Sensori HAL 1.0

L'interfaccia Sensors HAL, dichiarata in sensori.h , rappresenta l'interfaccia tra il framework Android e il software specifico dell'hardware. Un'implementazione HAL deve definire ogni funzione dichiarata in sensori.h. Le funzioni principali sono:

  • get_sensors_list - Restituisce l'elenco di tutti i sensori.
  • activate - Avvia o arresta un sensore.
  • batch : imposta i parametri di un sensore come la frequenza di campionamento e la latenza massima di reporting.
  • setDelay : utilizzato solo nella versione HAL 1.0. Imposta la frequenza di campionamento per un determinato sensore.
  • flush - Svuota il FIFO del sensore specificato e segnala un evento di flush completo al termine.
  • poll : restituisce gli eventi del sensore disponibili.

L'implementazione deve essere thread-safe e consentire la chiamata di queste funzioni da thread diversi.

L'interfaccia definisce anche diversi tipi utilizzati da tali funzioni. Le tipologie principali sono:

  • sensors_module_t
  • sensors_poll_device_t
  • sensor_t
  • sensors_event_t

Oltre alle sezioni seguenti, vedere sensors.h per ulteriori informazioni su questi tipi.

get_sensors_list(elenco)

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

Fornisce l'elenco dei sensori implementati dall'HAL. Vedi sensor_t per i dettagli su come sono definiti i sensori.

L'ordine in cui i sensori appaiono nell'elenco è l'ordine in cui i sensori verranno segnalati alle applicazioni. Di solito vengono visualizzati per primi i sensori di base, seguiti dai sensori compositi.

Se più sensori condividono lo stesso tipo di sensore e proprietà di attivazione, il primo nell'elenco viene chiamato sensore "predefinito". È quello restituito da getDefaultSensor(int sensorType, bool wakeUp) .

Questa funzione restituisce il numero di sensori nell'elenco.

attivare(sensore, vero/falso)

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

Attiva o disattiva un sensore.

sensor_handle è l'handle del sensore da attivare/disattivare. L'handle di un sensore è definito dal campo handle della sua struttura sensor_t .

enabled è impostato su 1 per abilitare o 0 per disabilitare il sensore.

I sensori one-shot si disattivano automaticamente alla ricezione di un evento e devono comunque accettare di essere disattivati ​​tramite una chiamata a activate(..., enabled=0) .

I sensori di non riattivazione non impediscono mai al SoC di entrare in modalità di sospensione; ovvero l'HAL non deve mantenere un wakelock parziale per conto delle applicazioni.

I sensori di risveglio, quando inviano eventi in modo continuo, possono impedire al SoC di entrare in modalità di sospensione, ma se non è necessario inviare alcun evento, il wakelock parziale deve essere rilasciato.

Se enabled è 1 e il sensore è già attivato, questa funzione è no-op e ha esito positivo.

Se enabled è 0 e il sensore è già disattivato, questa funzione è no-op e ha esito positivo.

Questa funzione restituisce 0 in caso di successo e un numero di errore negativo altrimenti.

batch(sensore, flag, periodo di campionamento, latenza massima del report)

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

Imposta i parametri di un sensore, tra cui la frequenza di campionamento e la latenza massima del report . Questa funzione può essere richiamata mentre il sensore è attivato, nel qual caso non deve causare la perdita di alcuna misura del sensore: la transizione da una frequenza di campionamento all'altra non può causare la perdita di eventi, né il passaggio da una latenza di report massima elevata a una bassa latenza massima del report.

sensor_handle è l'handle del sensore da configurare.

flags è attualmente inutilizzato.

sampling_period_ns è il periodo di campionamento in cui il sensore dovrebbe funzionare, in nanosecondi. Vedi sampling_period_ns per maggiori dettagli.

max_report_latency_ns è il tempo massimo entro il quale gli eventi possono essere ritardati prima di essere segnalati tramite l'HAL, in nanosecondi. Vedi il paragrafo max_report_latency_ns per maggiori dettagli.

Questa funzione restituisce 0 in caso di successo e un numero di errore negativo altrimenti.

