Sensors HAL 1.0

Hinweis: Auf dieser Seite wird Sensors HAL 1.0 beschrieben. Informationen zur Implementierung von Sensors HAL 2.0 auf Geräten mit Android 10 und höher finden Sie unter Sensors HAL 2.0.

Die in sensors.h deklarierte HAL-Schnittstelle ist die Schnittstelle zwischen dem Android-Framework und dem Hardware-spezifische Software zu implementieren. Eine HAL-Implementierung muss jede Funktion definieren Sensoren.h. 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. die Abtasthäufigkeit und der Maximalwert Berichtslatenz.
• setDelay – Nur in HAL-Version 1.0 verwendet. Legt die Stichprobenhäufigkeit für eine Sensor verwendet.
• flush – Der FIFO des angegebenen Sensors wird geleert und es wird ein Ereignis ausgegeben, wenn der Vorgang abgeschlossen ist.
• poll: Gibt die verfügbaren 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

Zusätzlich zu den Abschnitten unten finden Sie unter sensors.h weitere Informationen zu diesen Typen.

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 Composite-Sensoren.

Wenn mehrere Sensoren denselben Sensortyp und dieselbe Weckeigenschaft haben, wird der erste in der Liste als „Standardsensor“ bezeichnet. Das 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 Ziehpunkt des Sensors, der aktiviert oder deaktiviert werden soll. Der Handle wird durch das Feld handle seiner sensor_t-Struktur definiert.

Wenn enabled auf „1“ gesetzt ist, ist der Sensor aktiviert. Bei „0“ ist 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.

Nicht-Aktivierungssensoren verhindern niemals, dass das SoC in den Ruhemodus wechselt. das hat der HAL keinen Teil-Wakelock im Namen von Anwendungen.

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, ist diese Funktion eine Nullfunktion. und erfolgreich ist.

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 0 und ansonsten eine negative Fehlerzahl 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);

Hiermit werden die Parameter eines Sensors festgelegt, einschließlich Abtastrate und maximaler Berichtslatenz. Diese Funktion kann aufgerufen werden, während der Sensor aktiviert ist: In diesem Fall darf dies nicht zu einem Verlust von Sensormessungen führen: Übergang von einer Stichprobenrate zur anderen Rate verloren gegangen sind. Ebenso wenig Übergang von einer hohen maximalen Berichtslatenz zu einem niedrigen maximalen Bericht Latenz.

sensor_handle ist der Handle des zu konfigurierenden Sensors.

flags wird derzeit nicht verwendet.

sampling_period_ns ist der Zeitraum der Stichprobenerhebung, in dem der Sensor in Nanosekunden. Siehe sampling_period_ns für erhalten Sie weitere Informationen.

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 ansonsten eine negative Fehlerzahl 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 nicht mehr aufgerufen. Stattdessen wird die Funktion batch aufgerufen, um den Parameter sampling_period_ns festzulegen.

In HAL-Version 1.0 wurde zum Festlegen von sampling_period_ns anstelle eines Batches setDelay verwendet.

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 Ereignis zum Leeren des Abschlusses hinzu und leert den FIFO. werden diese Ereignisse wie gewohnt bereitgestellt. abgelaufen ist) und aus dem FIFO entfernt.

Das Leeren erfolgt asynchron (d. h., diese Funktion muss sofort zurückgeben). Wenn die Implementierung einen einzelnen FIFO für mehrere Sensoren verwendet, ist dieser FIFO geleert und das Ereignis „Leeren abgeschlossen“ 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 müssen der Anzahl der erstellten Ereignisse für abgeschlossene Leerungen 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.

Umfrage()

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 müssen blockiert werden, bis Ereignisse verfügbar sind. Es wird die Anzahl der gelesenen Ereignisse bei Erfolg oder eine negative Fehlerzahl im Falle eines Fehlers.

Die Anzahl der in data zurückgegebenen Ereignisse muss kleiner oder gleich sein Das Argument count. 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.

Beachten Sie, dass in der HAL-Version 1_0 das Gegenteil der Fall war: activate wurde 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.

Sensorenmodult

sensors_module_t ist der Typ, der zum Erstellen des Android-Hardwaremoduls für die Sensoren verwendet wird. Die Implementierung des HAL muss ein Objekt definieren. HAL_MODULE_INFO_SYM dieses Typs, 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.

sensor_poll_device_t / sensor_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 des HAL.

sensor_t

sensor_t steht für einen Android-Sensor. Hier sind einige wichtige Felder:

