Panoramica dei sensori

La maggior parte dei dispositivi Android ha sensori integrati che misurano il movimento, l'orientamento e varie condizioni ambientali. Questi sensori sono in grado di fornire dati non elaborati con elevata precisione e accuratezza e sono utili se vuoi monitorare il movimento o il posizionamento tridimensionale del dispositivo oppure se vuoi monitorare i cambiamenti nell'ambiente circostante vicino a un dispositivo. Ad esempio, un gioco potrebbe monitorare le letture del sensore di gravità di un dispositivo per dedurre gesti e movimenti complessi dell'utente, come inclinazione, scuotimento, rotazione o oscillazione. Allo stesso modo, un'applicazione meteo potrebbe utilizzare il sensore di temperatura e il sensore di umidità di un dispositivo per calcolare e segnalare il punto di rugiada, oppure un'applicazione di viaggi potrebbe utilizzare il sensore del campo geomagnetico e l'accelerometro per segnalare la direzione di una bussola.

Consulta le seguenti risorse correlate:

• Sensori
• Sensori di movimento
• Sensori di posizione
• Sensori ambientali
• API Demo (OS - RotationVectorDemo)

La piattaforma Android supporta tre categorie generali di sensori:

• Sensori di movimento

  Questi sensori misurano le forze di accelerazione e rotazione lungo tre assi. Questa categoria include accelerometri, sensori di gravità, giroscopi e sensori di vettore di rotazione.

• Sensori ambientali

  Questi sensori misurano vari parametri ambientali, come la temperatura e la pressione dell'aria ambiente, l'illuminazione e l'umidità. Questa categoria include barometri, fotometri e termometri.

• Sensori di posizione

  Questi sensori misurano la posizione fisica di un dispositivo. Questa categoria include sensori di orientamento e magnetometri.

Puoi accedere ai sensori disponibili sul dispositivo e acquisire dati grezzi dei sensori utilizzando il framework dei sensori di Android. Il framework dei sensori fornisce diverse classi e interfacce che ti aiutano a eseguire un'ampia varietà di attività correlate ai sensori. Ad esempio, puoi utilizzare il framework dei sensori per:

• Determina quali sensori sono disponibili su un dispositivo.
• Determina le funzionalità di un singolo sensore, ad esempio la portata massima, il produttore, i requisiti di alimentazione e la risoluzione.
• Acquisisci i dati dei sensori non elaborati e definisci la frequenza minima di acquisizione.
• Registra e annulla la registrazione dei listener di eventi del sensore che monitorano le modifiche del sensore.

Questo argomento fornisce una panoramica dei sensori disponibili sulla piattaforma Android. Fornisce anche un'introduzione al framework dei sensori.

Introduzione ai sensori

Il framework dei sensori Android ti consente di accedere a molti tipi di sensori. Alcuni di questi sensori sono basati sull'hardware e altri sul software. I sensori basati sull'hardware sono componenti fisici integrati in un dispositivo portatile o tablet. Derivano i propri dati misurando direttamente proprietà ambientali specifiche, come accelerazione, intensità del campo geomagnetico o variazione angolare. I sensori basati su software non sono dispositivi fisici, anche se imitano i sensori basati su hardware. I sensori basati su software derivano i propri dati da uno o più sensori basati su hardware e a volte vengono chiamati sensori virtuali o sensori sintetici. Il sensore di accelerazione lineare e il sensore di gravità sono esempi di sensori basati su software. La tabella 1 riassume i sensori supportati dalla piattaforma Android.

Pochi dispositivi con Android hanno tutti i tipi di sensori. Ad esempio, la maggior parte dei dispositivi mobili e dei tablet è dotata di accelerometro e magnetometro, ma meno dispositivi hanno barometri o termometri. Inoltre, un dispositivo può avere più di un sensore di un determinato tipo. Ad esempio, un dispositivo può avere due sensori di gravità, ognuno con un intervallo diverso.

Tabella 1. Tipi di sensori supportati dalla piattaforma Android.