setDelay(sensore, periodo di campionamento)

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

Dopo la versione 1.0 di HAL, questa funzione è deprecata e non viene mai chiamata. Viene invece richiamata la funzione batch per impostare il parametro sampling_period_ns .

Nella versione HAL 1.0, setDelay veniva utilizzato al posto di batch per impostare sampling_period_ns .

scarico (sensore)

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

Aggiunge un evento di svuotamento completo alla fine della FIFO hardware per il sensore specificato e scarica la FIFO; tali eventi vengono consegnati come al solito (ovvero: come se la latenza massima di reporting fosse scaduta) e rimossi dal FIFO.

Lo svuotamento avviene in modo asincrono (ovvero: questa funzione deve restituire immediatamente). Se l'implementazione utilizza un singolo FIFO per più sensori, tale FIFO viene svuotato e l'evento di svuotamento completo viene aggiunto solo per il sensore specificato.

Se il sensore specificato non ha FIFO (nessun buffering possibile) o se il FIFO era vuoto al momento della chiamata, flush deve comunque avere esito positivo e inviare un evento di svuotamento completato per quel sensore. Questo vale per tutti i sensori diversi dai sensori one-shot.

Quando viene chiamato flush , anche se un evento di svuotamento è già presente nella FIFO per quel sensore, è necessario crearne uno aggiuntivo e aggiungerlo alla fine della FIFO, e la FIFO deve essere svuotata. Il numero di chiamate flush deve essere uguale al numero di eventi di svuotamento completati creati.

flush non si applica ai sensori one-shot ; se sensor_handle si riferisce a un sensore one-shot, flush deve restituire -EINVAL e non generare alcun evento di metadati flush complete.

Questa funzione restituisce 0 in caso di successo, -EINVAL se il sensore specificato è un sensore one-shot o non è stato abilitato e un numero di errore negativo altrimenti.

sondaggio()

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

Restituisce una matrice di dati del sensore compilando l'argomento data . Questa funzione deve bloccarsi finché gli eventi non sono disponibili. Restituirà il numero di eventi letti in caso di successo o un numero di errore negativo in caso di errore.

Il numero di eventi restituiti nei data deve essere inferiore o uguale all'argomento count . Questa funzione non restituirà mai 0 (nessun evento).

Sequenza di chiamate

Quando il dispositivo si avvia, viene chiamato get_sensors_list .

Quando un sensore viene attivato, la funzione batch verrà chiamata con i parametri richiesti, seguita da activate(..., enable=1) .

Si noti che nella versione HAL 1_0, l'ordine era inverso: activate veniva chiamato per primo, seguito da set_delay .

Quando le caratteristiche richieste di un sensore cambiano mentre è attivato, viene richiamata la funzione batch .

flush può essere chiamato in qualsiasi momento, anche su sensori non attivati ​​(in tal caso deve restituire -EINVAL )

Quando un sensore viene disattivato, verrà chiamato activate(..., enable=0) .

Parallelamente a tali chiamate, la funzione poll verrà chiamata ripetutamente per richiedere dati. poll può essere chiamato anche quando nessun sensore è attivato.

modulo_sensori_t

sensors_module_t è il tipo utilizzato per creare il modulo hardware Android per i sensori. L'implementazione dell'HAL deve definire un oggetto HAL_MODULE_INFO_SYM di questo tipo per esporre la funzione get_sensors_list . Vedere la definizione di sensors_module_t in sensori.h e la definizione di hw_module_t per ulteriori informazioni.

sensori_poll_dispositivo_t / sensori_poll_dispositivo_1_t

sensors_poll_device_1_t contiene il resto dei metodi definiti sopra: activate , batch , flush e poll . Il suo campo common (di tipo hw_device_t ) definisce il numero di versione dell'HAL.

sensore_t

sensor_t rappresenta un sensore Android . Ecco alcuni dei suoi campi importanti:

name: una stringa visibile all'utente che rappresenta il sensore. Questa stringa spesso contiene il nome della parte del sensore sottostante, il tipo di sensore e se si tratta di un sensore di riattivazione. Ad esempio, "Accelerometro LIS2HH12", "Giroscopio non calibrato MAX21000", "Barometro di risveglio BMP280", "Vettore di rotazione del gioco MPU6515"