name:Ein für den Nutzer sichtbarer String, der den Sensor darstellt. Dieser String wird häufig verwendet den Teilnamen des zugrunde liegenden Sensors, den Sensortyp und ganz gleich, ob es sich um einen Wecksensor handelt. Beispiel: „LIS2HH12-Beschleunigungsmesser“, „MAX21000 Unkalibrated Gyrosscope“, „BMP280 Wake-up Barometer“, „MPU6515 Game“ Rotationsvektor“

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. Für nicht offizielle Sensortypen, type muss 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. Wann? hat der Sensor einen herstellerspezifischen Typ, stringType muss mit dem Reverse-Domainnamen des Herstellers beginnen. Ein Sensor (z. B. Einhorndetektor, die vom Cool-product-Team bei Das fiktive Unternehmen könnte stringType=”com.fictional_company.cool_product.unicorn_detector” Die stringType wird verwendet, um nicht offizielle Sensoren eindeutig zu identifizieren Typen. Weitere Informationen zu Typen und Strings finden Sie unter sensors.h. Typen.

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 Anwendungen keine Berechtigung für den Zugriff auf diesen Sensor benötigen. Für einige Sensortypen wie den Herzfrequenzmesser ist eine obligatorische requiredPermission erforderlich. 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 Bestandteile von Das Flag, das in der aktuellen HAL-Version nicht verwendet wird, muss gleich 0 sein.

maxRange:Der Maximalwert, den der Sensor melden kann. Der Wert sollte in derselben Einheit wie der den angegebenen Werten. Der Sensor muss Werte ohne Sättigung ausgeben können innerhalb von [-maxRange; maxRange]. Dies bedeutet, dass der Gesamtbereich der im allgemeinen Sinn 2*maxRange ist. Wenn der Sensor Werte für mehrere Achsen meldet, gilt der Bereich für jede Achse. Beispiel: „+/- 2g“ Der Beschleunigungsmesser meldet 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 Kosten für das Aktivieren des Sensors in MilliAmp. Dies ist fast immer höher als der in den Berichten Datenblatt des zugrunde liegenden Sensors. Weitere Informationen finden Sie unter Basissensoren ≠ physische Sensoren und unter Prozess zur Leistungsmessung. Wenn der Stromverbrauch des Sensors davon abhängt, ob das Gerät bewegt wird, Der Stromverbrauch während der Bewegung ist der im power erfasste Stromverbrauch ein.

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. minDelay ist in Mikrosekunden ausgedrückt, während der Wert für sampling_period_ns in Nanosekunden. Für Sensoren im Modus „Bei Änderung“ und „Spezielle Berichtsmodus“, es sei denn, anders angegeben, muss minDelay 0 sein. Bei Einmalsensoren muss der Wert -1 sein.

maxDelay:Bei fortlaufenden und On-Change-Sensoren kann die Stichprobenerhebung Periode in Mikrosekunden, entsprechend der langsamsten Geschwindigkeit, die der Sensor unterstützt. Siehe sampling_period_ns für Details zur Verwendung dieses Werts. maxDelay ist in Mikrosekunden ausgedrückt, während der Wert für sampling_period_ns in Nanosekunden. 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. Auf den meisten gemeinsam genutzten FIFO-Systemen und auf ohne Hardware-FIFO, ist dieser Wert 0.

fifoMaxEventCount:Die maximale Anzahl von Ereignissen, die für diesen Sensor in den FIFOs gespeichert werden. Dieser Wert ist immer größer oder gleich fifoReservedEventCount. Anhand dieses Werts wird geschätzt, wird der FIFO schnell voll, wenn er sich bei einer bestimmten 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.

sensor_event_t

Sensorereignisse, die von Android-Sensoren generiert und über die poll-Funktion gemeldet werden, haben den Wert 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

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

timestamp: Der Zeitstempel des Ereignisses in Nanosekunden. Dies ist der Zeitpunkt, Ereignis eingetreten ist (ein Schritt wurde unternommen oder eine Messung des Beschleunigungsmessers durchgeführt). und nicht den Zeitpunkt, zu dem das Ereignis gemeldet 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 von der Sensor. Die Bedeutung und die Einheiten dieser Felder sind für jeden Sensor unterschiedlich. Typ. 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 enthält nur für diese ausgewählten Sensortypen, die auf der SDK-Ebene als Genauigkeitswert. Für diese Sensoren ist die Tatsache, dass das Statusfeld in ihrem Sensortyp erwähnt wird. Definition.

Ereignisse zu abgeschlossenem Leeren von Metadaten

Metadatenereignisse haben denselben Typ wie normale Sensorereignisse: sensors_event_meta_data_t = sensors_event_t Sie werden zusammen mit andere Sensorereignisse über die Umfrage. Sie enthalten die folgenden Felder:

version:Muss META_DATA_VERSION sein

type: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 nur einen gültigen Metadatentyp: META_DATA_FLUSH_COMPLETE.

META_DATA_FLUSH_COMPLETE-Ereignisse geben an, dass das Leeren des FIFO-Puffers eines Sensors abgeschlossen ist. Wann: meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor muss auf den Griff des gespülten Sensors eingestellt sein. Sie werden nur dann generiert, wenn flush auf einem Sensor aufgerufen wird. Weitere Informationen finden Sie im Abschnitt der Funktion flush.