Sensore	Tipo	Descrizione	Utilizzi comuni
TYPE_ACCELEROMETER	Hardware	Misura la forza di accelerazione in m/s^2 applicata a un dispositivo su tutti e tre gli assi fisici (x, y e z), inclusa la forza di gravità.	Rilevamento dei movimenti (scuotimento, inclinazione e così via).
TYPE_AMBIENT_TEMPERATURE	Hardware	Misura la temperatura ambiente della stanza in gradi Celsius (°C). Vedi la nota di seguito.	Monitoraggio delle temperature dell'aria.
TYPE_GRAVITY	Software o hardware	Misura la forza di gravità in m/s^2 applicata a un dispositivo su tutti e tre gli assi fisici (x, y, z).	Rilevamento dei movimenti (scuotimento, inclinazione e così via).
TYPE_GYROSCOPE	Hardware	Misura la velocità di rotazione di un dispositivo in rad/s intorno a ciascuno dei tre assi fisici (x, y e z).	Rilevamento della rotazione (rotazione, svolta e così via).
TYPE_LIGHT	Hardware	Misura il livello di luce ambientale (illuminazione) in lx.	Controllare la luminosità dello schermo.
TYPE_LINEAR_ACCELERATION	Software o hardware	Misura la forza di accelerazione in m/s^2 applicata a un dispositivo su tutti e tre gli assi fisici (x, y e z), escludendo la forza di gravità.	Monitoraggio dell'accelerazione lungo un singolo asse.
TYPE_MAGNETIC_FIELD	Hardware	Misura il campo geomagnetico ambientale per tutti e tre gli assi fisici (x, y, z) in μT.	Creazione di una bussola.
TYPE_ORIENTATION	Software	Misura i gradi di rotazione che un dispositivo esegue intorno a tutti e tre gli assi fisici (x, y, z). A partire dal livello API 3, puoi ottenere la matrice di inclinazione e la matrice di rotazione per un dispositivo utilizzando il sensore di gravità e il sensore del campo geomagnetico insieme al metodo getRotationMatrix().	Determinare la posizione del dispositivo.
TYPE_PRESSURE	Hardware	Misura la pressione dell'aria ambiente in hPa o mbar.	Monitoraggio delle variazioni di pressione dell'aria.
TYPE_PROXIMITY	Hardware	Misura la prossimità di un oggetto in cm rispetto alla schermata di visualizzazione di un dispositivo. Questo sensore viene in genere utilizzato per determinare se un telefono viene tenuto vicino all'orecchio di una persona.	Posizione dello smartphone durante una chiamata.
TYPE_RELATIVE_HUMIDITY	Hardware	Misura l'umidità relativa dell'ambiente in percentuale (%).	Monitoraggio del punto di rugiada, dell'umidità assoluta e di quella relativa.
TYPE_ROTATION_VECTOR	Software o hardware	Misura l'orientamento di un dispositivo fornendo i tre elementi del vettore di rotazione del dispositivo.	Rilevamento dei movimenti e della rotazione.
TYPE_TEMPERATURE	Hardware	Misura la temperatura del dispositivo in gradi Celsius (°C). L'implementazione di questo sensore varia in base ai dispositivi e questo sensore è stato sostituito con il sensore TYPE_AMBIENT_TEMPERATURE nel livello API 14	Monitoraggio delle temperature.

Framework sensore

Puoi accedere a questi sensori e acquisire i dati grezzi dei sensori utilizzando il framework dei sensori Android. Il framework dei sensori fa parte del pacchetto android.hardware e include le seguenti classi e interfacce:

SensorManager

Puoi utilizzare questa classe per creare un'istanza del servizio sensore. Questa classe fornisce vari metodi per accedere ai sensori ed elencarli, registrare e annullare la registrazione dei listener di eventi del sensore e acquisire informazioni sull'orientamento. Questa classe fornisce anche diverse costanti del sensore che vengono utilizzate per segnalare la precisione del sensore, impostare le velocità di acquisizione dei dati e calibrare i sensori.

Sensor

Puoi utilizzare questa classe per creare un'istanza di un sensore specifico. Questa classe fornisce vari metodi che ti consentono di determinare le funzionalità di un sensore.

SensorEvent

Il sistema utilizza questa classe per creare un oggetto evento sensore, che fornisce informazioni su un evento sensore. Un oggetto evento sensore include le seguenti informazioni: i dati grezzi del sensore, il tipo di sensore che ha generato l'evento, la precisione dei dati e il timestamp dell'evento.

SensorEventListener

Puoi utilizzare questa interfaccia per creare due metodi di callback che ricevono notifiche (eventi del sensore) quando i valori del sensore cambiano o quando cambia la precisione del sensore.

In un'applicazione tipica, utilizzi queste API correlate ai sensori per eseguire due attività di base:

• Identificazione dei sensori e delle loro funzionalità

  L'identificazione dei sensori e delle loro funzionalità in fase di runtime è utile se la tua applicazione ha funzionalità che si basano su tipi o funzionalità di sensori specifici. Ad esempio, potresti voler identificare tutti i sensori presenti su un dispositivo e disattivare le funzionalità dell'applicazione che si basano su sensori non presenti. Allo stesso modo, potresti voler identificare tutti i sensori di un determinato tipo per poter scegliere l'implementazione del sensore che offre le prestazioni ottimali per la tua applicazione.

• Monitorare gli eventi dei sensori

  Il monitoraggio degli eventi dei sensori è il modo in cui acquisisci i dati non elaborati dei sensori. Un evento sensore si verifica ogni volta che un sensore rileva una variazione nei parametri che sta misurando. Un evento del sensore fornisce quattro informazioni: il nome del sensore che ha attivato l'evento, il timestamp dell'evento, la precisione dell'evento e i dati grezzi del sensore che hanno attivato l'evento.