handle: il numero intero utilizzato per fare riferimento al sensore durante la registrazione o la generazione di eventi da esso.

tipo: il tipo di sensore. Consulta la spiegazione del tipo di sensore in Cosa sono i sensori Android? per maggiori dettagli e vedere Tipi di sensori per i tipi di sensori ufficiali. Per i tipi di sensori non ufficiali, type deve iniziare con SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: il tipo del sensore come stringa. Quando il sensore ha un tipo ufficiale, impostalo su SENSOR_STRING_TYPE_* . Quando il sensore ha un tipo specifico del produttore, stringType deve iniziare con il nome del dominio inverso del produttore. Ad esempio, un sensore (ad esempio un rilevatore di unicorno) definito dal team Cool-product di Fictional-Company potrebbe utilizzare stringType=”com.fictional_company.cool_product.unicorn_detector” . stringType viene utilizzato per identificare in modo univoco i tipi di sensori non ufficiali. Vedi sensori.h per ulteriori informazioni su tipi e tipi di stringa.

requestPermission: una stringa che rappresenta l'autorizzazione che le applicazioni devono possedere per vedere il sensore, registrarsi e riceverne i dati. Una stringa vuota significa che le applicazioni non richiedono alcuna autorizzazione per accedere a questo sensore. Alcuni tipi di sensori, come il cardiofrequenzimetro, hanno requiredPermission obbligatoria. Tutti i sensori che forniscono informazioni sensibili sull'utente (come la frequenza cardiaca) devono essere protetti da un'autorizzazione.

flag: flag per questo sensore, che definiscono la modalità di reporting del sensore e se il sensore è un sensore di sveglia o meno. Ad esempio, un sensore di riattivazione one-shot avrà flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP . I bit del flag che non vengono utilizzati nella versione HAL corrente devono essere lasciati uguali a 0.

maxRange: il valore massimo che il sensore può segnalare, nella stessa unità dei valori riportati. Il sensore deve essere in grado di riportare valori senza saturazione entro [-maxRange; maxRange] . Si noti che ciò significa che la portata totale del sensore in senso generico è 2*maxRange . Quando il sensore segnala valori su più assi, l'intervallo si applica a ciascun asse. Ad esempio, un accelerometro “+/- 2g” riporterà maxRange = 2*9.81 = 2g .

risoluzione: la più piccola differenza di valore che il sensore può misurare. Solitamente calcolato in base a maxRange e al numero di bit nella misurazione.

potenza: il costo energetico per abilitare il sensore, in milliAmp. Questo è quasi sempre superiore al consumo energetico riportato nella scheda tecnica del sensore sottostante. Vedere Sensori di base!= sensori fisici per maggiori dettagli e vedere Processo di misurazione della potenza per dettagli su come misurare il consumo energetico di un sensore. Se il consumo energetico del sensore dipende dal fatto che il dispositivo sia in movimento, il consumo energetico durante lo spostamento è quello riportato nel campo power .

minDelay: per i sensori continui, il periodo di campionamento, in microsecondi, corrispondente alla velocità più veloce supportata dal sensore. Vedi sampling_period_ns per i dettagli su come viene utilizzato questo valore. Attenzione che minDelay è espresso in microsecondi mentre sampling_period_ns è in nanosecondi. Per i sensori in modalità di segnalazione in variazione e speciale, se non diversamente specificato, minDelay deve essere 0. Per i sensori one-shot, deve essere -1.

maxDelay: per sensori continui e in variazione, il periodo di campionamento, in microsecondi, corrispondente alla velocità più lenta supportata dal sensore. Vedi sampling_period_ns per i dettagli su come viene utilizzato questo valore. Attenzione che maxDelay è espresso in microsecondi mentre sampling_period_ns è in nanosecondi. Per sensori speciali e one-shot, maxDelay deve essere 0.

