Die in sensors.h deklarierte Sensors-HAL-Schnittstelle stellt die Schnittstelle zwischen dem Android- Framework und der hardwarespezifischen Software dar. Eine HAL-Implementierung muss jede in sensors.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 fest, z. B. Abtastfrequenz und maximale Berichtslatenz. -
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 geschehen ist. -
poll- Gibt verfügbare Sensorereignisse zurück.
Die Implementierung muss Thread-sicher sein und zulassen, dass diese Funktionen von verschiedenen Threads aufgerufen werden.
Die Schnittstelle definiert auch 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 unter sensors.h weitere Informationen zu diesen Typen.
get_sensors_list(Liste)
int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);
Stellt die Liste der vom HAL implementierten Sensoren bereit. Siehe sensor_t für Details darüber, wie die Sensoren definiert sind.
Die Reihenfolge, in der die Sensoren in der Liste erscheinen, ist die Reihenfolge, in der die Sensoren an die Anwendungen gemeldet werden. Normalerweise erscheinen die Basissensoren zuerst, gefolgt von den zusammengesetzten Sensoren.
Wenn mehrere Sensoren den gleichen Sensortyp und die gleiche Aufweckeigenschaft haben, wird der erste in der Liste als „Standard“-Sensor bezeichnet. Es ist derjenige, der von getDefaultSensor(int sensorType, bool wakeUp) .
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 zu aktivierenden/deaktivierenden Sensors. 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 den Sensor zu deaktivieren.
One-Shot-Sensoren deaktivieren sich automatisch beim Empfang eines Ereignisses und müssen noch akzeptieren, dass sie durch einen Aufruf von activate(..., enabled=0) deaktiviert werden.
Non-Wake-up-Sensoren verhindern niemals, dass das SoC in den Suspend-Modus wechselt; das heißt, die HAL soll keine partielle Wecksperre für Anwendungen halten.
Wake-up-Sensoren können bei kontinuierlicher Bereitstellung von Ereignissen verhindern, dass das SoC in den Suspend-Modus wechselt, aber wenn kein Ereignis übermittelt werden muss, muss die teilweise Wake-Lock aufgehoben werden.
Wenn enabled “ 1 ist und der Sensor bereits aktiviert ist, ist diese Funktion ohne Operation und erfolgreich.
Wenn enabled 0 ist und der Sensor bereits deaktiviert ist, ist diese Funktion ohne Operation 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 dazu führen, dass Sensormessungen verloren gehen: Der Übergang von einer Abtastrate zur anderen kann keine verlorenen Ereignisse verursachen, ebenso wenig wie der Übergang von einer hohen maximalen Berichtslatenz zu einer niedrigen maximale Meldelatenz.
sensor_handle ist das Handle des zu konfigurierenden Sensors.
flags wird derzeit nicht verwendet.
sampling_period_ns ist die Abtastperiode, in der der Sensor laufen soll, in Nanosekunden. 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, Abtastperiode)
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 aufgerufen. Stattdessen wird die batch aufgerufen, um den Parameter „ sampling_period_ns “ festzulegen.
In HAL Version 1.0 wurde setDelay anstelle von batch verwendet, um sample_period_ns festzulegen.
Spülung (Sensor)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Fügt am Ende des Hardware-FIFOs für den angegebenen Sensor ein Flush-Complete-Ereignis hinzu und löscht den FIFO; diese Ereignisse werden wie gewöhnlich geliefert (dh: als ob die maximale Berichtslatenzzeit abgelaufen wäre) und aus dem FIFO entfernt.
Das Flush geschieht asynchron (dh: diese Funktion muss sofort zurückkehren). Wenn die Implementierung einen einzelnen FIFO für mehrere Sensoren verwendet, wird dieser FIFO geleert und das Leerungs-Abgeschlossen-Ereignis 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 die flush trotzdem erfolgreich sein und ein Spülungs-Abgeschlossen-Ereignis für diesen Sensor senden. Dies gilt für alle Sensoren außer One-Shot-Sensoren.
Wenn das flush aufgerufen wird, muss, selbst wenn bereits ein Spülereignis für diesen Sensor im FIFO vorhanden ist, ein zusätzliches Ereignis erstellt und am Ende des FIFO hinzugefügt werden, und das FIFO muss geleert werden. Die Anzahl der flush Aufrufe muss gleich der Anzahl der erstellten Flush-Complete-Ereignisse sein.
flush gilt nicht für One-Shot- Sensoren; Wenn sich sensor_handle auf einen One-Shot-Sensor bezieht, muss flush -EINVAL und darf kein Metadatenereignis zum vollständigen Flush generieren.
Diese Funktion gibt bei Erfolg 0 zurück, -EINVAL , wenn der angegebene Sensor ein One-Shot-Sensor ist oder nicht aktiviert wurde, und 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 ausgefüllt wird. Diese Funktion muss blockieren, bis Ereignisse verfügbar sind. Es gibt die Anzahl der gelesenen Ereignisse bei Erfolg oder eine negative Fehlernummer im Fehlerfall zurück.
Die Anzahl der in data zurückgegebenen Ereignisse muss kleiner oder gleich dem count -Argument sein. Diese Funktion darf niemals 0 (kein Ereignis) zurückgeben.
Anruffolge
Wenn das Gerät bootet, 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 aufgerufen werden, auch wenn keine Sensoren aktiviert sind.
Sensoren_Modul_t
sensors_module_t ist der Typ, der verwendet wird, um das Android-Hardwaremodul für die Sensoren zu erstellen. Die Implementierung der HAL muss ein Objekt HAL_MODULE_INFO_SYM dieses Typs definieren, um die get_sensors_list- Funktion 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 .
sensor_poll_device_t / sensors_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 der HAL.
sensor_t
sensor_t repräsentiert einen Android-Sensor . Hier sind einige der wichtigsten Felder:
name: Eine für den Benutzer sichtbare Zeichenfolge, die den Sensor darstellt. Diese Zeichenfolge enthält häufig den Teilenamen des zugrunde liegenden Sensors, den Typ des Sensors 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. Siehe die Erklärung des Sensortyps in Was sind Android-Sensoren? Weitere Einzelheiten finden Sie unter Sensortypen für offizielle Sensortypen. Bei nicht offiziellen Sensortypen muss der type mit SENSOR_TYPE_DEVICE_PRIVATE_BASE
stringType: Der Typ des Sensors als String. Wenn der Sensor einen offiziellen Typ hat, stellen Sie ihn auf SENSOR_STRING_TYPE_* ein. 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 stringType=”com.fictional_company.cool_product.unicorn_detector” . Der stringType wird verwendet, um nicht offizielle Sensortypen eindeutig zu identifizieren. Weitere Informationen zu Typen und Zeichenfolgentypen finden Sie unter sensors.h .
requiredPermission: 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. Einige Sensortypen wie der Herzfrequenzsensor haben eine zwingend requiredPermission Berechtigung . Alle Sensoren, die sensible Benutzerinformationen (z. B. die Herzfrequenz) liefern, müssen durch eine Berechtigung geschützt werden.
flags: Flags für diesen Sensor, die den Meldemodus des Sensors definieren und ob der Sensor ein Wecksensor ist oder nicht. Beispielsweise hat ein One-Shot- 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 [-maxRange; maxRange] . Beachten Sie, dass dies bedeutet, dass die Gesamtreichweite des Sensors im allgemeinen Sinne 2*maxRange . Meldet der Sensor Werte über mehrere Achsen, gilt der Bereich für jede Achse. Ein „+/- 2g“ Beschleunigungssensor meldet maxRange = 2*9.81 = 2g .
Auflösung: Der kleinste Wertunterschied, den der Sensor messen kann. Normalerweise basierend auf maxRange und der Anzahl der Bits in der Messung berechnet.
power: Die Energiekosten für die Aktivierung des Sensors in Milliampere. Dies ist fast immer mehr als die im Datenblatt des zugrunde liegenden Sensors angegebene Leistungsaufnahme. Siehe Basissensoren != physikalische Sensoren für weitere Details und siehe Leistungsmessungsverfahren für Details zum Messen des Stromverbrauchs eines Sensors. Wenn der Stromverbrauch des Sensors davon abhängt, ob sich das Gerät bewegt, ist der Stromverbrauch während der Bewegung derjenige, der im power angegeben ist.
minDelay: Bei kontinuierlichen Sensoren die Abtastperiode in Mikrosekunden, die der schnellsten vom Sensor unterstützten Rate entspricht. Einzelheiten 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-Mode-Sensoren muss minDelay , sofern nicht anders angegeben, 0 sein. Für One-Shot-Sensoren muss es -1 sein.
maxDelay: Für kontinuierliche und On-Change-Sensoren die Abtastperiode in Mikrosekunden, die der langsamsten Rate entspricht, die der Sensor unterstützt. Einzelheiten 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 es einen dedizierten FIFO für diesen Sensor gibt, dann 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 können. Dies 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 Einzelheiten finden Sie unter Stapelverarbeitung .
Bei Sensoren mit offiziellem Sensortyp werden einige Felder durch das Framework überschrieben. Beispielsweise müssen Beschleunigungssensoren einen kontinuierlichen Berichtsmodus haben, und Herzfrequenzmonitore müssen durch die SENSOR_PERMISSION_BODY_SENSORS geschützt werden.
Sensoren_Ereignis_t
Sensorereignisse, die von Android-Sensoren generiert und über die Abfragefunktion gemeldet werden, sind vom type sensors_event_t . Hier sind einige wichtige Felder von sensors_event_t :
version: Muss sizeof sein sizeof(struct sensors_event_t)
sensor: Das Handle des Sensors, der das Ereignis generiert hat, wie durch sensor_t.handle definiert.
type: Der Sensortyp des Sensors, der das Ereignis generiert hat, wie durch sensor_t.type definiert.
timestamp: Der Zeitstempel des Ereignisses in Nanosekunden. Dies ist die Zeit, zu der das Ereignis stattfand (ein Schritt wurde gemacht oder eine Beschleunigungsmessung durchgeführt), nicht die Zeit, zu der das Ereignis gemeldet wurde. timestamp muss mit der elapsedRealtimeNano Clock synchronisiert werden und bei kontinuierlichen Sensoren muss der Jitter gering sein. Die Zeitstempelfilterung ist manchmal erforderlich, um die CDD-Anforderungen zu erfüllen, da die Verwendung nur der SoC-Interruptzeit zum Setzen der Zeitstempel einen zu hohen Jitter verursacht und die Verwendung nur der Sensorchipzeit zum Setzen der Zeitstempel eine Desynchronisation von der verstrichenen Echtzeit- elapsedRealtimeNano verursachen kann, da die Sensoruhr driftet.
Daten und überlappende Felder: Die vom Sensor gemessenen Werte. Die Bedeutung und Einheiten dieser Felder sind für jeden Sensortyp spezifisch. Siehe sensors.h und die Definition der verschiedenen Sensortypen für eine Beschreibung der Datenfelder. 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 durchgeleitet und erscheint auf der SDK-Ebene als Genauigkeitswert. Für diese Sensoren wird die Tatsache, dass das Statusfeld gesetzt werden muss, in ihrer Sensortypdefinition erwähnt.
Metadaten-Flush-Ereignisse abgeschlossen
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 besitzen folgende Felder:
Version: Muss META_DATA_VERSION sein
Typ: Muss SENSOR_TYPE_META_DATA sein
sensor, reserviert und timestamp : 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 repräsentieren den Abschluss des Spülens eines Sensor-FIFO. Wenn meta_data.what=META_DATA_FLUSH_COMPLETE , muss meta_data.sensor auf den Griff des Sensors gesetzt werden, der gespült wurde. Sie werden nur dann generiert, wenn an einem Sensor eine flush wird. Weitere Informationen finden Sie im Abschnitt über die Spülfunktion .