Disponibilità dei sensori

Sebbene la disponibilità dei sensori vari da dispositivo a dispositivo, può variare anche tra le versioni di Android. Questo perché i sensori Android sono stati introdotti nel corso di diverse versioni della piattaforma. Ad esempio, molti sensori sono stati introdotti in Android 1.5 (livello API 3), ma alcuni non sono stati implementati e non erano disponibili per l'uso fino ad Android 2.3 (livello API 9). Allo stesso modo, in Android 2.3 (livello API 9) e Android 4.0 (livello API 14) sono stati introdotti diversi sensori. Due sensori sono stati ritirati e sostituiti con sensori più nuovi e migliori.

La tabella 2 riepiloga la disponibilità di ciascun sensore in base alla piattaforma. Sono elencate solo quattro piattaforme perché sono quelle che hanno comportato modifiche ai sensori. I sensori elencati come ritirati sono ancora disponibili sulle piattaforme successive (a condizione che il sensore sia presente su un dispositivo), in linea con la policy di compatibilità in avanti di Android.

Tabella 2. Disponibilità dei sensori per piattaforma.

Sensore	Android 4.0 (livello API 14)	Android 2.3 (livello API 9)	Android 2.2 (livello API 8)	Android 1.5 (livello API 3)
TYPE_ACCELEROMETER	Sì	Sì	Sì	Sì
TYPE_AMBIENT_TEMPERATURE	Sì	n/a	n/d	n/a
TYPE_GRAVITY	Sì	Sì	n/a	n/a
TYPE_GYROSCOPE	Sì	Sì	n/a^1	n/a^1
TYPE_LIGHT	Sì	Sì	Sì	Sì
TYPE_LINEAR_ACCELERATION	Sì	Sì	n/a	n/a
TYPE_MAGNETIC_FIELD	Sì	Sì	Sì	Sì
TYPE_ORIENTATION	Sì^2	Sì^2	Sì^2	Sì
TYPE_PRESSURE	Sì	Sì	n/a^1	n/a^1
TYPE_PROXIMITY	Sì	Sì	Sì	Sì
TYPE_RELATIVE_HUMIDITY	Sì	n/a	n/d	n/a
TYPE_ROTATION_VECTOR	Sì	Sì	n/a	n/a
TYPE_TEMPERATURE	Sì^2	Sì	Sì	Sì

¹ Questo tipo di sensore è stato aggiunto in Android 1.5 (livello API 3), ma non era disponibile per l'uso fino ad Android 2.3 (livello API 9).

² Questo sensore è disponibile, ma è stato ritirato.

Identificazione dei sensori e delle funzionalità dei sensori

Il framework dei sensori Android fornisce diversi metodi che semplificano la determinazione in fase di runtime dei sensori presenti su un dispositivo. L'API fornisce anche metodi che consentono di determinare le funzionalità di ciascun sensore, come la portata massima, la risoluzione e i requisiti di alimentazione.

Per identificare i sensori presenti su un dispositivo, devi prima ottenere un riferimento al servizio sensori. Per farlo, crea un'istanza della classe SensorManager chiamando il metodo getSystemService() e passando l'argomento SENSOR_SERVICE. Ad esempio:

Kotlin

private lateinit var sensorManager: SensorManager
...
sensorManager = getSystemService(Context.SENSOR_SERVICE) as SensorManager

Java

private SensorManager sensorManager;
...
sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);

Successivamente, puoi ottenere un elenco di tutti i sensori su un dispositivo chiamando il metodo getSensorList() e utilizzando la costante TYPE_ALL. Ad esempio:

Kotlin

val deviceSensors: List<Sensor> = sensorManager.getSensorList(Sensor.TYPE_ALL)

Java

List<Sensor> deviceSensors = sensorManager.getSensorList(Sensor.TYPE_ALL);

Se vuoi elencare tutti i sensori di un determinato tipo, puoi utilizzare un'altra costante anziché TYPE_ALL, ad esempio TYPE_GYROSCOPE, TYPE_LINEAR_ACCELERATION o TYPE_GRAVITY.

Puoi anche determinare se un tipo specifico di sensore esiste su un dispositivo utilizzando il metodo getDefaultSensor() e passando la costante di tipo per un sensore specifico. Se un dispositivo ha più di un sensore di un determinato tipo, uno dei sensori deve essere designato come sensore predefinito. Se non esiste un sensore predefinito per un determinato tipo di sensore, la chiamata al metodo restituisce null, il che significa che il dispositivo non dispone di quel tipo di sensore. Ad esempio, il seguente codice controlla se è presente un magnetometro su un dispositivo:

Kotlin

