Sensoren HAL 1.0

Die in sensor.h deklarierte HAL-Schnittstelle von Sensors stellt die Schnittstelle zwischen dem Android- Framework und der hardwarespezifischen Software dar. Eine HAL-Implementierung muss jede in sensor.h deklarierte Funktion definieren. Die Hauptfunktionen sind:

  • get_sensors_list – Gibt die Liste aller Sensoren zurück.
  • activate – Startet oder stoppt einen Sensor.
  • batch – Legt die Parameter eines Sensors wie die Abtastfrequenz und die maximale Berichtslatenz fest.
  • setDelay – Wird nur in HAL Version 1.0 verwendet. Legt die Abtastfrequenz für einen bestimmten Sensor fest.
  • flush – Leert den FIFO des angegebenen Sensors und meldet ein Flush-Complete-Ereignis, wenn dies erledigt ist.
  • poll – Gibt verfügbare Sensorereignisse zurück.

Die Implementierung muss Thread-sicher sein und den Aufruf dieser Funktionen aus verschiedenen Threads ermöglichen.

Die Schnittstelle definiert außerdem mehrere Typen, die von diesen Funktionen verwendet werden. Die Haupttypen sind:

  • sensors_module_t
  • sensors_poll_device_t
  • sensor_t
  • sensors_event_t

Zusätzlich zu den folgenden Abschnitten finden Sie weitere Informationen zu diesen Typen in „sensors.h“ .

get_sensors_list(list)

int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
  const** list);

Stellt die Liste der vom HAL implementierten Sensoren bereit. Einzelheiten zur Definition der Sensoren finden Sie unter sensor_t .

Die Reihenfolge, in der die Sensoren in der Liste erscheinen, ist die Reihenfolge, in der die Sensoren den Anwendungen gemeldet werden. Normalerweise erscheinen zuerst die Basissensoren, gefolgt von den Verbundsensoren.

Wenn mehrere Sensoren den gleichen Sensortyp und die gleiche Aktivierungseigenschaft haben, wird der erste in der Liste als „Standard“-Sensor bezeichnet. Es ist das, was von getDefaultSensor(int sensorType, bool wakeUp) zurückgegeben wird.

Diese Funktion gibt die Anzahl der Sensoren in der Liste zurück.

aktivieren(Sensor, wahr/falsch)

int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int
  enabled);

Aktiviert oder deaktiviert einen Sensor.

sensor_handle ist das Handle des Sensors, der aktiviert/deaktiviert werden soll. Das Handle eines Sensors wird durch das handle Feld seiner sensor_t- Struktur definiert.

enabled wird auf 1 gesetzt, um den Sensor zu aktivieren, oder auf 0, um ihn zu deaktivieren.

One-Shot-Sensoren deaktivieren sich automatisch, wenn sie ein Ereignis empfangen, und sie müssen dennoch akzeptieren, dass sie durch einen Aufruf von activate(..., enabled=0) deaktiviert werden.

Nicht-Wake-up-Sensoren verhindern niemals, dass der SoC in den Suspend-Modus wechselt. Das heißt, der HAL darf im Namen von Anwendungen keinen teilweisen Wake-Lock halten.

Wenn Wake-up-Sensoren kontinuierlich Ereignisse liefern, können sie verhindern, dass der SoC in den Suspend-Modus wechselt. Wenn jedoch kein Ereignis übermittelt werden muss, muss die teilweise Wake-Sperre aufgehoben werden.

Wenn enabled 1 ist und der Sensor bereits aktiviert ist, ist diese Funktion ein No-Op und erfolgreich.

Wenn enabled “ 0 ist und der Sensor bereits deaktiviert ist, ist diese Funktion ein No-Op und erfolgreich.

Diese Funktion gibt bei Erfolg 0 und andernfalls eine negative Fehlernummer zurück.

Batch (Sensor, Flags, Abtastzeitraum, maximale Berichtslatenz)

int (*batch)(
     struct sensors_poll_device_1* dev,
     int sensor_handle,
     int flags,
     int64_t sampling_period_ns,
     int64_t max_report_latency_ns);

