Die Sensors HAL-Schnittstelle, die in sensors.h deklariert ist, stellt die Schnittstelle zwischen dem Android-Framework und der hardwarespezifischen Software dar. In einer HAL-Implementierung muss jede in sensors.h deklarierte Funktion definiert werden. Die wichtigsten Funktionen sind:
get_sensors_list: Gibt die Liste aller Sensoren zurück.activate– Startet oder beendet einen Sensor.batch: Legt die Parameter eines Sensors fest, z. B. die Abtastfrequenz und die maximale Meldeverzögerung.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 Ereignis vom Typ „flush complete“, wenn dies abgeschlossen ist.poll– Gibt verfügbare Sensorereignisse zurück.
Die Implementierung muss threadsicher sein und es ermöglichen, dass diese Funktionen von verschiedenen Threads aus aufgerufen werden.
Die Schnittstelle definiert auch mehrere Typen, die von diesen Funktionen verwendet werden. Die wichtigsten Typen sind:
sensors_module_tsensors_poll_device_tsensor_tsensors_event_t
Zusätzlich zu den Abschnitten unten 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);
Gibt die Liste der vom HAL implementierten Sensoren zurück. 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 die Sensoren an die Anwendungen gemeldet werden. Normalerweise werden zuerst die Basissensoren und dann die zusammengesetzten Sensoren angezeigt.
Wenn mehrere Sensoren denselben Sensortyp und dieselbe Wake-up-Eigenschaft haben, wird der erste in der Liste als „Standard“-Sensor bezeichnet. Er wird von getDefaultSensor(int sensorType, bool wakeUp) zurückgegeben.
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 Handle des Sensors, der aktiviert/deaktiviert werden soll. Der Handle eines Sensors wird durch das Feld handle seiner sensor_t-Struktur definiert.
enabled ist auf 1 gesetzt, um den Sensor zu aktivieren, oder auf 0, um ihn zu deaktivieren.
One-Shot-Sensoren werden nach dem Empfang eines Ereignisses automatisch deaktiviert. Sie müssen jedoch weiterhin über einen Aufruf von activate(...,
enabled=0) deaktiviert werden.
Sensoren, die nicht zum Aufwecken verwendet werden, verhindern nie, dass das SoC in den Ruhemodus wechselt. Das HAL darf also im Namen von Anwendungen keinen partiellen Wake-Lock halten.
Wenn Wake-up-Sensoren kontinuierlich Ereignisse liefern, kann das SoC nicht in den Ruhemodus wechseln. Wenn jedoch kein Ereignis geliefert werden muss, muss die partielle Wake-Lock-Sperre aufgehoben werden.
Wenn enabled = 1 und der Sensor bereits aktiviert ist, wird diese Funktion nicht ausgeführt und ist erfolgreich.
Wenn enabled = 0 und der Sensor bereits deaktiviert ist, ist diese Funktion ein No-Op und wird erfolgreich ausgeführt.
Diese Funktion gibt bei Erfolg 0 und andernfalls eine negative Fehlernummer zurück.
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);Legt die Parameter eines Sensors fest, einschließlich Abtastfrequenz und maximaler Berichtslatenz. Diese Funktion kann aufgerufen werden, während der Sensor aktiviert ist. In diesem Fall dürfen keine Sensormessungen verloren gehen: Der Übergang von einer Samplingrate zur anderen darf nicht zu verlorenen Ereignissen führen, ebenso wenig wie der Übergang 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 der Abtastzeitraum, in dem 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 0 und andernfalls eine negative Fehlernummer zurück.
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 nie 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 dem Ende des Hardware-FIFO für den angegebenen Sensor ein flush complete event hinzu und leeren Sie den FIFO. Diese Ereignisse werden wie gewohnt (d. h. als ob die maximale Meldeverzögerung abgelaufen wäre) übermittelt und aus dem FIFO entfernt.
Das Leeren erfolgt asynchron. Diese Funktion muss also sofort zurückgegeben werden. Wenn bei der Implementierung ein einzelner FIFO für mehrere Sensoren verwendet wird, wird dieser FIFO geleert und das Ereignis „Flush abgeschlossen“ wird nur für den angegebenen Sensor hinzugefügt.
Wenn der angegebene Sensor keinen FIFO-Puffer hat (keine Pufferung möglich) oder der FIFO-Puffer zum Zeitpunkt des Aufrufs leer war, muss flush trotzdem erfolgreich sein und ein Ereignis zum Abschluss des Flush-Vorgangs für diesen Sensor senden. Das gilt für alle Sensoren mit Ausnahme von Sensoren, die nur einmal ausgelöst werden.
Wenn flush aufgerufen wird, muss ein zusätzliches Flush-Ereignis erstellt und am Ende des FIFO hinzugefügt werden, auch wenn sich bereits ein Flush-Ereignis im FIFO für diesen Sensor befindet. 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 sensor_handle auf einen One-Shot-Sensor verweist, 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, und andernfalls eine negative Fehlernummer.
poll()
int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
count);Gibt ein Array mit Sensordaten zurück, indem das data-Argument 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 0 (kein Ereignis) zurückgeben.
Abfolge der Aufrufe
Wenn das Gerät hochfährt, wird get_sensors_list aufgerufen.
Wenn ein Sensor aktiviert wird, wird die Funktion batch mit den angeforderten Parametern aufgerufen, gefolgt von activate(..., enable=1).
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 Funktion batch 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. In der HAL-Implementierung muss ein Objekt HAL_MODULE_INFO_SYM dieses Typs definiert werden, 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.
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 Namen des zugrunde liegenden Sensors, den Sensortyp und die Information, ob es sich um einen Wake-up-Sensor handelt. Beispiele: „LIS2HH12 Accelerometer“, „MAX21000 Uncalibrated Gyroscope“, „BMP280 Wake-up Barometer“, „MPU6515 Game Rotation Vector“
handle:Die Ganzzahl, die verwendet wird, um auf den Sensor zu verweisen, wenn er registriert wird oder Ereignisse von ihm generiert werden.
type:Der Typ des Sensors. Weitere Informationen finden Sie in der Erklärung des Sensortyps unter Was sind Android-Sensoren? und in Sensortypen für offizielle Sensortypen. Bei inoffiziellen Sensortypen muss type mit SENSOR_TYPE_DEVICE_PRIVATE_BASE beginnen.
stringType:Der Typ des Sensors als String. Wenn der Sensor einen offiziellen Typ hat, legen Sie ihn auf SENSOR_STRING_TYPE_* fest. Wenn der Sensor einen herstellerspezifischen Typ hat, muss stringType mit dem umgekehrten Domainnamen des Herstellers beginnen. Ein Sensor (z. B. ein Einhorn-Detektor), der vom Team Cool-product bei Fictional-Company definiert wurde, könnte beispielsweise stringType=”com.fictional_company.cool_product.unicorn_detector” verwenden.
Mit stringType werden inoffizielle Sensortypen eindeutig identifiziert. Weitere Informationen zu Typen und String-Typen finden Sie unter sensors.h.
requiredPermission:Ein String, der die Berechtigung darstellt, die Anwendungen benötigen, um den Sensor zu sehen, sich dafür zu registrieren und seine Daten zu empfangen. Ein leerer String bedeutet, dass Anwendungen keine Berechtigung für den Zugriff auf diesen Sensor benötigen. Für einige Sensortypen wie den Herzfrequenzmesser ist ein obligatorisches requiredPermission erforderlich. Alle Sensoren, die vertrauliche Nutzerinformationen (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 angeben, ob der Sensor ein Wake-up-Sensor ist oder nicht. Ein One-Shot-Wake-up-Sensor 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 gesetzt werden.
maxRange:Der maximale Wert, den der Sensor melden kann, in derselben Einheit wie die gemeldeten Werte. Der Sensor muss Werte innerhalb von [-maxRange; maxRange] melden können, ohne dass es zu einer Sättigung kommt. Das bedeutet, dass der gesamte Bereich des Sensors im generischen Sinne 2*maxRange ist. Wenn der Sensor Werte für mehrere Achsen meldet, gilt der Bereich für jede Achse. Ein Beschleunigungsmesser mit „+/- 2g“ gibt beispielsweise maxRange = 2*9.81 = 2g zurück.
Auflösung:Der kleinste Wertunterschied, den der Sensor messen kann.
Wird in der Regel auf Grundlage von maxRange und der Anzahl der Bits in der Messung berechnet.
power:Die Stromkosten für die Aktivierung des Sensors in Milliampere.
Das ist fast immer mehr als der im Datenblatt des zugrunde liegenden Sensors angegebene Stromverbrauch. Weitere Informationen finden Sie unter Basissensoren != physische Sensoren. Informationen zum Messen des Stromverbrauchs eines Sensors finden Sie unter Prozess zur Leistungsmessung.
Wenn der Stromverbrauch des Sensors davon abhängt, ob sich das Gerät bewegt, wird der Stromverbrauch während der Bewegung im Feld power angegeben.
minDelay:Für kontinuierliche Sensoren der Stichprobenzeitraum in Mikrosekunden, der der schnellsten Rate entspricht, die der Sensor unterstützt. Weitere Informationen zur Verwendung dieses Werts finden Sie unter sampling_period_ns. minDelay wird in Mikrosekunden angegeben, sampling_period_ns in Nanosekunden. Bei Sensoren im On-Change- und im speziellen Berichtsmodus muss minDelay – sofern nicht anders angegeben – 0 sein. Bei einmaligen Sensoren muss der Wert -1 sein.
maxDelay:Für kontinuierliche und On-Change-Sensoren der Abtastzeitraum in Mikrosekunden, der der langsamsten Rate entspricht, die der Sensor unterstützt. Weitere Informationen zur Verwendung dieses Werts finden Sie unter sampling_period_ns. maxDelay wird in Mikrosekunden angegeben, sampling_period_ns in Nanosekunden. Bei speziellen Sensoren und Sensoren für einmalige Messungen 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 dedizierten FIFO gibt, 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. 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. Dieser Wert wird verwendet, um zu schätzen, wie schnell der FIFO-Speicher voll wird, wenn er mit einer bestimmten Rate für den Sensor registriert wird, vorausgesetzt, dass keine anderen Sensoren aktiviert sind. Auf Systemen ohne Hardware-FIFO ist fifoMaxEventCount = 0. Weitere Informationen finden Sie unter Batching.
Bei Sensoren mit einem offiziellen Sensortyp werden einige der 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 durch sensor_t.handle definiert.
type:Der Sensortyp des Sensors, der das Ereignis generiert hat, wie von 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 wurde durchgeführt), nicht der Zeitpunkt, zu dem das Ereignis gemeldet wurde. timestamp muss mit der elapsedRealtimeNano-Uhr synchronisiert sein. Bei kontinuierlichen Sensoren muss der Jitter gering sein. Die Zeitstempelfilterung ist manchmal erforderlich, um die CDD-Anforderungen zu erfüllen. Wenn nur die SoC-Unterbrechungszeit zum Festlegen der Zeitstempel verwendet wird, führt dies zu einem zu hohen Jitter. Wenn nur die Sensorchip-Zeit zum Festlegen der Zeitstempel verwendet wird, kann es zu einer Desynchronisierung von der elapsedRealtimeNano-Uhr kommen, da die Sensoruhr abweicht.
Daten und sich überschneidende 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 das Feld status angegeben. Dieses Feld wird nur für diese ausgewählten Sensortypen übergeben und erscheint auf der SDK-Ebene als Genauigkeitswert. Für diese Sensoren wird in der Definition des Sensortyps darauf hingewiesen, dass das Statusfeld festgelegt werden muss.
Ereignisse für den Abschluss des Metadaten-Flush
Metadatenereignisse haben denselben Typ wie normale Sensorereignisse: sensors_event_meta_data_t = sensors_event_t. Sie werden zusammen mit anderen Sensorereignissen durch Poll 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 stellen den Abschluss des Leerns eines Sensor-FIFO dar. Wenn meta_data.what=META_DATA_FLUSH_COMPLETE, muss meta_data.sensor auf das Handle des Sensors gesetzt werden, der geleert wurde. Sie werden nur generiert, wenn flush für einen Sensor aufgerufen wird. Weitere Informationen finden Sie im Abschnitt zur flush-Funktion.