private lateinit var sensorManager: SensorManager
...
sensorManager = getSystemService(Context.SENSOR_SERVICE) as SensorManager
if (sensorManager.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD) != null) {
    // Success! There's a magnetometer.
} else {
    // Failure! No magnetometer.
}

Java

private SensorManager sensorManager;
...
sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
if (sensorManager.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD) != null){
    // Success! There's a magnetometer.
} else {
    // Failure! No magnetometer.
}

Nota: Android non richiede ai produttori di dispositivi di integrare tipi particolari di sensori nei loro dispositivi Android, pertanto i dispositivi possono avere un'ampia gamma di configurazioni dei sensori.

Oltre a elencare i sensori presenti su un dispositivo, puoi utilizzare i metodi pubblici della classe Sensor per determinare le funzionalità e gli attributi dei singoli sensori. Ciò è utile se vuoi che la tua applicazione si comporti in modo diverso in base ai sensori o alle funzionalità dei sensori disponibili su un dispositivo. Ad esempio, puoi utilizzare i metodi getResolution() e getMaximumRange() per ottenere la risoluzione e l'intervallo massimo di misurazione di un sensore. Puoi anche utilizzare il metodo getPower() per ottenere i requisiti di alimentazione di un sensore.

Due dei metodi pubblici sono particolarmente utili se vuoi ottimizzare la tua applicazione per sensori di produttori diversi o versioni diverse di un sensore. Ad esempio, se la tua applicazione deve monitorare i gesti dell'utente, come l'inclinazione e lo scuotimento, puoi creare un insieme di regole di filtraggio e ottimizzazioni dei dati per i dispositivi più recenti che hanno un sensore di gravità di un fornitore specifico e un altro insieme di regole di filtraggio e ottimizzazioni dei dati per i dispositivi che non hanno un sensore di gravità e hanno solo un accelerometro. Il seguente esempio di codice mostra come utilizzare i metodi getVendor() e getVersion() per eseguire questa operazione. In questo esempio, cerchiamo un sensore di gravità che elenca Google LLC come fornitore e ha un numero di versione pari a 3. Se questo sensore non è presente sul dispositivo, proviamo a utilizzare l'accelerometro.

Kotlin

private lateinit var sensorManager: SensorManager
private var mSensor: Sensor? = null

...

sensorManager = getSystemService(Context.SENSOR_SERVICE) as SensorManager

if (sensorManager.getDefaultSensor(Sensor.TYPE_GRAVITY) != null) {
    val gravSensors: List<Sensor> = sensorManager.getSensorList(Sensor.TYPE_GRAVITY)
    // Use the version 3 gravity sensor.
    mSensor = gravSensors.firstOrNull { it.vendor.contains("Google LLC") && it.version == 3 }
}
if (mSensor == null) {
    // Use the accelerometer.
    mSensor = if (sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER) != null) {
        sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER)
    } else {
        // Sorry, there are no accelerometers on your device.
        // You can't play this game.
        null
    }
}

Java

private SensorManager sensorManager;
private Sensor mSensor;

...

sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
mSensor = null;

if (sensorManager.getDefaultSensor(Sensor.TYPE_GRAVITY) != null){
    List<Sensor> gravSensors = sensorManager.getSensorList(Sensor.TYPE_GRAVITY);
    for(int i=0; i<gravSensors.size(); i++) {
        if ((gravSensors.get(i).getVendor().contains("Google LLC")) &&
           (gravSensors.get(i).getVersion() == 3)){
            // Use the version 3 gravity sensor.
            mSensor = gravSensors.get(i);
        }
    }
}
if (mSensor == null){
    // Use the accelerometer.
    if (sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER) != null){
        mSensor = sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER);
    } else{
        // Sorry, there are no accelerometers on your device.
        // You can't play this game.
    }
}

Un altro metodo utile è getMinDelay(), che restituisce l'intervallo di tempo minimo (in microsecondi) che un sensore può utilizzare per rilevare i dati. Qualsiasi sensore che restituisce un valore diverso da zero per il metodo getMinDelay() è un sensore di streaming. I sensori di streaming rilevano i dati a intervalli regolari e sono stati introdotti in Android 2.3 (livello API 9). Se un sensore restituisce zero quando chiami il metodo getMinDelay(), significa che non è un sensore di streaming perché segnala i dati solo quando si verifica una modifica nei parametri che rileva.

Il metodo getMinDelay() è utile perché ti consente di determinare la velocità massima con cui un sensore può acquisire dati. Se alcune funzionalità della tua applicazione richiedono tassi di acquisizione dati elevati o un sensore di streaming, puoi utilizzare questo metodo per determinare se un sensore soddisfa questi requisiti e poi attivare o disattivare le funzionalità pertinenti nella tua applicazione di conseguenza.