Legt die Parameter eines Sensors fest, einschließlich der Abtastfrequenz und der maximalen Berichtslatenz . Diese Funktion kann aufgerufen werden, während der Sensor aktiviert ist. In diesem Fall darf sie nicht zum Verlust von Sensormessungen führen: Der Übergang von einer Abtastrate zur anderen kann nicht zum Verlust von Ereignissen führen, ebenso wenig wie der Übergang von einer hohen maximalen Berichtslatenz zu einer niedrigen maximale Berichtslatenz.

sensor_handle ist das Handle des zu konfigurierenden Sensors.

flags wird derzeit nicht verwendet.

sampling_period_ns ist die Abtastperiode in Nanosekunden, mit der der Sensor laufen soll. Weitere Einzelheiten finden Sie unter „sampling_period_ns“ .

max_report_latency_ns ist die maximale Zeit in Nanosekunden, um die Ereignisse verzögert werden können, bevor sie über die HAL gemeldet werden. Weitere Einzelheiten finden Sie im Absatz „max_report_latency_ns“ .

Diese Funktion gibt bei Erfolg 0 und andernfalls eine negative Fehlernummer zurück.

setDelay(Sensor, Abtastzeitraum)

int (*setDelay)(
     struct sensors_poll_device_t *dev,
     int sensor_handle,
     int64_t sampling_period_ns);

Nach HAL-Version 1.0 ist diese Funktion veraltet und wird nie mehr aufgerufen. Stattdessen wird die batch Funktion aufgerufen, um den Parameter sampling_period_ns festzulegen.

In HAL Version 1.0 wurde setDelay anstelle von Batch verwendet, um sampling_period_ns festzulegen.

bündig (Sensor)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

Fügen Sie am Ende des Hardware-FIFO für den angegebenen Sensor ein Flush-Complete-Ereignis hinzu und leeren Sie den FIFO. Diese Ereignisse werden wie gewohnt übermittelt (d. h. als ob die maximale Berichtslatenz abgelaufen wäre) und aus dem FIFO entfernt.

Der Flush erfolgt asynchron (d. h. diese Funktion muss sofort zurückkehren). Wenn die Implementierung einen einzelnen FIFO für mehrere Sensoren verwendet, wird dieser FIFO geleert und das Ereignis „Flush Complete“ wird nur für den angegebenen Sensor hinzugefügt.

Wenn der angegebene Sensor keinen FIFO hat (keine Pufferung möglich) oder wenn der FIFO zum Zeitpunkt des Aufrufs leer war, muss flush dennoch erfolgreich sein und ein Flush-Complete-Ereignis für diesen Sensor senden. Dies gilt für alle Sensoren außer One-Shot-Sensoren.

Wenn flush aufgerufen wird, muss, selbst wenn bereits ein Flush-Ereignis im FIFO für diesen Sensor vorhanden ist, ein zusätzliches Ereignis erstellt und am Ende des FIFO hinzugefügt werden, und der FIFO muss geleert werden. Die Anzahl der flush Aufrufe muss der Anzahl der erstellten Flush-Complete-Ereignisse entsprechen.

flush gilt nicht für One-Shot- Sensoren; Wenn sich sensor_handle auf einen One-Shot-Sensor bezieht, muss flush -EINVAL zurückgeben und darf kein Flush-Complete-Metadatenereignis generieren.

Diese Funktion gibt bei Erfolg 0 zurück, -EINVAL wenn der angegebene Sensor ein One-Shot-Sensor ist oder nicht aktiviert wurde, andernfalls eine negative Fehlernummer.

Umfrage()

int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
  count);

Gibt ein Array von Sensordaten zurück, indem das data gefüllt wird. Diese Funktion muss blockieren, bis Ereignisse verfügbar sind. Bei Erfolg wird die Anzahl der gelesenen Ereignisse zurückgegeben, im Fehlerfall eine negative Fehlernummer.

