Sensori HAL 1.0

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

  • get_sensors_list: restituisce l'elenco di tutti i sensori.
  • activate: avvia o interrompe un sensore.
  • batch: imposta i parametri di un sensore, ad esempio la frequenza di campionamento e la latenza massima dei report.
  • setDelay: utilizzata solo nella versione 1.0 dell'HAL. Imposta la frequenza di campionamento per un determinato sensore.
  • flush - Esegue il flush del FIFO del sensore specificato e segnala uno svuotamento completato al termine dell'operazione.
  • poll: restituisce gli eventi dei sensori disponibili.

L'implementazione deve essere sicura tramite thread e consentire di chiamare queste funzioni da diversi thread.

L'interfaccia definisce anche diversi tipi utilizzati da queste funzioni. I tipi principali sono:

  • sensors_module_t
  • sensors_poll_device_t
  • sensor_t
  • sensors_event_t

Oltre alle sezioni seguenti, consulta la pagina sensors.h per ulteriori informazioni su questi tipi di dispositivi.

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. Per informazioni dettagliate su come vengono definiti i sensori, consulta la sezione sensor_t.

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

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

Questa funzione restituisce il numero di sensori nell'elenco.

attiva(sensore, vero/falso)

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

Attiva o disattiva un sensore.

sensor_handle è il manico del sensore per l'attivazione/disattivazione. L'handle di un sensore è definito dal campo handle della sua struttura sensor_t.

Il valore enabled è impostato su 1 per attivare o su 0 per disattivare il sensore.

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

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

I sensori di riattivazione, durante l'invio continuo di eventi, possono impedire al SoC di entra in modalità di sospensione, ma se non è necessario pubblicare alcun evento, viene eseguita la il wakelock deve essere rilasciato.

Se enabled è 1 e il sensore è già attivato, questa funzione non esegue alcuna operazione e ha esito positivo.

Se il valore di enabled è 0 e il sensore è già disattivato, questa funzione è autonoma e ha successo.

Questa funzione restituisce 0 in caso di esito positivo, mentre in caso contrario restituisce un numero di errore negativo.

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 dei report. Questa funzione può essere chiamata quando il sensore è attivo, nel qual caso non deve causare la perdita di misurazioni del sensore: il passaggio da una frequenza di campionamento all'altra non può causare la perdita di eventi, né il passaggio da una latenza massima del report elevata a una minima.

sensor_handle è il punto di manipolazione del sensore da configurare.

flags non è al momento utilizzato.

sampling_period_ns è il periodo di campionamento in cui il sensore dovrebbe essere eseguito in nanosecondi. Vedi sampling_period_ns per ulteriori dettagli.

max_report_latency_ns è il tempo massimo entro il quale possono essere eseguiti ritardato prima di essere riportato tramite l'HAL, in nanosecondi. Consulta la sezione max_report_latency_ns per ulteriori dettagli.

Questa funzione restituisce 0 in caso di esito positivo e un numero di errore negativo in caso contrario.

setDelay(sensore, periodo di campionamento)

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

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

Nella versione 1.0 di HAL, veniva utilizzato setDelay anziché batch per impostare sampling_period_ns.

flush(sensor)

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

Aggiungi un evento di svuotamento completo alla fine del file FIFO hardware per il sensore specificato ed effettua il flush del segnale FIFO. questi eventi vengono pubblicati normalmente (ovvero come se la latenza massima nei report erano scaduti) e rimossi dal FIFO.

Lo svuotamento avviene in modo asincrono, ad esempio la funzione deve essere restituita immediatamente. Se l'implementazione utilizza un singolo FIFO per diversi sensori, quel FIFO viene e l'evento svuotamento completo viene aggiunto solo per il sensore specificato.

Se il sensore specificato non ha il segnale FIFO (non è possibile il buffering) oppure se il sensore FIFO, era vuoto al momento della chiamata, flush deve comunque riuscire e inviare un evento di svuotamento completo del sensore. Questo vale per tutti i sensori, rispetto ai sensori one-shot.

Quando viene chiamato flush, anche se un evento di svuotamento è già presente nella FIFO per quel sensore, deve essere creato e aggiunto un altro evento alla fine della FIFO, che deve essere svuotata. Il numero di chiamate flush deve essere uguale al numero di eventi di aggiornamento completo creati.

flush non si applica a one-shot sensori; se sensor_handle si riferisce a un sensore one-shot, flush deve restituire -EINVAL e non generarne nessuna svuota l'evento di metadati completo.