fifoReservedEventCount: il numero di eventi riservati per questo sensore nel FIFO hardware. Se esiste una FIFO dedicata per questo sensore, fifoReservedEventCount è la dimensione di questa FIFO dedicata. Se la FIFO è condivisa con altri sensori, fifoReservedEventCount è la dimensione della parte della FIFO riservata a quel sensore. Sulla maggior parte dei sistemi FIFO condivisi e sui sistemi che non dispongono di FIFO hardware questo valore è 0.

fifoMaxEventCount: il numero massimo di eventi che potrebbero essere memorizzati nelle FIFO per questo sensore. Questo è sempre maggiore o uguale a fifoReservedEventCount . Questo valore viene utilizzato per stimare la velocità con cui la FIFO si riempirà quando si registra al sensore a una velocità specifica, supponendo che non siano attivati ​​altri sensori. Sui sistemi che non dispongono di un FIFO hardware, fifoMaxEventCount è 0. Per ulteriori dettagli vedere Batching .

Per i sensori con un tipo di sensore ufficiale, alcuni campi vengono sovrascritti dal framework. Ad esempio, i sensori dell'accelerometro sono costretti ad avere una modalità di reporting continuo e i cardiofrequenzimetri sono costretti a essere protetti dall'autorizzazione SENSOR_PERMISSION_BODY_SENSORS .

sensori_evento_t

Gli eventi dei sensori generati dai sensori Android e segnalati tramite la funzione di sondaggio sono di type sensors_event_t . Ecco alcuni campi importanti di sensors_event_t :

versione: deve essere sizeof(struct sensors_event_t)

sensor: l'handle del sensore che ha generato l'evento, come definito da sensor_t.handle .

type: il tipo di sensore che ha generato l'evento, come definito da sensor_t.type .

timestamp: il timestamp dell'evento in nanosecondi. Si tratta dell'ora in cui si è verificato l'evento (è stato compiuto un passo o è stata effettuata una misurazione con l'accelerometro), non l'ora in cui l'evento è stato segnalato. timestamp deve essere sincronizzato con l'orologio elapsedRealtimeNano e, nel caso di sensori continui, il jitter deve essere piccolo. Il filtraggio del timestamp è talvolta necessario per soddisfare i requisiti CDD, poiché l'utilizzo solo del tempo di interruzione del SoC per impostare i timestamp provoca un jitter troppo elevato e l'utilizzo solo del tempo del chip del sensore per impostare i timestamp può causare la desincronizzazione dall'orologio elapsedRealtimeNano , poiché il l'orologio del sensore va alla deriva.

dati e campi sovrapposti: i valori misurati dal sensore. Il significato e le unità di questi campi sono specifici per ciascun tipo di sensore. Vedi sensori.h e la definizione dei diversi tipi di sensori per una descrizione dei campi dati. Per alcuni sensori, la precisione delle letture viene segnalata anche come parte dei dati, attraverso un campo status . Questo campo viene convogliato solo per i tipi di sensori selezionati e viene visualizzato a livello SDK come valore di precisione. Per questi sensori, il fatto che il campo di stato debba essere impostato è menzionato nella definizione del tipo di sensore .

Eventi completi di svuotamento dei metadati

Gli eventi di metadati hanno lo stesso tipo dei normali eventi dei sensori: sensors_event_meta_data_t = sensors_event_t . Vengono restituiti insieme ad altri eventi del sensore tramite poll. Possiedono i seguenti campi:

versione: deve essere META_DATA_VERSION

tipo: deve essere SENSOR_TYPE_META_DATA

sensore, riservato e timestamp : deve essere 0

meta_data.what: contiene il tipo di metadati per questo evento. Attualmente esiste un unico tipo di metadati valido: META_DATA_FLUSH_COMPLETE .

Gli eventi META_DATA_FLUSH_COMPLETE rappresentano il completamento del lavaggio di una FIFO del sensore. Quando meta_data.what=META_DATA_FLUSH_COMPLETE , meta_data.sensor deve essere impostato sull'handle del sensore che è stato svuotato. Vengono generati quando e solo quando viene richiesto flush su un sensore. Per ulteriori informazioni vedere la sezione sulla funzione flush .