Die Anzahl der in data zurückgegebenen Ereignisse muss kleiner oder gleich dem count sein. Diese Funktion darf niemals 0 (kein Ereignis) zurückgeben.

Reihenfolge der Anrufe

Beim Booten des Geräts wird get_sensors_list aufgerufen.

Wenn ein Sensor aktiviert wird, wird die batch Funktion mit den angeforderten Parametern aufgerufen, gefolgt von activate(..., enable=1) .

Beachten Sie, dass in HAL-Version 1_0 die Reihenfolge umgekehrt war: activate wurde zuerst aufgerufen, gefolgt von set_delay .

Wenn sich die angeforderten Eigenschaften eines Sensors ändern, während er aktiviert ist, wird die batch Funktion aufgerufen.

flush kann jederzeit aufgerufen werden, auch bei nicht aktivierten Sensoren (in diesem Fall muss -EINVAL zurückgegeben werden)

Wenn ein Sensor deaktiviert wird, wird activate(..., enable=0) aufgerufen.

Parallel zu diesen Aufrufen wird die poll Funktion wiederholt aufgerufen, um Daten anzufordern. poll kann auch dann aufgerufen werden, wenn keine Sensoren aktiviert sind.

sensoren_module_t

sensors_module_t ist der Typ, der zum Erstellen des Android-Hardwaremoduls für die Sensoren verwendet wird. Die Implementierung der HAL muss ein Objekt HAL_MODULE_INFO_SYM dieses Typs definieren, um die Funktion get_sensors_list verfügbar zu machen. Weitere Informationen finden Sie in der Definition von sensors_module_t in „sensors.h“ und in der Definition von „ hw_module_t .

sensoren_poll_device_t / sensoren_poll_device_1_t

sensors_poll_device_1_t enthält den Rest der oben definierten Methoden: activate , batch , flush und poll . Sein common Feld (vom Typ hw_device_t ) definiert die Versionsnummer des HAL.

sensor_t

sensor_t repräsentiert einen Android-Sensor . Hier sind einige seiner wichtigen Bereiche:

Name: Eine für den Benutzer sichtbare Zeichenfolge, die den Sensor darstellt. Diese Zeichenfolge enthält häufig den Teilnamen des zugrunde liegenden Sensors, den Sensortyp und ob es sich um einen Wecksensor handelt. Zum Beispiel „LIS2HH12 Accelerometer“, „MAX21000 Unkalibriertes Gyroskop“, „BMP280 Wake-up Barometer“, „MPU6515 Game Rotation Vector“

Handle: Die Ganzzahl, die verwendet wird, um auf den Sensor zu verweisen, wenn er sich bei ihm registriert oder Ereignisse daraus generiert.

Typ: Der Typ des Sensors. Weitere Informationen zum Sensortyp finden Sie unter Was sind Android-Sensoren? Weitere Einzelheiten finden Sie unter Sensortypen für offizielle Sensortypen. Bei nicht offiziellen Sensortypen muss type mit SENSOR_TYPE_DEVICE_PRIVATE_BASE beginnen

stringType: Der Typ des Sensors als String. Wenn der Sensor einen offiziellen Typ hat, setzen Sie ihn auf SENSOR_STRING_TYPE_* . Wenn der Sensor einen herstellerspezifischen Typ hat, muss stringType mit dem umgekehrten Domänennamen des Herstellers beginnen. Beispielsweise könnte ein vom Cool-Product- Team bei Fictional-Company definierter Sensor (z. B. ein Einhorndetektor) stringType=”com.fictional_company.cool_product.unicorn_detector” verwenden. Der stringType wird zur eindeutigen Identifizierung nicht offizieller Sensortypen verwendet. Weitere Informationen zu Typen und Zeichenfolgentypen finden Sie unter „sensors.h“ .