Attenzione:la velocità massima di acquisizione dei dati di un sensore non è necessariamente la velocità con cui il framework del sensore fornisce i dati del sensore alla tua applicazione. Il framework dei sensori segnala i dati tramite gli eventi dei sensori e diversi fattori influenzano la velocità con cui la tua applicazione riceve gli eventi dei sensori. Per ulteriori informazioni, vedi Monitoraggio degli eventi dei sensori.

Monitoraggio degli eventi dei sensori

Per monitorare i dati non elaborati dei sensori, devi implementare due metodi di callback esposti tramite l'interfaccia SensorEventListener: onAccuracyChanged() e onSensorChanged(). Il sistema Android chiama questi metodi ogni volta che si verifica quanto segue:

• La precisione di un sensore cambia.

  In questo caso, il sistema richiama il metodo onAccuracyChanged(), fornendoti un riferimento all'oggetto Sensor modificato e alla nuova precisione del sensore. L'accuratezza è rappresentata da una delle quattro costanti di stato: SENSOR_STATUS_ACCURACY_LOW, SENSOR_STATUS_ACCURACY_MEDIUM, SENSOR_STATUS_ACCURACY_HIGH, o SENSOR_STATUS_UNRELIABLE.

• Un sensore segnala un nuovo valore.

  In questo caso, il sistema richiama il metodo onSensorChanged(), fornendoti un oggetto SensorEvent. Un oggetto SensorEvent contiene informazioni sui nuovi dati dei sensori, tra cui: l'accuratezza dei dati, il sensore che ha generato i dati, il timestamp in cui sono stati generati i dati e i nuovi dati registrati dal sensore.

Il seguente codice mostra come utilizzare il metodo onSensorChanged() per monitorare i dati del sensore di luce. Questo esempio mostra i dati grezzi dei sensori in un TextView definito nel file main.xml come sensor_data.

Kotlin

class SensorActivity : Activity(), SensorEventListener {
    private lateinit var sensorManager: SensorManager
    private var mLight: Sensor? = null

    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main)

        sensorManager = getSystemService(Context.SENSOR_SERVICE) as SensorManager
        mLight = sensorManager.getDefaultSensor(Sensor.TYPE_LIGHT)
    }

    override fun onAccuracyChanged(sensor: Sensor, accuracy: Int) {
        // Do something here if sensor accuracy changes.
    }

    override fun onSensorChanged(event: SensorEvent) {
        // The light sensor returns a single value.
        // Many sensors return 3 values, one for each axis.
        val lux = event.values[0]
        // Do something with this sensor value.
    }

    override fun onResume() {
        super.onResume()
        mLight?.also { light ->
            sensorManager.registerListener(this, light, SensorManager.SENSOR_DELAY_NORMAL)
        }
    }

    override fun onPause() {
        super.onPause()
        sensorManager.unregisterListener(this)
    }
}

Java

public class SensorActivity extends Activity implements SensorEventListener {
    private SensorManager sensorManager;
    private Sensor mLight;

    @Override
    public final void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
        mLight = sensorManager.getDefaultSensor(Sensor.TYPE_LIGHT);
    }

    @Override
    public final void onAccuracyChanged(Sensor sensor, int accuracy) {
        // Do something here if sensor accuracy changes.
    }

    @Override
    public final void onSensorChanged(SensorEvent event) {
        // The light sensor returns a single value.
        // Many sensors return 3 values, one for each axis.
        float lux = event.values[0];
        // Do something with this sensor value.
    }

    @Override
    protected void onResume() {
        super.onResume();
        sensorManager.registerListener(this, mLight, SensorManager.SENSOR_DELAY_NORMAL);
    }

    @Override
    protected void onPause() {
        super.onPause();
        sensorManager.unregisterListener(this);
    }
}

In questo esempio, il ritardo dei dati predefinito (SENSOR_DELAY_NORMAL) viene specificato quando viene richiamato il metodo registerListener(). Il ritardo dei dati (o frequenza di campionamento) controlla l'intervallo in cui gli eventi dei sensori vengono inviati alla tua applicazione tramite il metodo di callback onSensorChanged(). Il ritardo dei dati predefinito è adatto al monitoraggio delle modifiche tipiche dell'orientamento dello schermo e utilizza un ritardo di 200.000 microsecondi. Puoi specificare altri ritardi dei dati, ad esempio SENSOR_DELAY_GAME (ritardo di 20.000 microsecondi), SENSOR_DELAY_UI (ritardo di 60.000 microsecondi) o SENSOR_DELAY_FASTEST (ritardo di 0 microsecondi). A partire da Android 3.0 (livello API 11), puoi specificare il ritardo anche come valore assoluto (in microsecondi).

Il ritardo che specifichi è solo un suggerimento. Il sistema Android e altre applicazioni possono modificare questo ritardo. Come best practice, devi specificare il ritardo più lungo possibile perché il sistema in genere utilizza un ritardo inferiore a quello specificato (ovvero, devi scegliere il tasso di campionamento più lento che soddisfi comunque le esigenze della tua applicazione). L'utilizzo di un ritardo maggiore impone un carico inferiore sul processore e quindi consuma meno energia.

