Intervallo tra i dispositivi

Android 16 introduce il modulo Ranging, che fornisce un'interfaccia unificata e standardizzata per la misurazione precisa della distanza tra i dispositivi. Puoi utilizzare questa superficie API per misurare la distanza e la posizione dei dispositivi peer senza dover gestire singolarmente ogni tecnologia di misurazione della distanza.

Il modulo Ranging supporta le seguenti tecnologie:

Funzionalità e disponibilità di misurazione della distanza

La classe RangingManager fornisce alle app informazioni sulle tecnologie di misurazione della distanza supportate dal dispositivo locale, nonché sulla disponibilità e sulle funzionalità di ogni tecnologia. Le app possono registrarsi per un Callback per ricevere aggiornamenti su eventuali modifiche alla disponibilità o alle funzionalità delle tecnologie supportate.

Ruoli dei dispositivi

Un dispositivo che partecipa a una sessione di misurazione della distanza deve essere un iniziatore o un risponditore. Il dispositivo iniziatore avvia la sessione di misurazione della distanza con uno o più dispositivi risponditori. Un dispositivo risponditore risponde alle richieste di misurazione della distanza di un solo iniziatore alla volta. Puoi specificare il ruolo di un determinato dispositivo in una sessione di misurazione della distanza con la RangingPreference classe.

Tipi di sessione di misurazione della distanza

Quando si avvia una sessione di misurazione della distanza tra i dispositivi, spesso è necessario stabilire un trasporto di dati fuori banda (OOB) per scambiare i parametri della sessione.

Il modulo Ranging può gestire le negoziazioni OOB per te, ma supporta anche le implementazioni OOB personalizzate.

Figura 1. Flusso OOB per i tipi di sessione.

Implementazione OOB predefinita

In questo tipo di sessione (RANGING_SESSION_OOB), il modulo Ranging gestisce le negoziazioni OOB per avviare una sessione di misurazione della distanza. Seleziona i parametri adatti in base alle preferenze di misurazione della distanza fornite dall'app e utilizza le tecnologie appropriate in base a quelle supportate da entrambi i dispositivi. Questo tipo di sessione utilizza una OOB specificationstandardizzata.

Il modulo Ranging definisce solo il formato e la sequenza dei dati OOB da utilizzare per interagire con un dispositivo peer. Non gestisce l'individuazione dei dispositivi peer o la creazione della connessione.

Implementazione OOB personalizzata

In questo tipo di sessione (RANGING_SESSION_RAW), l'app ignora il flusso OOB del modulo Ranging e gestisce la propria negoziazione e i propri parametri OOB. Ciò significa che l'app deve determinare le tecnologie supportate dal dispositivo peer, negoziare i parametri di misurazione della distanza e avviare la sessione di misurazione della distanza.

Preferenze di misurazione della distanza

Utilizza un RangingPreference oggetto per specificare i parametri selezionati per una sessione di misurazione della distanza. È incluso quanto segue:

  • Ruolo del dispositivo. Indica se il dispositivo sarà l'iniziatore o il risponditore.
  • Configurazione della misurazione della distanza. Un oggetto RangingConfig specifica il tipo di sessione di misurazione della distanza e altri parametri necessari per avviare una sessione di misurazione della distanza.
  • Configurazione della sessione. Un oggetto SessionConfig specifica i parametri da applicare alla sessione di misurazione della distanza, come il limite di misurazione, la fusione dei sensori, la configurazione del recinto virtuale e altro ancora.

Autorizzazione di misurazione della distanza

Il modulo Ranging richiede una nuova autorizzazione unificata (android.permission.RANGING) per accedere a tutte le tecnologie di misurazione della distanza attuali e future. Questa autorizzazione è inclusa nell'elenco NEARBY_DEVICES_PERMISSIONS.

<uses-permission android:name="android.permission.RANGING" />

Restrizioni e limitazioni