Questa funzione restituisce 0 in caso di esito positivo, -EINVAL se il sensore specificato è un sensore una tantum o non è stato attivato e un numero di errore negativo in caso contrario.

poll()

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

Restituisce un array di dati del sensore riempiendo l'argomento data. Questa funzione deve bloccarsi finché non sono disponibili eventi. Verrà restituito il numero di eventi letti in caso di esito positivo o un numero di errore negativo in caso di errore.

Il numero di eventi restituiti in data deve essere minore 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 viene richiamata con i parametri richiesti, seguita da activate(..., enable=1).

Tieni presente che nella versione 1_0 di HAL l'ordine era opposto: activate veniva chiamato prima, seguito da set_delay.

Quando le caratteristiche richieste di un sensore cambiano mentre è viene attivata la funzione batch.

flush può essere chiamato in qualsiasi momento, anche se i sensori non sono attivati (in questo caso deve restituire -EINVAL)

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

In parallelo a queste chiamate, la funzione poll verrà chiamata ripetutamente per richiedere i dati. poll può essere chiamato anche se non sono attivi sensori.

sensors_module_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. Per ulteriori informazioni, consulta la definizione di sensors_module_t in sensors.h e la definizione di hw_module_t.

sensors_poll_device_t / sensors_poll_device_1_t

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

sensore_t

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

name: una stringa visibile all'utente che rappresenta il sensore. Spesso questa stringa contiene il nome della parte del sensore sottostante, il tipo di sensore e se si tratta di un sensore di attivazione. Ad esempio, "LIS2HH12 Accelerometer", "MAX21000 Uncalibrated Gyroscope", "BMP280 Wake-up Barometer", "MPU6515 Game Rotation Vector"

handle: il numero intero utilizzato per fare riferimento al sensore durante la registrazione o generando eventi.

type: il tipo di sensore. Leggi la spiegazione relativa al sensore digita Che cosa sono i sensori Android? per ulteriori dettagli e vedi 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 di sensore come stringa. Quando di un sensore è di tipo ufficiale, impostato su SENSOR_STRING_TYPE_*. Quando il sensore è di un tipo specifico del produttore, stringType deve iniziano con il nome di dominio inverso del produttore. Ad esempio, un sensore (come rilevatore unicorno) definita dal team di Cool-product di L'azienda di fantasia potrebbe usare stringType=”com.fictional_company.cool_product.unicorn_detector”. stringType viene utilizzato per identificare in modo univoco i sensori non ufficiali di testo. Vedi sensors.h per ulteriori informazioni su tipi e stringhe. di testo.

requiredPermission:una stringa che rappresenta l'autorizzazione. che le applicazioni devono possedere per vedere il sensore, registrarsi e ricevere e i relativi dati. Una stringa vuota indica che le applicazioni non richiedono alcuna autorizzazione per accedere a questo sensore. Per alcuni tipi di sensori, come il cardiofrequenzimetro, è obbligatorio un requiredPermission. Tutti i sensori che forniscono dati sensibili informazioni utente (come il battito cardiaco) devono essere protette da un autorizzazione.

flags: indicatori per questo sensore, che definiscono la modalità di generazione di report e se il sensore è o meno un sensore di attivazione. Ad esempio, un sensore di riattivazione one-shot avrà flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP. I frammenti il flag non utilizzato nella versione attuale dell'HAL deve essere lasciato uguale a 0.

maxRange: il valore massimo che il sensore può segnalare, nella stessa unità di misura dei valori registrati. Il sensore deve essere in grado di registrare i valori senza saturazione in [-maxRange; maxRange]. Nota che ciò significa che l'intervallo totale in senso generico è 2*maxRange. Quando il sensore registra valori su più assi, l'intervallo si applica a ciascun asse. Ad esempio, "+/- 2g" dell'accelerometro segnalerà maxRange = 2*9.81 = 2g.

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

power (alimentazione): il costo dell'alimentazione per l'attivazione del sensore, espresso in milliA. Questo valore è quasi sempre superiore al consumo di energia riportato nella scheda tecnica del sensore sottostante. Per ulteriori dettagli, consulta la sezione Sensori di base != sensori fisici e la sezione Procedura di misurazione della potenza per informazioni su come misurare il consumo di energia di un sensore. Se il consumo energetico del sensore dipende dal fatto che il dispositivo sia in movimento, il il consumo energetico durante gli spostamenti è quello riportato nell'power .

