Android 16 (livello API 36) introduce il modulo Ranging, che fornisce un'interfaccia unificata e standardizzata per il rilevamento preciso 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:
- Banda ultralarga
- Bluetooth Channel Sounding
- Wi-Fi NAN RTT
- Rilevamento della distanza RSSI Bluetooth
- Rilevamento di prossimità Wi-Fi su Android 17 (livello API 37) e versioni successive
Funzionalità e disponibilità di Ranging
La classe RangingManager fornisce alle app informazioni sulle tecnologie di rilevamento della distanza supportate dal dispositivo locale, nonché sulla disponibilità e sulle funzionalità di ciascuna tecnologia. Le app possono registrare un'interfaccia RangingCapabilitiesCallback per ricevere aggiornamenti su eventuali modifiche alla disponibilità o alle funzionalità di qualsiasi tecnologia supportata.
Ruoli dei dispositivi
Un dispositivo che partecipa a una sessione di misurazione della distanza deve essere un iniziatore, un risponditore o un tag Downlink-TDoA (DT-Tag) per le sessioni UWB Downlink-TDoA su Android 17 (livello API 37) e versioni successive. Il dispositivo iniziatore avvia la sessione di misurazione della distanza con uno o più dispositivi risponditori. Un dispositivo responder risponde alle richieste di misurazione della distanza di un solo initiator alla volta. In una sessione UWB Downlink Time Difference of Arrival (DL-TDoA), il dispositivo utilizza il ruolo DEVICE_ROLE_DT_TAG per ricevere segnali da più anchor UWB.
Puoi specificare il ruolo di un determinato dispositivo in una sessione di misurazione della distanza con la classe RangingPreference.
Tipi di sessioni di rilevamento della distanza
Quando si avvia una sessione di rilevamento della distanza tra i dispositivi, spesso è necessario stabilire un trasporto dati fuori banda (OOB) per scambiare i parametri della sessione.
Il modulo Ranging può gestire le negoziazioni OOB per te, ma supporta anche implementazioni OOB personalizzate.
Implementazione OOB predefinita
In questo tipo di sessione (RANGING_SESSION_OOB), il modulo di misurazione della distanza gestisce le negoziazioni OOB per avviare una sessione di misurazione della distanza. Seleziona i parametri adatti in base alle preferenze di rilevamento della distanza fornite dall'app e utilizza le tecnologie appropriate in base a ciò che supportano entrambi i dispositivi. Questo tipo di sessione utilizza una specifica OOB standardizzata. Su Android 16 QPR2 (livello API 36.1)
e versioni successive, gli initiator possono limitare le tecnologie negoziate
chiamando setRangingTechnologyFilter su
OobInitiatorRangingConfig.Builder.
Il modulo Ranging definisce solo il formato dei dati OOB e la sequenza da utilizzare per interagire con un dispositivo peer. Non gestisce il rilevamento dei dispositivi peer o la creazione della connessione.
Implementazione OOB personalizzata
In questo tipo di sessione (RANGING_SESSION_RAW), l'app bypassa il flusso OOB del modulo di rilevamento della distanza e gestisce la propria negoziazione e i propri parametri OOB. Ciò significa che l'app deve determinare quali tecnologie sono supportate dal dispositivo peer, negoziare i parametri di rilevamento della distanza e avviare la sessione di rilevamento della distanza.
Preferenze di rilevamento
Utilizza un oggetto RangingPreference per specificare i parametri selezionati per una sessione di rilevamento della distanza. È incluso quanto segue:
- Ruolo del dispositivo. Indica se il dispositivo è l'iniziatore, il risponditore o un DT-Tag su Android 17 (livello API 37) e versioni successive.
- Configurazione del rilevamento della distanza. Un oggetto
RangingConfigspecifica il tipo di sessione di rilevamento della distanza e altri parametri necessari per avviarla. - Configurazione della sessione. Un oggetto
SessionConfigspecifica i parametri da applicare alla sessione di rilevamento della distanza, come il limite di misurazione, la fusione dei sensori, la configurazione del geofencing e altro ancora. Su Android 17 (livello API 37) e versioni successive, puoi anche configurare la modalità antenna (ANTENNA_MODE_DIRECTIONALoANTENNA_MODE_OMNI) consetAntennaModesuSessionConfig.Builderdopo aver controllato le modalità supportate congetSupportedAntennaModessuUwbRangingCapabilities.
Autorizzazione di rilevamento
Il modulo Ranging utilizza un'autorizzazione unificata (android.permission.RANGING) per le tecnologie di rilevamento peer-to-peer. Questa autorizzazione è nell'elenco NEARBY_DEVICES_PERMISSIONS.
<uses-permission android:name="android.permission.RANGING" />
Restrizioni e limitazioni
Il modulo Ranging potrebbe limitare il rilevamento della distanza per diversi motivi, tra cui:
- Le app di terze parti possono eseguire il rilevamento in background con la banda ultralarga solo sui dispositivi supportati. Il rilevamento della distanza in background con altre tecnologie non è consentito.
- Il ranging non è consentito quando è stato raggiunto il numero massimo di sessioni di ranging simultanee per dispositivo.
- Il rilevamento potrebbe essere limitato a causa di problemi di integrità del sistema, ad esempio batteria, prestazioni o memoria.
Il modulo Ranging presenta anche le seguenti limitazioni note:
- Il modulo Ranging supporta solo l'invio di dati di rilevamento 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 rilevamento della distanza non elaborata e solo per la banda ultralarga.
- Il modulo Ranging non supporta le sessioni a banda ultralarga one-to-many per le implementazioni OOB predefinite. Se passi più handle di dispositivi, il modulo crea una sessione one-to-one per ogni dispositivo peer che supporta la banda ultralarga.
Esegui una sessione di misurazione della distanza
Per condurre una sessione di misurazione della distanza utilizzando il modulo Ranging, segui questi passaggi:
- Verifica che tutti i dispositivi eseguano Android 16 (livello API 36) e versioni successive.
- Richiedi l'autorizzazione
android.permission.RANGINGnel manifest dell'app. - Valutare le funzionalità e la disponibilità delle tecnologie di misurazione della distanza.
- Rilevare un dispositivo peer per le operazioni di rilevamento della distanza.
- Stabilisci una connessione per uno scambio fuori banda utilizzando uno dei tipi di sessione descritti in Tipi di sessione di misurazione della distanza.
- Avviare il rilevamento della distanza e acquisire continuamente i dati di rilevamento.
- Termina la sessione di rilevamento della distanza.
Il seguente esempio di codice mostra questi passaggi sia per il ruolo di iniziatore sia per quello di risponditore.
class RangingApp { // Starts a ranging session on the initiator side. fun startRangingInitiator( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // 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) ?: return null // 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. Ranging data is delivered asynchronously through // callback.onResults; call stopRanging(session) when ranging is no longer needed. session.start(preference) return session } // Starts a ranging session on the responder side. fun startRangingResponder( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // 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) ?: return null // 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. Call stopRanging(session) when finished. session.start(preference) return session } // Stops an active ranging session. fun stopRanging(session: RangingSession) { session.stop() } }
Gestisci i risultati di misurazione della distanza e il movimento dei peer
Quando una sessione è attiva, RangingSession.Callback fornisce misurazioni della distanza e dell'angolo di arrivo negli oggetti RangingData tramite onResults:
- Incertezza della distanza. Su Android 16 QPR2 (livello API 36.1) e versioni successive,
chiama
hasDistanceStandardDeviationegetDistanceStandardDeviationMeterssuRangingDataper ispezionare la deviazione standard delle misurazioni della distanza, se disponibile. - Extra specifici per la tecnologia. Su Android 17 (livello API 37) e versioni successive,
chiama
getRangingDataExtrassuRangingDataper recuperare un oggettoRangingDataExtrascontenente metadati specifici della tecnologia, comeBleSpecificData,UwbSpecificDataoWifiRttSpecificData. - Stato di movimento del peer. Su Android 17 (livello API 37) e versioni successive, esegui l'override di
onMotionReceivedinRangingSession.Callbackper ricevere aggiornamenti diMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEoMOTION_LARGE) quando il movimento di un dispositivo peer cambia.
Interoperabilità UWB con i dispositivi iOS
Il modulo Ranging supporta l'interoperabilità con i dispositivi iOS che utilizzano la banda ultralarga (UWB). Per il rilevamento con un dispositivo iOS, devi utilizzare un'implementazione OOB personalizzata e configurare la sessione di rilevamento con parametri specifici che corrispondono al protocollo Apple Nearby Interaction Accessory. Per un esempio, 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 esegue il ranging con un responder iOS:
// 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()
API UWB Downlink-TDoA
Su Android 17 (livello API 37) e versioni successive, il rilevamento della distanza Downlink Time Difference of Arrival (DL-TDoA) consente a un dispositivo di determinare la propria posizione rispetto a più anchor UWB misurando i tempi di arrivo relativi dei segnali.
Il seguente snippet mostra come utilizzare RangingManager per verificare il supporto di DL-TDoA, configurare DlTdoaRangingParams e RawDtTagRangingConfig per avviare una sessione e ricevere i risultati di DlTdoaMeasurement:
class RangingApp { fun initDlTdoa(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Register for device capabilities. val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback { override fun onRangingCapabilities(capabilities: RangingCapabilities) { // Make sure DL-TDoA is supported before starting the session. if (capabilities.uwbCapabilities?.isDlTdoaSupported == true) { startDlTDoASession(context) } } } rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback) } fun startDlTDoASession(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Create session and configure parameters. val executor = Executors.newSingleThreadExecutor() val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback()) val rangingRoundIndexes = byteArrayOf(0) val config: ByteArray = byteArrayOf() // OOB config data val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes) val rangingDevice = RangingDevice.Builder().build() val rawTagDevice = RawRangingDevice.Builder() .setRangingDevice(rangingDevice) .setDlTdoaRangingParams(params) .build() val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build() val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig) .setSessionConfig(SessionConfig.Builder().build()) .build() // Start the ranging session. rangingSession?.start(preference) } } private class RangingSessionCallback : RangingSession.Callback { override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) { // Process measurement results here. } override fun onOpened() { // ... } override fun onOpenFailed(reason: Int) { // ... } override fun onStarted(peer: RangingDevice, technology: Int) { // ... } override fun onStopped(peer: RangingDevice, technology: Int) { // ... } override fun onResults(peer: RangingDevice, data: RangingData) { // ... } override fun onClosed(reason: Int) { // ... } }
Configurazioni fuori banda (OOB)
Il seguente snippet fornisce un esempio di dati di configurazione OOB DL-TDoA per Wi-Fi e BLE:
// Wi-Fi Configuration (Vendor-Specific IE, FiRa CID 0x5A18FF, Config 0) val wifiConfig = byteArrayOf( 0xDD.toByte(), 0x30, 0x5A, 0x18, 0xFF.toByte(), // Wi-Fi VSE Header 0x5F, 0x1C, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x14, 0x01, 0x0A, // Preamble Code Index (10) 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x08, 0x02, 0x60, 0x09, // Slot Duration (2400 RSTU = 2 ms) 0x1B, 0x01, 0x0A, // Slots per Ranging Round (10) 0x09, 0x04, 0xFA.toByte(), 0x00, 0x00, 0x00, // Ranging Duration (250 ms) 0x52, 0x01, 0x00, // Initiator DT-Anchor Round Index (0) 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) ) // BLE Configuration (ADV_NONCONN_IND Service Data UUID 0xFFF3, Config 0) val bleConfig = byteArrayOf( 0x1E, 0x16, 0xF3.toByte(), 0xFF.toByte(), // BLE Service Data Header 0xF0.toByte(), // Fragment Indication Sub-Element (unfragmented) 0x5F, 0x09, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) )
Se non puoi utilizzare una configurazione OOB perché non è presente o se devi modificare i valori predefiniti che non sono presenti nella configurazione OOB, puoi creare i parametri con DlTdoaRangingParams.Builder anziché chiamare DlTdoaRangingParams.createFromFiraConfigPacket:
val dlTdoaParams = DlTdoaRangingParams.Builder(1) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(9).setPreambleIndex(10).build() ) .setDeviceAddress(deviceAddress) .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04)) .setRangingIntervalMillis(240) .setSlotDuration(UwbRangingParams.DURATION_2_MS) .setSlotsPerRangingRound(20) .setRangingRoundIndexes(byteArrayOf(0x01, 0x05)) .build()
App di esempio
Per un esempio end-to-end di come utilizzare il modulo Ranging, consulta l'app di esempio in AOSP. Questa app di esempio copre tutte le tecnologie di rilevamento 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 per Android supporta l'avvio di una sessione di rilevamento della distanza UWB con l'app di esempio per iOS.