Il modulo Ranging potrebbe limitare la misurazione della distanza per diversi motivi, tra cui:

  • Le app di terze parti possono eseguire la misurazione della distanza in background solo con la banda ultralarga e solo sui dispositivi supportati. La misurazione della distanza in background con altre tecnologie non è consentita.
  • La misurazione della distanza non è consentita quando è stato raggiunto il numero massimo di sessioni di misurazione della distanza simultanee per dispositivo.
  • La misurazione della distanza potrebbe essere limitata a causa di problemi di integrità del sistema, come batteria, prestazioni o memoria.

Il modulo Ranging presenta anche le seguenti limitazioni note:

  • Il modulo Ranging supporta solo la fornitura di dati di misurazione della distanza ai dispositivi peer per la banda ultralarga. Per altre tecnologie, il modulo Ranging fornisce i dati di misurazione della distanza solo al dispositivo iniziatore.
  • Il modulo Ranging supporta solo l'aggiunta dinamica di dispositivi in modalità di misurazione della distanza non elaborata e solo per la banda ultralarga.
  • Il modulo Ranging non supporta le sessioni di banda ultralarga da uno a molti per le implementazioni OOB predefinite. Se passi più handle di dispositivi, il modulo crea una sessione uno a uno per ogni dispositivo peer che supporta la banda ultralarga.

Eseguire una sessione di misurazione della distanza

Per eseguire una sessione di misurazione della distanza utilizzando il modulo Ranging:

  1. Verifica che tutti i dispositivi utilizzino Android 16 o versioni successive.
  2. Richiedi l'android.permission.RANGING autorizzazione nel file manifest dell'app.
  3. Valuta le funzionalità e la disponibilità delle tecnologie di misurazione della distanza.
  4. Individua un dispositivo peer per le operazioni di misurazione della distanza.
  5. Stabilisci una connessione per uno scambio fuori banda, utilizzando uno dei tipi di sessione descritti in Tipi di sessione di misurazione della distanza.
  6. Avvia la misurazione della distanza e acquisisci continuamente i dati di misurazione della distanza.
  7. Termina la sessione di misurazione della distanza.

Il seguente esempio di codice illustra questi passaggi sia per il ruolo di iniziatore sia per il ruolo di risponditore.

Kotlin

class RangingApp {

    // Starts a ranging session on the initiator side.
    fun startRangingInitiator(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback)

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        val config = OobInitiatorRangingConfig.Builder()
            .setFastestRangingInterval(Duration.ofMillis(100))
            .setSlowestRangingInterval(Duration.ofMillis(5000))
            .setRangingMode(RANGING_MODE_AUTO)
            .setSecurityLevel(SECURITY_LEVEL_BASIC)
            .addDeviceHandle(deviceHandle)
            .build()

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build()

        // Start ranging session.
        session.start(preference)

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop()
    }

    // Starts a ranging session on the responder side.
    fun startRangingResponder(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback)

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        val config = OobResponderRangingConfig.Builder(deviceHandle).build()

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build()

        // Start the ranging session.
        session.start(preference)

        // Stop the ranging session
        session.stop()
    }
}

Java

public class RangingApp {

    // Starts a ranging session on the initiator side.
    void startRangingInitiator(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        OobInitiatorRangingConfig config = new OobInitiatorRangingConfig.Builder()
                .setFastestRangingInterval(Duration.ofMillis(100))
                .setSlowestRangingInterval(Duration.ofMillis(5000))
                .setRangingMode(RANGING_MODE_AUTO)
                .setSecurityLevel(SECURITY_LEVEL_BASIC)
                .addDeviceHandle(deviceHandle)
                .build();

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build();

        // Start ranging session.
        session.start(preference);

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop();

    }

    // Starts a ranging session on the responder side.
    void startRangingResponder(Context context,  DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        OobResponderRangingConfig config = new OobResponderRangingConfig.Builder(  deviceHandle).build();

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build();

        // Start the ranging session.
        session.start(preference);

        // Stop the ranging session
        session.stop();
    }
}

Interoperabilità UWB con i dispositivi iOS

Il modulo Ranging supporta l'interoperabilità con i dispositivi iOS tramite la banda ultralarga (UWB). Per misurare la distanza con un dispositivo iOS, devi utilizzare un'implementazione OOB personalizzata e configurare la sessione di misurazione della distanza con parametri specifici che corrispondono al protocollo di accessori di interazione nelle vicinanze di Apple. Per riferimento, consulta l'app di esempio.