requirePermission: Eine Zeichenfolge, die die Berechtigung darstellt, die Anwendungen besitzen müssen, um den Sensor zu sehen, sich bei ihm zu registrieren und seine Daten zu empfangen. Eine leere Zeichenfolge bedeutet, dass Anwendungen keine Berechtigung benötigen, um auf diesen Sensor zuzugreifen. Für einige Sensortypen wie den Herzfrequenzmesser ist eine zwingend erforderliche requiredPermission . Alle Sensoren, die sensible Benutzerinformationen (z. B. die Herzfrequenz) liefern, müssen durch eine Erlaubnis geschützt sein.

Flags: Flags für diesen Sensor, die den Berichtsmodus des Sensors definieren und ob der Sensor ein Wecksensor ist oder nicht. Beispielsweise verfügt ein One-Shot-Wecksensor über flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . Die Bits des Flags, die in der aktuellen HAL-Version nicht verwendet werden, müssen auf 0 belassen werden.

maxRange: Der maximale Wert, den der Sensor melden kann, in derselben Einheit wie die gemeldeten Werte. Der Sensor muss in der Lage sein, Werte ohne Sättigung innerhalb von [-maxRange; maxRange] . Beachten Sie, dass dies bedeutet, dass die Gesamtreichweite des Sensors im allgemeinen Sinne 2*maxRange beträgt. Wenn der Sensor Werte über mehrere Achsen meldet, gilt der Bereich für jede Achse. Beispielsweise meldet ein „+/- 2g“-Beschleunigungsmesser maxRange = 2*9.81 = 2g .

Auflösung: Der kleinste Wertunterschied, den der Sensor messen kann. Wird normalerweise basierend auf maxRange und der Anzahl der Bits in der Messung berechnet.

Leistung: Die Stromkosten für die Aktivierung des Sensors in Milliampere. Dies ist fast immer mehr als der im Datenblatt des zugrunde liegenden Sensors angegebene Stromverbrauch. Weitere Einzelheiten finden Sie unter Basissensoren != physikalische Sensoren und unter Leistungsmessprozess für Einzelheiten zur Messung des Stromverbrauchs eines Sensors. Wenn der Stromverbrauch des Sensors davon abhängt, ob sich das Gerät bewegt, wird der Stromverbrauch während der Bewegung im power angegeben.

minDelay: Bei kontinuierlichen Sensoren die Abtastperiode in Mikrosekunden, die der schnellsten Rate entspricht, die der Sensor unterstützt. Weitere Informationen zur Verwendung dieses Werts finden Sie unter „sampling_period_ns“ . Beachten Sie, dass minDelay in Mikrosekunden ausgedrückt wird, während sampling_period_ns in Nanosekunden angegeben wird. Für On-Change- und Special-Reporting-Modus-Sensoren muss minDelay , sofern nicht anders angegeben, 0 sein. Für One-Shot-Sensoren muss es -1 sein.

maxDelay: Bei kontinuierlichen und On-Change-Sensoren die Abtastperiode in Mikrosekunden, die der langsamsten Rate entspricht, die der Sensor unterstützt. Weitere Informationen zur Verwendung dieses Werts finden Sie unter „sampling_period_ns“ . Beachten Sie, dass maxDelay in Mikrosekunden ausgedrückt wird, während sampling_period_ns in Nanosekunden angegeben wird. Für Spezial- und One-Shot-Sensoren muss maxDelay 0 sein.

fifoReservedEventCount: Die Anzahl der für diesen Sensor im Hardware-FIFO reservierten Ereignisse. Wenn für diesen Sensor ein dedizierter FIFO vorhanden ist, ist fifoReservedEventCount die Größe dieses dedizierten FIFO. Wenn der FIFO mit anderen Sensoren geteilt wird, ist fifoReservedEventCount die Größe des Teils des FIFO, der für diesen Sensor reserviert ist. Auf den meisten Shared-FIFO-Systemen und auf Systemen ohne Hardware-FIFO ist dieser Wert 0.

