A partire dal 27 marzo 2025, ti consigliamo di utilizzare android-latest-release anziché aosp-main per compilare e contribuire ad AOSP. Per ulteriori informazioni, vedi Modifiche ad AOSP.

Questa pagina è stata tradotta dall'API Cloud Translation.

Sensori HAL 1.0
Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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: utilizzato solo nella versione 1.0 dell'HAL. Imposta la frequenza di campionamento per un un dato sensore.
flush - Esegue il flush del FIFO del sensore specificato e segnala uno svuotamento completato al termine dell'operazione.
poll: restituisce gli eventi del sensore 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 riportate di seguito, consulta 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. Per informazioni dettagliate su come vengono definiti i sensori, consulta la sezione sensor_t.

L'ordine in cui appaiono i sensori nell'elenco è l'ordine in cui i sensori i sensori 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 proprietà di riattivazione, la prima quello dell'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.

enabled è impostato su 1 per attivare il sensore o su 0 per disattivarlo.

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

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

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

Se enabled è 1 e il sensore è già attivato, questa funzione è autonoma e ha successo.

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(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);

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 al momento non è utilizzato.

sampling_period_ns è il periodo di campionamento a cui deve funzionare il sensore, in nanosecondi. Vedi sampling_period_ns per ulteriori dettagli.

max_report_latency_ns è il tempo massimo di ritardo degli eventi prima che vengano registrati 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(sensor, sampling period)

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 il parametro sampling_period_ns.

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

flush(sensore)

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

Aggiungi un evento di aggiornamento completo alla fine della coda FIFO hardware per il sensore specificato ed esegui l'aggiornamento della coda FIFO. Questi eventi vengono inviati come di consueto (ovvero come se la latenza massima di generazione dei report fosse scaduta) e rimossi dalla coda FIFO.

Lo svuotamento avviene in modo asincrono (ovvero questa funzione deve restituire immediatamente). Se l'implementazione utilizza una singola coda FIFO per più sensori, la coda viene svuotata e l'evento di completamento dello svuotamento 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 flush devono essere uguali al numero di eventi di svuotamento completi creati.

flush non si applica ai sensori una tantum. Se sensor_handle fa riferimento a un sensore una tantum, flush deve restituire -EINVAL e non generare alcun evento di aggiornamento completo dei metadati.

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.

sondaggio()

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 devono essere bloccati finché gli eventi non sono disponibili. Restituisce 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 chiamata con il parametri richiesti, seguiti da activate(..., enable=1).

Tieni presente che nella versione 1_0 dell'HAL l'ordine era opposto: il nome activate era seguito da set_delay.

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

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

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

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

modulo_sensori_t

sensors_module_t è il tipo utilizzato per creare l'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. Consulta le definizione di sensors_module_t in sensors.h e la definizione di hw_module_t per ulteriori informazioni.

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 sensore Android. Ecco alcuni dei suoi campi importanti:

name: una stringa visibile all'utente che rappresenta il sensore. Questa stringa spesso contiene il nome parziale del sensore sottostante, il tipo di sensore e o un sensore di sveglia. Ad esempio, "Accelerometro LIS2HH12", "MAX21000 Giroscopio non calibrato", "BMP280 Wake-up Barometer", "Gioco MPU6515 Rotazione Vector" (Vettore di rotazione)

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 tipi di sensori non ufficiali, type deve iniziare con SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: il tipo di sensore come stringa. Se il sensore ha un tipo ufficiale, impostalo 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 (ad esempio un rilevatore di unicorni) definito dal team di Prodotto-fantastico 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. Per ulteriori informazioni sui tipi e sui tipi di stringa, consulta sensors.h.

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 valori senza saturare entro [-maxRange; maxRange]. Tieni presente che questo significa che l'intervallo totale del sensore in senso generico è 2*maxRange. Quando il sensore segnala valori superiori a più assi, l'intervallo si applica a ciascuno di essi. Ad esempio, "+/- 2g" dell'accelerometro segnalerà maxRange = 2*9.81 = 2g.

risoluzione:la differenza minima di valore che il sensore è in grado di misurare. In genere 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 è quasi sempre superiore al consumo energetico riportato nella scheda tecnica del sensore sottostante. Vedi Sensori di base != fisici Sensori per ulteriori dettagli e consulta la sezione Misurazione dell'alimentazione per informazioni dettagliate su come misurare il consumo energetico di un sensore. Se il consumo di energia del sensore dipende dal movimento del dispositivo, il consumo di energia in movimento è quello indicato nel campo 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 è espresso in microsecondi mentre sampling_period_ns è in nanosecondi. 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.

fifoReservedEventCount: il numero di eventi riservati per questo sensore nella FIFO hardware. Se è presente un FIFO dedicato per questo sensore, fifoReservedEventCount è la dimensione di questo FIFO dedicato. Se la coda FIFO è condivisa con altri sensori, fifoReservedEventCount è la dimensione della parte della coda FIFO riservata a quel sensore. Nella maggior parte dei sistemi con FIFO condiviso e su quelli che non dispongono di un 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 dispongono di una FIFO hardware, fifoMaxEventCount è 0. Per ulteriori dettagli, consulta la sezione Raggruppamento.

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 del sensore generati dai sensori Android e segnalati tramite la funzione poll sono di tipo 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. Questa è l'ora che si è verificato (è stato effettuato un passo o è stata effettuata una misurazione con l'accelerometro), non l'ora in cui l'evento è stato segnalato. timestamp deve essere sincronizzato con il clock elapsedRealtimeNano e, nel caso di sensori continui, il jitter deve essere ridotto. A volte il filtro timestamp è necessario per soddisfare il CDD come l'uso esclusivo del tempo di interruzione del SoC per impostare i timestamp causa un jitter troppo elevato e l'uso del solo chip del sensore per impostare la i timestamp possono causare la desincronizzazione Orologio elapsedRealtimeNano, mentre l'orologio del sensore cambia.

Dati e campi sovrapposti: i valori misurati dal sensore. Il significato e le unità di questi campi sono specifici per ogni tipo di sensore. Consulta la pagina sensors.h e la definizione dei diversi tipi di sensori per una descrizione dei campi di dati. Per alcuni sensori, l'accuratezza delle letture viene riportata anche 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 debba essere impostato è indicato nella definizione del tipo di sensore.

Eventi completati per lo svuotamento 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 del flush di un sensore FIFO. 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 chiamato flush su un sensore. Consulta la sezione sulle la funzione flush per ulteriori informazioni.