minDelay: per i sensori continui, il periodo di campionamento in microsecondi corrispondente alla frequenza più elevata supportata dal sensore. Consulta sampling_period_ns per dettagli su come viene utilizzato questo valore. Tieni presente che minDelay è expressed in microseconds mentre sampling_period_ns è in nanoseconds. Per i sensori in caso di modifica e in modalità di reporting speciale, a meno che altrimenti specificato, minDelay deve essere 0. Per i sensori one-shot, deve essere -1.

maxDelay: per i sensori continui e in continuo cambiamento, il campionamento periodo, in microsecondi, corrispondente alla velocità più lenta del sensore Google Cloud. Consulta sampling_period_ns per dettagli su come viene utilizzato questo valore. Tieni presente che maxDelay è espresso in microsecondi mentre sampling_period_ns è in nanosecondi. Per i sensori speciali e una tantum, maxDelay deve essere equale a 0.

fifoConfidentialEventCount:il numero di eventi riservati a questo sensore nella zona hardware FIFO. Se esiste una coda FIFO dedicata per questo sensore, fifoReservedEventCount è la dimensione di questa coda FIFO dedicata. Se la coda FIFO è condivisa con altri sensori, fifoReservedEventCount è la dimensione della parte della coda FIFO riservata a quel sensore. Sulla maggior parte dei sistemi FIFO condivisi e per i sistemi privi di FIFO hardware questo valore è 0.

fifoMaxEventCount: il numero massimo di eventi che possono verrà memorizzato nei FIFO di questo sensore. Questo valore è sempre maggiore o uguale a fifoReservedEventCount. Questo valore viene utilizzato per stimare la rapidità con cui la coda FIFO si riempie quando la registrazione al sensore avviene a una frequenza specifica, supponendo che non siano attivati altri sensori. Sui sistemi che non hanno FIFO hardware, fifoMaxEventCount è 0. Per ulteriori dettagli, consulta Raggruppamento in batch.

Per i sensori con un tipo di sensore ufficiale, alcuni campi vengono sovrascritti dal framework. Ad esempio, i sensori di accelerometro devono obbligatoriamente avere una modalità di generazione di report continua e i monitor della frequenza cardiaca devono obbligatoriamente essere protetti dall'autorizzazione SENSOR_PERMISSION_BODY_SENSORS.

sensors_event_t

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

version: 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 del sensore che ha generato l'evento, come definito dalla sensor_t.type.

timestamp: il timestamp dell'evento espresso in nanosecondi. Si tratta dell'ora in cui si è verificato l'evento (è stato fatto un passo o è stata eseguita una misurazione dell'accelerometro), non dell'ora in cui è stato registrato. timestamp deve essere sincronizzato con orologio elapsedRealtimeNano; nel caso di sensori continui, il tremolio deve essere piccolo. A volte è necessario filtrare i timestamp per soddisfare i requisiti CDD, poiché l'utilizzo solo del tempo di interruzione del SoC per impostare i timestamp causa un jitter troppo elevato e l'utilizzo solo del tempo del chip del sensore per impostare i timestamp può causare la disattivazione della sincronizzazione con il elapsedRealtimeNano orologio, poiché l'orologio del sensore si sposta.

dati e campi sovrapposti: i valori misurati sensore. Il significato e le unità di questi campi sono specifici per ogni tipo di sensore. Per una descrizione dei campi di dati, consulta sensors.h e la definizione dei diversi tipi di sensori. Per alcuni sensori viene segnalata anche la precisione delle letture come parte dei dati, tramite un campo status. Questo campo è limitato vengono trasmessi per i tipi di sensori selezionati, visualizzati a livello dell'SDK come il valore della precisione. Per questi sensori, il fatto che il campo dello stato sia impostato è menzionato nel suo tipo di sensore definizione di Kubernetes.

Eventi di aggiornamento completo dei metadati

Gli eventi dei metadati sono dello stesso tipo dei normali eventi dei sensori: sensors_event_meta_data_t = sensors_event_t. Vengono restituiti insieme altri eventi del sensore tramite sondaggio. Sono presenti i seguenti campi:

version: deve essere META_DATA_VERSION

type: deve essere SENSOR_TYPE_META_DATA

sensore, riservato e timestamp: deve essere 0

meta_data.what: contiene il tipo di metadati per questo evento. Al momento è disponibile un singolo tipo di metadati valido: META_DATA_FLUSH_COMPLETE.

Gli eventi META_DATA_FLUSH_COMPLETE rappresentano il completamento dello svuotamento di un FIFO del sensore. Quando meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor deve essere impostato sull'impugnatura del sensore che è stato lavato in lavatrice. Sono generate quando e solo quando flush viene chiamato su un sensore. Consulta la sezione sulle la funzione flush per ulteriori informazioni.