fifoMaxEventCount: Die maximale Anzahl von Ereignissen, die in den FIFOs für diesen Sensor gespeichert werden konnten. Dieser ist immer größer oder gleich fifoReservedEventCount . Dieser Wert wird verwendet, um abzuschätzen, wie schnell der FIFO voll wird, wenn er sich mit einer bestimmten Rate beim Sensor registriert, vorausgesetzt, dass keine anderen Sensoren aktiviert sind. Auf Systemen ohne Hardware-FIFO ist fifoMaxEventCount 0. Weitere Informationen finden Sie unter Batchverarbeitung .

Bei Sensoren mit offiziellem Sensortyp werden einige Felder vom Framework überschrieben. Beschleunigungssensoren müssen beispielsweise einen kontinuierlichen Berichtsmodus haben und Herzfrequenzmesser müssen durch die Berechtigung SENSOR_PERMISSION_BODY_SENSORS geschützt sein.

sensoren_event_t

Von Android-Sensoren generierte und über die Umfragefunktion gemeldete Sensorereignisse sind vom type sensors_event_t . Hier sind einige wichtige Felder von sensors_event_t :

Version: Muss sizeof(struct sensors_event_t) sein

sensor: Das Handle des Sensors, der das Ereignis generiert hat, wie durch sensor_t.handle definiert.

Typ: Der Sensortyp des Sensors, der das Ereignis generiert hat, wie durch sensor_t.type definiert.

Zeitstempel: Der Zeitstempel des Ereignisses in Nanosekunden. Dabei handelt es sich um den Zeitpunkt, zu dem das Ereignis aufgetreten ist (ein Schritt wurde ausgeführt oder eine Beschleunigungsmessung durchgeführt), nicht um den Zeitpunkt, zu dem das Ereignis gemeldet wurde. timestamp muss mit der elapsedRealtimeNano -Uhr synchronisiert sein und bei kontinuierlichen Sensoren muss der Jitter gering sein. Manchmal ist eine Zeitstempelfilterung erforderlich, um die CDD-Anforderungen zu erfüllen, da die alleinige Verwendung der SoC-Interruptzeit zum Festlegen der Zeitstempel einen zu hohen Jitter verursacht und die alleinige Verwendung der Sensorchipzeit zum Festlegen der Zeitstempel zu einer Desynchronisierung mit der elapsedRealtimeNano -Uhr führen kann, wie z Die Uhr des Sensors driftet.

Daten und überlappende Felder: Die vom Sensor gemessenen Werte. Die Bedeutung und Einheiten dieser Felder sind für jeden Sensortyp spezifisch. Eine Beschreibung der Datenfelder finden Sie in „sensors.h“ und in der Definition der verschiedenen Sensortypen . Bei einigen Sensoren wird die Genauigkeit der Messwerte auch als Teil der Daten über ein status gemeldet. Dieses Feld wird nur für diese ausgewählten Sensortypen weitergeleitet und erscheint auf der SDK-Ebene als Genauigkeitswert. Bei diesen Sensoren wird in der Definition des Sensortyps erwähnt, dass das Statusfeld festgelegt werden muss.

Metadaten-Flush-Abschlussereignisse

Metadatenereignisse haben den gleichen Typ wie normale Sensorereignisse: sensors_event_meta_data_t = sensors_event_t . Sie werden zusammen mit anderen Sensorereignissen per Abfrage zurückgegeben. Sie verfügen über folgende Bereiche:

Version: Muss META_DATA_VERSION sein

Typ: Muss SENSOR_TYPE_META_DATA sein

Sensor, reserviert und Zeitstempel : Muss 0 sein

meta_data.what: Enthält den Metadatentyp für dieses Ereignis. Derzeit gibt es einen einzigen gültigen Metadatentyp: META_DATA_FLUSH_COMPLETE .

META_DATA_FLUSH_COMPLETE Ereignisse stellen den Abschluss der Spülung eines Sensor-FIFOs dar. Wenn meta_data.what=META_DATA_FLUSH_COMPLETE ist, muss meta_data.sensor auf das Handle des Sensors gesetzt werden, der geleert wurde. Sie werden nur dann generiert, wenn flush an einem Sensor aufgerufen wird. Weitere Informationen finden Sie im Abschnitt zur Spülfunktion .