Die Sensors HAL-Schnittstelle, die in sensors.h deklariert ist, 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
: Hiermit werden die Parameter eines Sensors wie die Abtastrate und die maximale Berichtslatenz festgelegt.setDelay
– Nur in HAL-Version 1.0 verwendet. Legt die Abtastrate für einen bestimmten Sensor fest.flush
– Der FIFO des angegebenen Sensors wird geleert und es wird ein Ereignis ausgegeben, wenn der Vorgang abgeschlossen ist.poll
– Gibt verfügbare Sensorereignisse zurück.
Die Implementierung muss threadsicher sein und es ermöglichen, dass diese Funktionen von verschiedenen Threads aufgerufen werden.
Die Schnittstelle definiert auch mehrere Typen, die von diesen Funktionen verwendet werden. Die wichtigsten Typen sind:
sensors_module_t
sensors_poll_device_t
sensor_t
sensors_event_t
Weitere Informationen zu diesen Typen finden Sie in sensors.h und in den folgenden Abschnitten.
get_sensors_list(list)
int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t const** list);
Liste der von der HAL implementierten Sensoren. Weitere Informationen zur Definition der Sensoren finden Sie unter sensor_t.
Die Reihenfolge, in der die Sensoren in der Liste angezeigt werden, ist die Reihenfolge, in der sie an die Anwendungen gemeldet werden. Normalerweise werden zuerst die Basissensoren angezeigt, gefolgt von den zusammengesetzten Sensoren.
Wenn mehrere Sensoren denselben Sensortyp und dieselbe Weckeigenschaft haben, wird der erste in der Liste als „Standardsensor“ bezeichnet. Es ist der Wert, der von getDefaultSensor(int sensorType, bool wakeUp)
zurückgegeben wird.
Diese Funktion gibt die Anzahl der Sensoren in der Liste zurück.
activate(sensor, true/false)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Aktiviert oder deaktiviert einen Sensor.
sensor_handle
ist der Griff des Sensors, der aktiviert/deaktiviert werden soll. Der Handle eines Sensors wird durch das Feld handle
der Struktur sensor_t definiert.
Wenn enabled
auf „1“ gesetzt ist, wird der Sensor aktiviert. Ist er auf „0“ gesetzt, wird er deaktiviert.
Einmaleinsende-Sensoren deaktivieren sich automatisch, wenn sie ein Ereignis erhalten. Sie müssen jedoch trotzdem über einen Aufruf von activate(...,
enabled=0)
deaktiviert werden.
Sensoren, die nicht zum Aktivieren dienen, verhindern nie, dass das SoC in den Ruhemodus wechselt. Das heißt, die HAL darf im Namen von Anwendungen keine teilweise Wake-Lock halten.
Wenn Wecksensoren kontinuierlich Ereignisse senden, kann das SoC nicht in den Ruhemodus versetzt werden. Wenn jedoch kein Ereignis gesendet werden muss, muss die teilweise Wecksperre aufgehoben werden.
Wenn enabled
= 1 ist und der Sensor bereits aktiviert ist, wird diese Funktion nicht ausgeführt und der Vorgang ist erfolgreich.
Wenn enabled
= 0 ist und der Sensor bereits deaktiviert ist, führt diese Funktion keine Aktion aus und wird erfolgreich abgeschlossen.
Diese Funktion gibt bei Erfolg den Wert 0 zurück, andernfalls eine negative Fehlernummer.
batch(sensor, flags, sampling period, maximum report latency)
int (*batch)( struct sensors_poll_device_1* dev, int sensor_handle, int flags, int64_t sampling_period_ns, int64_t max_report_latency_ns);
Hier legen Sie die Parameter eines Sensors fest, einschließlich Abtastrate und maximaler Berichtslatenz. Diese Funktion kann aufgerufen werden, während der Sensor aktiviert ist. In diesem Fall dürfen keine Sensormessungen verloren gehen: Der Wechsel von einer zu einer anderen Abtastrate darf keine Ereignisse verlieren. Das gilt auch für den Wechsel von einer hohen maximalen Berichtslatenz zu einer niedrigen maximalen Berichtslatenz.
sensor_handle
ist der Handle des zu konfigurierenden Sensors.
flags
wird derzeit nicht verwendet.
sampling_period_ns
ist die Abtastzeit, mit der der Sensor ausgeführt werden soll, in Nanosekunden. Weitere Informationen finden Sie unter sampling_period_ns.
max_report_latency_ns
ist die maximale Zeit, um die Ereignisse verzögert werden können, bevor sie über die HAL gemeldet werden, in Nanosekunden. Weitere Informationen finden Sie im Abschnitt max_report_latency_ns.
Diese Funktion gibt bei Erfolg den Wert 0 zurück, andernfalls eine negative Fehlernummer.
setDelay(sensor, sampling period)
int (*setDelay)( struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns);
Nach HAL-Version 1.0 wird diese Funktion nicht mehr unterstützt und nicht mehr aufgerufen.
Stattdessen wird die Funktion batch
aufgerufen, um den Parameter sampling_period_ns
festzulegen.
In HAL-Version 1.0 wurde „setDelay“ anstelle von „batch“ verwendet, um sampling_period_ns festzulegen.
flush(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 vollständiges Flush-Ereignis hinzu und leeren Sie den FIFO. Diese Ereignisse werden wie gewohnt gesendet (d. h., als wäre die maximale Berichtslatenz abgelaufen) und aus dem FIFO entfernt.
Das Leeren erfolgt asynchron (d.h., diese Funktion muss sofort zurückgeben). Wenn in der Implementierung ein einzelner FIFO für mehrere Sensoren verwendet wird, 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 der FIFO zum Zeitpunkt des Aufrufs leer war, muss flush
trotzdem erfolgreich sein und ein Ereignis vom Typ „Flush complete“ für diesen Sensor senden. Das gilt für alle Sensoren mit Ausnahme von Einmalsensoren.
Wenn flush
aufgerufen wird, muss ein zusätzliches Ereignis erstellt und dem Ende des FIFO für diesen Sensor hinzugefügt werden, auch wenn sich bereits ein Flush-Ereignis im FIFO für diesen Sensor befindet. Außerdem muss der FIFO geleert werden. Die Anzahl der flush
-Aufrufe muss der Anzahl der erstellten Ereignisse vom Typ „Flush complete“ entsprechen.
flush
gilt nicht für One-Shot-Sensoren. Wenn sensor_handle
sich auf einen One-Shot-Sensor bezieht, muss flush
-EINVAL
zurückgeben und darf kein Ereignis vom Typ „Metadaten vollständig löschen“ generieren.
Diese Funktion gibt bei Erfolg den Wert 0 zurück, -EINVAL
, wenn der angegebene Sensor ein Einmalsensor ist oder nicht aktiviert war, andernfalls eine negative Fehlernummer.
poll()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
count);
Gibt ein Array von Sensordaten zurück, indem das Argument data
ausgefüllt wird. Diese Funktion muss blockieren, bis Ereignisse verfügbar sind. Bei Erfolg wird die Anzahl der gelesenen Ereignisse zurückgegeben, bei einem Fehler eine negative Fehlernummer.
Die Anzahl der in data
zurückgegebenen Ereignisse muss kleiner oder gleich dem Argument count
sein. Diese Funktion darf niemals den Wert 0 (kein Ereignis) zurückgeben.
Aufrufabfolge
Beim Starten des Geräts wird get_sensors_list
aufgerufen.
Wenn ein Sensor aktiviert wird, wird die Funktion batch
mit den angeforderten Parametern und anschließend activate(..., enable=1)
aufgerufen.
In HAL-Version 1_0 war die Reihenfolge umgekehrt: 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 Funktion poll
wiederholt aufgerufen, um Daten anzufordern. poll
kann auch aufgerufen werden, wenn keine Sensoren aktiviert sind.
sensors_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 bereitzustellen. Weitere Informationen finden Sie in der Definition von sensors_module_t
in sensors.h und in der Definition von hw_module_t
.
sensors_poll_device_t / sensors_poll_device_1_t
sensors_poll_device_1_t
enthält die restlichen oben definierten Methoden: activate
, batch
, flush
und poll
. Das Feld common
vom Typ hw_device_t definiert die Versionsnummer der HAL.
sensor_t
sensor_t
steht für einen Android-Sensor. Hier sind einige der wichtigsten Felder:
name:Ein für Nutzer sichtbarer String, der den Sensor darstellt. Dieser String enthält häufig den Teilnamen des zugrunde liegenden Sensors, den Sensortyp und ob es sich um einen Wecksensor handelt. Beispiel: „LIS2HH12 Accelerometer“, „MAX21000 Uncalibrated Gyroscope“, „BMP280 Wake-up Barometer“, „MPU6515 Game Rotation Vector“
handle:Die Ganzzahl, die sich auf den Sensor bezieht, wenn er registriert oder Ereignisse von ihm generiert werden.
type:Der Sensortyp. Weitere Informationen finden Sie in der Erklärung zum Sensortyp unter Was sind Android-Sensoren? und unter Sensortypen. Bei nicht offiziellen Sensortypen muss type
mit SENSOR_TYPE_DEVICE_PRIVATE_BASE
beginnen.
stringType:Der Sensortyp als String. Wenn der Sensor einen offiziellen Typ hat, legen Sie SENSOR_STRING_TYPE_*
fest. Wenn der Sensor einen herstellerspezifischen Typ hat, muss stringType
mit dem umgekehrten Domainnamen des Herstellers beginnen. Beispielsweise könnte ein Sensor (z. B. ein Einhorn-Detektor), der vom Team Cooles Produkt des fiktiven Unternehmens Fictional-Company definiert wurde, stringType=”com.fictional_company.cool_product.unicorn_detector”
verwenden.
Die stringType
wird verwendet, um nicht offizielle Sensortypen eindeutig zu identifizieren. Weitere Informationen zu Typen und Stringtypen finden Sie in sensors.h.
requiredPermission:Ein String, der die Berechtigung darstellt, die Anwendungen benötigen, um den Sensor zu sehen, sich bei ihm zu registrieren und seine Daten zu empfangen. Ein leerer String bedeutet, dass Apps keine Berechtigung für den Zugriff auf diesen Sensor benötigen. Für einige Sensortypen wie den Herzfrequenzmesser ist eine requiredPermission
obligatorisch. Alle Sensoren, die sensible Nutzerdaten wie die Herzfrequenz erfassen, müssen durch eine Berechtigung geschützt sein.
flags:Flags für diesen Sensor, die den Meldemodus des Sensors und ob es sich um einen Wecksensor handelt, definieren. Ein Einmal-Wecksensor hat beispielsweise 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 bleiben.
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 Übersättigung innerhalb von [-maxRange; maxRange]
zu erfassen. Das bedeutet, dass der Gesamtbereich des Sensors im generischen Sinne 2*maxRange
ist. Wenn der Sensor Werte über mehrere Achsen meldet, gilt der Bereich für jede Achse. Ein Beschleunigungsmesser mit der Angabe „+/- 2 g“ meldet beispielsweise maxRange = 2*9.81 = 2g
.
Auflösung: Der kleinste Wertunterschied, den der Sensor messen kann.
Wird in der Regel anhand von maxRange
und der Anzahl der Bits in der Messung berechnet.
power:Die Leistungskosten für die Aktivierung des Sensors in Milliamperen.
Das ist fast immer höher als der im Datenblatt des zugrunde liegenden Sensors angegebene Stromverbrauch. Weitere Informationen finden Sie unter Basissensoren ≠ physische Sensoren und unter Prozess zur Leistungsmessung.
Wenn der Energieverbrauch des Sensors davon abhängt, ob sich das Gerät bewegt, wird der Energieverbrauch während der Bewegung im Feld power
erfasst.
minDelay:Bei kontinuierlichen Sensoren entspricht die Stichprobenzeit in Mikrosekunden der höchsten Rate, die der Sensor unterstützt. Weitere Informationen zur Verwendung dieses Werts finden Sie unter sampling_period_ns. Beachten Sie, dass minDelay
in Mikrosekunden und sampling_period_ns
in Nanosekunden angegeben wird. Bei Sensoren mit dem Modus „Bei Änderung“ und dem speziellen Berichtsmodus muss minDelay
, sofern nicht anders angegeben, 0 sein. Bei Einmalsensoren muss es -1 sein.
maxDelay:Bei kontinuierlichen und bei Änderungen ausgelösten Sensoren entspricht die Abtastzeit in Mikrosekunden der niedrigsten Rate, die der Sensor unterstützt. Weitere Informationen zur Verwendung dieses Werts finden Sie unter sampling_period_ns. Beachten Sie, dass maxDelay
in Mikrosekunden und sampling_period_ns
in Nanosekunden angegeben wird. Bei speziellen und Einmalsensoren muss maxDelay
0 sein.
fifoReservedEventCount:Die Anzahl der Ereignisse, die für diesen Sensor im Hardware-FIFO reserviert sind. Wenn es für diesen Sensor einen speziellen FIFO gibt, ist fifoReservedEventCount
die Größe dieses speziellen FIFO. Wenn der FIFO mit anderen Sensoren geteilt wird, ist fifoReservedEventCount
die Größe des für diesen Sensor reservierten Teils des FIFO. Bei den meisten Shared-FIFO-Systemen und bei 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. Dieser Wert ist immer größer oder gleich fifoReservedEventCount
. Mit diesem Wert wird geschätzt, wie schnell der FIFO bei einer bestimmten Registrierungsrate voll wird, vorausgesetzt, dass keine anderen Sensoren aktiviert sind. Bei Systemen ohne Hardware-FIFO ist fifoMaxEventCount
= 0. Weitere Informationen finden Sie unter Batch-Verarbeitung.
Bei Sensoren mit einem offiziellen Sensortyp werden einige Felder vom Framework überschrieben. Beispielsweise müssen Beschleunigungsmesser einen kontinuierlichen Berichtsmodus haben und Herzfrequenzmesser müssen durch die Berechtigung SENSOR_PERMISSION_BODY_SENSORS
geschützt werden.
sensors_event_t
Sensorereignisse, die von Android-Sensoren generiert und über die Funktion poll gemeldet werden, haben den Typ type sensors_event_t
. Hier sind einige wichtige Felder von sensors_event_t
:
version:Muss sizeof(struct sensors_event_t)
sein.
sensor:Der Handle des Sensors, der das Ereignis generiert hat, wie von sensor_t.handle
definiert.
type:Der Sensortyp des Sensors, der das Ereignis generiert hat, wie in sensor_t.type
definiert.
timestamp:Der Zeitstempel des Ereignisses in Nanosekunden. Das ist der Zeitpunkt, zu dem das Ereignis stattgefunden hat (ein Schritt wurde gemacht oder eine Beschleunigungsmessung durchgeführt), nicht der Zeitpunkt, zu dem das Ereignis erfasst wurde. timestamp
muss mit der elapsedRealtimeNano
-Taktzeit synchronisiert sein. 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-Unterbrechungszeit zum Festlegen der Zeitstempel zu einem zu hohen Jitter führt. Die Verwendung nur der Sensorchipzeit zum Festlegen der Zeitstempel kann zu einer Desynchronisierung von der elapsedRealtimeNano
-Uhr führen, da die Sensoruhr driftet.
Daten und sich überschneidende Felder:Die vom Sensor gemessenen Werte. Die Bedeutung und die 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
-Feld angegeben. Dieses Feld wird nur für die ausgewählten Sensortypen übergeben 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-Ereignisse
Metadatenereignisse haben denselben Typ wie normale Sensorereignisse: sensors_event_meta_data_t = sensors_event_t
. Sie werden zusammen mit anderen Sensorereignissen über die Abfrage zurückgegeben. Sie enthalten die folgenden Felder:
version:Muss META_DATA_VERSION
sein.
type:Muss SENSOR_TYPE_META_DATA
sein.
sensor, reserved und timestamp: Muss 0 sein.
meta_data.what:Enthält den Metadatentyp für dieses Ereignis. Derzeit gibt es nur einen gültigen Metadatentyp: META_DATA_FLUSH_COMPLETE
.
META_DATA_FLUSH_COMPLETE
-Ereignisse geben an, dass das Leeren eines Sensor-FIFO abgeschlossen ist. Bei meta_data.what=META_DATA_FLUSH_COMPLETE
muss meta_data.sensor
auf den Handle des gelöschten Sensors festgelegt werden. Sie werden nur dann generiert, wenn flush
auf einem Sensor aufgerufen wird. Weitere Informationen finden Sie im Abschnitt zur Funktion flush.