Quando crei RangingPreference, utilizza RawRangingDevice e UwbRangingParams per specificare la configurazione. I seguenti parametri sono fondamentali per l'interoperabilità con iOS:

  • ID configurazione: utilizza UwbRangingParams.CONFIG_UNICAST_DS_TWR.
  • Informazioni sulla chiave di sessione: fornisci un array di byte contenente l'ID fornitore e l'IV STS statico.
  • Canale complesso: imposta il numero di canale e l'indice del preambolo in modo che corrispondano alla configurazione del dispositivo iOS.

Il seguente snippet di codice mostra come creare un RangingPreference per un dispositivo iniziatore che misura la distanza con un risponditore iOS:

Kotlin

// Create UwbRangingParams with iOS-specific configuration
val uwbRangingParams = UwbRangingParams.Builder(
    sessionId,
    UwbRangingParams.CONFIG_UNICAST_DS_TWR,
    sourceAddress,
    destinationAddress
)
    .setComplexChannel(
        UwbComplexChannel.Builder()
            .setChannel(channelNumber)
            .setPreambleIndex(preambleIndex)
            .build()
    )
    .setRangingUpdateRate(updateRate)
    .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV
    .setSlotDuration(slotDuration)
    .build()

// Create RawRangingDevice
val rawRangingDevice = RawRangingDevice.Builder()
    .setRangingDevice(RangingDevice.Builder().build())
    .setUwbRangingParams(uwbRangingParams)
    .build()

// Create SessionConfig
val sessionConfig = SessionConfig.Builder()
    .setAngleOfArrivalNeeded(true)
    .setDataNotificationConfig(DataNotificationConfig.Builder()
        .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE)
        .build())
    .build()

// Create RangingPreference for the initiator
val preference = RangingPreference.Builder(
    RangingPreference.DEVICE_ROLE_INITIATOR,
    RawInitiatorRangingConfig.Builder()
        .addRawRangingDevice(rawRangingDevice)
        .build()
)
    .setSessionConfig(sessionConfig)
    .build()

Java

// Create UwbRangingParams with iOS-specific configuration
UwbRangingParams uwbRangingParams = new UwbRangingParams.Builder(
        sessionId,
        UwbRangingParams.CONFIG_UNICAST_DS_TWR,
        sourceAddress,
        destinationAddress)
        .setComplexChannel(new UwbComplexChannel.Builder()
                .setChannel(channelNumber)
                .setPreambleIndex(preambleIndex)
                .build())
        .setRangingUpdateRate(updateRate)
        .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV
        .setSlotDuration(slotDuration)
        .build();

// Create RawRangingDevice
RawRangingDevice rawRangingDevice = new RawRangingDevice.Builder()
        .setRangingDevice(new RangingDevice.Builder().build())
        .setUwbRangingParams(uwbRangingParams)
        .build();

// Create SessionConfig
SessionConfig sessionConfig = new SessionConfig.Builder()
        .setAngleOfArrivalNeeded(true)
        .setDataNotificationConfig(new DataNotificationConfig.Builder()
                .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE)
                .build())
        .build();

// Create RangingPreference for the initiator
RangingPreference preference = new RangingPreference.Builder(
        RangingPreference.DEVICE_ROLE_INITIATOR,
        new RawInitiatorRangingConfig.Builder()
                .addRawRangingDevice(rawRangingDevice)
                .build())
        .setSessionConfig(sessionConfig)
        .build();

API UWB Downlink-TDoA

Per l'API UWB DL-TDoA, consulta le nuove funzionalità di Android 17.

App di esempio

Per un esempio end-to-end di come utilizzare il modulo Ranging, consulta la sample app in AOSP. Questa app di esempio copre tutte le tecnologie di misurazione della distanza supportate dal modulo Ranging e include i flussi per entrambi i tipi di sessione supportati.

Interoperabilità UWB con i dispositivi iOS

L'app di esempio Android supporta l'avvio di una sessione di misurazione della distanza UWB con l' app di esempio iOS.

Figura 2. Utilizzo di UWB su Android e iOS.