Non esiste un metodo pubblico per determinare la velocità con cui il framework dei sensori invia gli eventi dei sensori alla tua applicazione. Tuttavia, puoi utilizzare i timestamp associati a ciascun evento dei sensori per calcolare la frequenza di campionamento su più eventi. Una volta impostata, non dovresti dover modificare la frequenza di campionamento (ritardo). Se per qualche motivo devi modificare il ritardo, dovrai annullare la registrazione e registrare nuovamente il listener del sensore.

È anche importante notare che questo esempio utilizza i metodi di callback onResume() e onPause() per registrare e annullare la registrazione del listener di eventi del sensore. Come best practice, dovresti sempre disattivare i sensori che non ti servono, soprattutto quando la tua attività è in pausa. In caso contrario, la batteria può scaricarsi in poche ore perché alcuni sensori hanno requisiti di alimentazione elevati e possono consumare rapidamente la batteria. Il sistema non disattiva automaticamente i sensori quando lo schermo si spegne.

Gestione di diverse configurazioni dei sensori

Android non specifica una configurazione standard dei sensori per i dispositivi, il che significa che i produttori di dispositivi possono incorporare qualsiasi configurazione dei sensori che desiderano nei loro dispositivi basati su Android. Di conseguenza, i dispositivi possono includere una varietà di sensori in un'ampia gamma di configurazioni. Se la tua applicazione si basa su un tipo specifico di sensore, devi assicurarti che il sensore sia presente su un dispositivo in modo che la tua app possa essere eseguita correttamente.

Hai due opzioni per assicurarti che un determinato sensore sia presente su un dispositivo:

• Rileva i sensori in fase di runtime e attiva o disattiva le funzionalità dell'applicazione in base alle esigenze.
• Utilizza i filtri di Google Play per scegliere come target i dispositivi con configurazioni specifiche dei sensori.

Ogni opzione è descritta nelle sezioni seguenti.

Rilevamento dei sensori in fase di runtime

Se la tua applicazione utilizza un tipo specifico di sensore, ma non si basa su di esso, puoi utilizzare il framework dei sensori per rilevare il sensore in fase di runtime e poi disattivare o attivare le funzionalità dell'applicazione in modo appropriato. Ad esempio, un'applicazione di navigazione potrebbe utilizzare il sensore di temperatura, il sensore di pressione, il sensore GPS e il sensore del campo geomagnetico per visualizzare la temperatura, la pressione barometrica, la posizione e la direzione della bussola. Se un dispositivo non dispone di un sensore di pressione, puoi utilizzare il framework dei sensori per rilevare l'assenza del sensore di pressione in fase di runtime e disattivare la parte dell'interfaccia utente dell'applicazione che mostra la pressione. Ad esempio, il seguente codice controlla se è presente un sensore di pressione su un dispositivo:

Kotlin

private lateinit var sensorManager: SensorManager
...
sensorManager = getSystemService(Context.SENSOR_SERVICE) as SensorManager

if (sensorManager.getDefaultSensor(Sensor.TYPE_PRESSURE) != null) {
    // Success! There's a pressure sensor.
} else {
    // Failure! No pressure sensor.
}

Java

private SensorManager sensorManager;
...
sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
if (sensorManager.getDefaultSensor(Sensor.TYPE_PRESSURE) != null){
    // Success! There's a pressure sensor.
} else {
    // Failure! No pressure sensor.
}

Utilizzo dei filtri di Google Play per scegliere come target configurazioni specifiche dei sensori

Se pubblichi la tua applicazione su Google Play, puoi utilizzare l'elemento <uses-feature> nel file manifest per filtrare la tua applicazione dai dispositivi che non hanno la configurazione del sensore appropriata per la tua applicazione. L'elemento <uses-feature> ha diversi descrittori hardware che ti consentono di filtrare le applicazioni in base alla presenza di sensori specifici. I sensori che puoi elencare includono: accelerometro, barometro, bussola (campo geomagnetico), giroscopio, luce e prossimità. Di seguito è riportato un esempio di voce del manifest che filtra le app che non hanno un accelerometro:

<uses-feature android:name="android.hardware.sensor.accelerometer"
              android:required="true" />

Se aggiungi questo elemento e questo descrittore al manifest della tua applicazione, gli utenti vedranno la tua applicazione su Google Play solo se il loro dispositivo è dotato di un accelerometro.

Devi impostare il descrittore su android:required="true" solo se la tua applicazione si basa interamente su un sensore specifico. Se la tua applicazione utilizza un sensore per alcune funzionalità, ma funziona comunque senza il sensore, devi elencare il sensore nell'elemento <uses-feature>, ma impostare il descrittore su android:required="false". In questo modo, i dispositivi possono installare la tua app anche se non dispongono di quel particolare sensore. Si tratta anche di una best practice di gestione dei progetti che ti aiuta a tenere traccia delle funzionalità utilizzate dalla tua applicazione. Tieni presente che, se la tua applicazione utilizza un sensore specifico, ma funziona comunque senza, devi rilevare il sensore in fase di runtime e disattivare o attivare le funzionalità dell'applicazione in modo appropriato.

Sistema di coordinate del sensore

In generale, il framework dei sensori utilizza un sistema di coordinate standard a tre assi per esprimere i valori dei dati. Per la maggior parte dei sensori, il sistema di coordinate è definito rispetto allo schermo del dispositivo quando questo è tenuto nel suo orientamento predefinito (vedi figura 1). Quando un dispositivo viene tenuto nel suo orientamento predefinito, l'asse X è orizzontale e punta a destra, l'asse Y è verticale e punta verso l'alto e l'asse Z punta verso l'esterno della superficie dello schermo. In questo sistema, le coordinate dietro lo schermo hanno valori Z negativi. Questo sistema di coordinate viene utilizzato dai seguenti sensori:

Figura 1. Sistema di coordinate (relativo a un dispositivo) utilizzato dall'API Sensor.

• Sensore di accelerazione
• Sensore di gravità
• Giroscopio
• Sensore di accelerazione lineare
• Sensore del campo geomagnetico

L'aspetto più importante da comprendere di questo sistema di coordinate è che gli assi non vengono invertiti quando l'orientamento dello schermo del dispositivo cambia, ovvero il sistema di coordinate del sensore non cambia mai quando il dispositivo si sposta. Questo comportamento è identico a quello del sistema di coordinate OpenGL.

Un altro punto da capire è che la tua applicazione non deve presupporre che l'orientamento naturale (predefinito) di un dispositivo sia verticale. L'orientamento naturale di molti tablet è orizzontale. Inoltre, il sistema di coordinate del sensore si basa sempre sull'orientamento naturale di un dispositivo.

Infine, se la tua applicazione associa i dati dei sensori alla visualizzazione sullo schermo, devi utilizzare il metodo getRotation() per determinare la rotazione dello schermo e poi il metodo remapCoordinateSystem() per mappare le coordinate del sensore alle coordinate dello schermo. Devi farlo anche se il manifest specifica la visualizzazione solo verticale.

Nota:alcuni sensori e metodi utilizzano un sistema di coordinate relativo al sistema di riferimento del mondo (anziché a quello del dispositivo). Questi sensori e metodi restituiscono dati che rappresentano il movimento o la posizione del dispositivo rispetto alla Terra. Per ulteriori informazioni, consulta il metodo getOrientation(), il metodo getRotationMatrix(), il sensore di orientamento e il sensore del vettore di rotazione.

Limitazione di frequenza del sensore

Per proteggere le informazioni potenzialmente sensibili sugli utenti, se la tua app ha come target Android 12 (livello API 31) o versioni successive, il sistema impone un limite alla frequenza di aggiornamento dei dati di alcuni sensori di movimento e di posizione. Questi dati includono i valori registrati dall'accelerometro, dal giroscopio e dal sensore del campo geomagnetico.

Il limite della frequenza di aggiornamento dipende dalla modalità di accesso ai dati dei sensori:

• Se chiami il metodo registerListener() per monitorare gli eventi dei sensori, la frequenza di campionamento dei sensori è limitata a 200 Hz. Questo vale per tutte le varianti sovraccariche del metodo registerListener().
• Se utilizzi la classe SensorDirectChannel, la frequenza di campionamento del sensore è limitata a RATE_NORMAL, che di solito è di circa 50 Hz.

Se la tua app deve raccogliere dati dei sensori di movimento a una velocità superiore, devi dichiarare l'autorizzazione HIGH_SAMPLING_RATE_SENSORS, come mostrato nello snippet di codice seguente. In caso contrario, se la tua app tenta di raccogliere dati del sensore di movimento a una velocità superiore senza dichiarare questa autorizzazione, si verifica un SecurityException.

AndroidManifest.xml

<manifest ...>
    <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS"/>
    <application ...>
        ...
    </application>
</manifest>

Nota: se l'utente disattiva l'accesso al microfono utilizzando i pulsanti di attivazione/disattivazione del dispositivo, i sensori di movimento e i sensori di posizione sono sempre limitati nella frequenza, indipendentemente dal fatto che tu dichiari l'autorizzazione HIGH_SAMPLING_RATE_SENSORS.

Best practice per l'accesso e l'utilizzo dei sensori

Quando progetti l'implementazione dei sensori, assicurati di seguire le linee guida descritte in questa sezione. Queste linee guida sono best practice consigliate per chiunque utilizzi il framework dei sensori per accedere ai sensori e acquisire i dati dei sensori.

Raccogliere i dati dei sensori solo in primo piano

Sui dispositivi con Android 9 (livello API 28) o versioni successive, le app in esecuzione in background hanno le seguenti limitazioni:

• I sensori che utilizzano la modalità di report continua, come accelerometri e giroscopi, non ricevono eventi.
• I sensori che utilizzano le modalità di reporting on-change o one-shot non ricevono eventi.

Date queste limitazioni, è meglio rilevare gli eventi dei sensori quando l'app è in primo piano o nell'ambito di un servizio in primo piano.

Annulla la registrazione dei listener dei sensori

Assicurati di annullare la registrazione di un listener del sensore quando hai finito di utilizzare il sensore o quando l'attività del sensore si interrompe. Se un listener del sensore è registrato e la sua attività è in pausa, il sensore continuerà ad acquisire dati e a utilizzare le risorse della batteria, a meno che tu non annulli la registrazione del sensore. Il seguente codice mostra come utilizzare il metodo onPause() per annullare la registrazione di un listener:

Kotlin

private lateinit var sensorManager: SensorManager
...
override fun onPause() {
    super.onPause()
    sensorManager.unregisterListener(this)
}

Java

private SensorManager sensorManager;
...
@Override
protected void onPause() {
    super.onPause();
    sensorManager.unregisterListener(this);
}

Per ulteriori informazioni, vedi unregisterListener(SensorEventListener).

Testare con l'emulatore Android

L'emulatore Android include un insieme di controlli dei sensori virtuali che ti consentono di testare sensori come accelerometro, temperatura ambiente, magnetometro, prossimità, luce e altro ancora.

L'emulatore utilizza una connessione con un dispositivo Android su cui è in esecuzione l'app SdkControllerSensor. Tieni presente che questa app è disponibile solo sui dispositivi con Android 4.0 (livello API 14) o versioni successive. Se sul dispositivo è installato Android 4.0, deve essere installata la revisione 2. L'app SdkControllerSensor monitora le modifiche ai sensori sul dispositivo e le trasmette all'emulatore. L'emulatore viene quindi trasformato in base ai nuovi valori che riceve dai sensori sul tuo dispositivo.

Puoi visualizzare il codice sorgente dell'app SdkControllerSensor nella seguente posizione:

$ your-android-sdk-directory/tools/apps/SdkController

Per trasferire i dati tra il dispositivo e l'emulatore, segui questi passaggi:

1. Verifica che il debug USB sia abilitato sul dispositivo.
2. Collega il dispositivo alla macchina di sviluppo utilizzando un cavo USB.
3. Avvia l'app SdkControllerSensor sul tuo dispositivo.
4. Nell'app, seleziona i sensori che vuoi emulare.

5. Esegui questo comando adb:

$ adb forward tcp:1968 tcp:1968

6. Avvia l'emulatore. Ora dovresti essere in grado di applicare trasformazioni all'emulatore spostando il dispositivo.

Nota : se i movimenti che esegui sul dispositivo fisico non trasformano l'emulatore, prova a eseguire di nuovo il comando adb del passaggio 5.

Per saperne di più, consulta la guida all'emulatore Android.

Non bloccare il metodo onSensorChanged()

I dati dei sensori possono cambiare a una velocità elevata, il che significa che il sistema potrebbe chiamare il metodo onSensorChanged(SensorEvent) abbastanza spesso. Come best practice, dovresti fare il meno possibile all'interno del metodo onSensorChanged(SensorEvent) per non bloccarlo. Se la tua applicazione richiede di filtrare o ridurre i dati dei sensori, devi eseguire questa operazione al di fuori del metodo onSensorChanged(SensorEvent).

Evita di utilizzare metodi o tipi di sensori deprecati

Diversi metodi e costanti sono stati ritirati. In particolare, il tipo di sensore TYPE_ORIENTATION è stato ritirato. Per ottenere i dati di orientamento, devi utilizzare il metodo getOrientation(). Allo stesso modo, il tipo di sensore TYPE_TEMPERATURE è stato ritirato. Devi utilizzare il tipo di sensore TYPE_AMBIENT_TEMPERATURE sui dispositivi con Android 4.0.

Verificare i sensori prima di utilizzarli

Verifica sempre che un sensore esista su un dispositivo prima di tentare di acquisire dati. Non presupporre che un sensore esista solo perché è un sensore utilizzato di frequente. I produttori di dispositivi non sono tenuti a fornire sensori particolari nei loro dispositivi.

Scegliere con attenzione i ritardi dei sensori

Quando registri un sensore con il metodo registerListener(), assicurati di scegliere una frequenza di invio adatta alla tua applicazione o al tuo caso d'uso. I sensori possono fornire dati a velocità molto elevate. Consentire al sistema di inviare dati aggiuntivi che non ti servono spreca risorse di sistema e consuma batteria.