Android 16 (niveau d'API 36) introduit le module de mesure de distance, qui fournit une interface unifiée et standardisée pour mesurer précisément la distance entre les appareils. Vous pouvez utiliser cette surface d'API pour mesurer la distance et la position des appareils pairs sans avoir à gérer chaque technologie de télémétrie individuellement.
Le module de télémétrie est compatible avec les technologies suivantes :
- Bande ultralarge
- Sondage de canal Bluetooth
- Wi-Fi NAN RTT
- Mesure de la distance RSSI Bluetooth
- Détection de proximité Wi-Fi sur Android 17 (niveau d'API 37) ou version ultérieure
Capacités de mesure de la distance et disponibilité
La classe RangingManager fournit aux applications des informations sur les technologies de télémétrie compatibles avec l'appareil local, ainsi que sur la disponibilité et les fonctionnalités de chaque technologie. Les applications peuvent enregistrer une interface RangingCapabilitiesCallback pour recevoir des informations sur les modifications apportées à la disponibilité ou aux fonctionnalités de toutes les technologies compatibles.
Rôles des appareils
Un appareil participant à une session de télémétrie doit être un initiateur, un répondeur ou un tag Downlink-TDoA (DT-Tag) pour les sessions UWB Downlink-TDoA sur Android 17 (niveau d'API 37) ou version ultérieure. L'appareil initiateur démarre la session de télémétrie avec un ou plusieurs appareils répondeurs. Un appareil répondeur répond aux requêtes de télémétrie d'un seul initiateur à la fois. Dans une session UWB DL-TDoA (Downlink Time Difference of Arrival), l'appareil utilise le rôle DEVICE_ROLE_DT_TAG pour recevoir les signaux de plusieurs ancres UWB.
Vous pouvez spécifier le rôle d'un appareil donné dans une session de télémétrie à l'aide de la classe RangingPreference.
Types de sessions de télémétrie
Lorsque vous démarrez une session de télémétrie entre des appareils, il est souvent nécessaire d'établir un transport de données hors bande (OOB) pour échanger les paramètres de la session.
Le module de télémétrie peut gérer les négociations OOB pour vous, mais il est également compatible avec les implémentations OOB personnalisées.
Implémentation OOB par défaut
Dans ce type de session (RANGING_SESSION_OOB), le module de télémétrie gère les négociations OOB pour démarrer une session de télémétrie. Il sélectionne les paramètres appropriés en fonction des préférences de télémétrie fournies par l'application et utilise les technologies appropriées en fonction de ce que les deux appareils prennent en charge. Ce type de session utilise une spécification OOB standardisée. Sur Android 16 QPR2 (niveau d'API 36.1) et versions ultérieures, les initiateurs peuvent limiter les technologies négociées en appelant setRangingTechnologyFilter sur OobInitiatorRangingConfig.Builder.
Le module de télémétrie ne définit que le format de données et la séquence OOB à utiliser pour interagir avec un appareil pair. Il ne gère pas la découverte d'appareils pairs ni l'établissement de la connexion.
Implémentation OOB personnalisée
Dans ce type de session (RANGING_SESSION_RAW), l'application contourne le flux OOB du module de télémétrie et gère ses propres négociation et paramètres OOB. Cela signifie que l'application doit déterminer les technologies compatibles avec l'appareil pair, négocier les paramètres de télémétrie et lancer la session de télémétrie.
Préférences de mesure de distance
Utilisez un objet RangingPreference pour spécifier les paramètres sélectionnés pour une session de télémétrie. parmi lesquels :
- Rôle de l'appareil. Indique si l'appareil est l'initiateur, le répondeur ou un tag DT sur Android 17 (niveau d'API 37) ou version ultérieure.
- Configuration de la télémétrie. Un objet
RangingConfigspécifie le type de session de télémétrie et d'autres paramètres nécessaires pour démarrer une session de télémétrie. - Configuration de la session Un objet
SessionConfigspécifie les paramètres à appliquer à la session de télémétrie, tels que la limite de mesure, la fusion de capteurs, la configuration de la zone de géorepérage, etc. Sur Android 17 (niveau d'API 37) ou version ultérieure, vous pouvez également configurer le mode d'antenne (ANTENNA_MODE_DIRECTIONALouANTENNA_MODE_OMNI) avecsetAntennaModesurSessionConfig.Builderaprès avoir vérifié les modes compatibles avecgetSupportedAntennaModessurUwbRangingCapabilities.
Autorisation de télémétrie
Le module de télémétrie utilise une autorisation unifiée (android.permission.RANGING) pour les technologies de télémétrie pair à pair. Cette autorisation figure dans la liste NEARBY_DEVICES_PERMISSIONS.
<uses-permission android:name="android.permission.RANGING" />
Restrictions et limitations
Le module de télémétrie peut restreindre la télémétrie pour plusieurs raisons, y compris les suivantes :
- Les applications tierces ne sont autorisées à effectuer des mesures de distance en arrière-plan qu'avec l'ultra-large bande et uniquement sur les appareils compatibles. La télémétrie en arrière-plan avec d'autres technologies n'est pas autorisée.
- La télémétrie n'est pas autorisée lorsque le nombre maximal de sessions de télémétrie simultanées par appareil a été atteint.
- La télémétrie peut être limitée en raison de problèmes d'état du système, tels que la batterie, les performances ou la mémoire.
Le module Ranging présente également les limites connues suivantes :
- Le module de télémétrie n'est compatible qu'avec la transmission de données de télémétrie aux appareils pairs pour la bande ultralarge. Pour les autres technologies, le module de télémétrie ne fournit des données de télémétrie qu'à l'appareil initiateur.
- Le module de télémétrie n'est compatible qu'avec l'ajout dynamique d'appareils en mode de télémétrie brute, et uniquement pour la bande ultralarge.
- Le module de télémétrie n'est pas compatible avec les sessions à bande ultralarge un à plusieurs pour les implémentations OOB par défaut. Si vous transmettez plusieurs identifiants d'appareil, le module crée une session individuelle pour chaque appareil pair compatible avec la bande ultralarge.
Effectuer une session de télémétrie
Pour effectuer une session de télémétrie à l'aide du module de télémétrie, procédez comme suit :
- Vérifiez que tous les appareils exécutent Android 16 (niveau d'API 36) ou version ultérieure.
- Demandez l'autorisation
android.permission.RANGINGdans le fichier manifeste d'application. - Évaluez les capacités et la disponibilité des technologies de mesure de distance.
- Découvrez un appareil pair pour les opérations de télémétrie.
- Établissez une connexion pour un échange hors bande, en utilisant l'un des types de session décrits dans Types de sessions de télémétrie.
- Lancez la télémétrie et acquérez des données de télémétrie en continu.
- Mettre fin à la session de télémétrie.
L'exemple de code suivant illustre ces étapes pour le rôle d'initiateur et le rôle de répondeur.
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() } }
Gérer les résultats de télémétrie et le mouvement des pairs
Lorsqu'une session est active, RangingSession.Callback fournit des mesures de distance et d'angle d'arrivée dans des objets RangingData via onResults :
- Incertitude de la distance. Sur Android 16 QPR2 (niveau d'API 36.1) ou version ultérieure, appelez
hasDistanceStandardDeviationetgetDistanceStandardDeviationMeterssurRangingDatapour inspecter l'écart type des mesures de distance lorsqu'il est disponible. - Avantages spécifiques à la technologie Sur Android 17 (niveau d'API 37) ou version ultérieure, appelez
getRangingDataExtrassurRangingDatapour récupérer un objetRangingDataExtrascontenant des métadonnées spécifiques à la technologie, telles queBleSpecificData,UwbSpecificDataouWifiRttSpecificData. - État de mouvement de l'application similaire. Sur Android 17 (niveau d'API 37) ou version ultérieure, remplacez
onMotionReceiveddansRangingSession.Callbackpour recevoir les mises à jourMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEouMOTION_LARGE) lorsque le mouvement d'un appareil pair change.
Interopérabilité UWB avec les appareils iOS
Le module de télémétrie prend en charge l'interopérabilité avec les appareils iOS utilisant la bande ultralarge (UWB). Pour effectuer une mesure de distance avec un appareil iOS, vous devez utiliser une implémentation OOB personnalisée et configurer la session de mesure de distance avec des paramètres spécifiques correspondant au protocole d'accessoire d'interaction à proximité d'Apple. Pour obtenir un exemple, consultez l'application exemple.
Lorsque vous créez le RangingPreference, utilisez RawRangingDevice et UwbRangingParams pour spécifier la configuration. Les paramètres suivants sont essentiels pour l'interopérabilité iOS :
- ID de configuration. Utilisez
UwbRangingParams.CONFIG_UNICAST_DS_TWR. - Informations sur la clé de session : fournissez un tableau d'octets contenant l'ID du fournisseur et le vecteur d'initialisation STS statique.
- Canal complexe. Définissez le numéro de canal et l'index du préambule pour qu'ils correspondent à la configuration de l'appareil iOS.
L'extrait de code suivant montre comment créer un RangingPreference pour un appareil initiateur effectuant une mesure de distance avec un répondeur 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
Sur Android 17 (niveau d'API 37) ou version ultérieure, la mesure de la différence de temps d'arrivée en liaison descendante (DL-TDoA) permet à un appareil de déterminer sa position par rapport à plusieurs ancres UWB en mesurant les temps d'arrivée relatifs des signaux.
L'extrait de code suivant montre comment utiliser RangingManager pour vérifier la compatibilité avec DL-TDoA, configurer DlTdoaRangingParams et RawDtTagRangingConfig pour démarrer une session, et recevoir les résultats 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) { // ... } }
Configurations hors bande (OOB)
L'extrait de code suivant fournit un exemple de données de configuration OOB DL-TDoA pour le Wi-Fi et le 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) )
Si vous ne pouvez pas utiliser une configuration OOB parce qu'elle est manquante, ou si vous devez modifier des valeurs par défaut qui ne figurent pas dans la configuration OOB, vous pouvez créer des paramètres avec DlTdoaRangingParams.Builder au lieu d'appeler 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()
Application exemple
Pour obtenir un exemple de bout en bout d'utilisation du module de télémétrie, consultez l'application exemple dans l'AOSP. Cette application exemple couvre toutes les technologies de télémétrie compatibles avec le module de télémétrie et inclut des flux pour les deux types de sessions compatibles.
Interopérabilité UWB avec les appareils iOS
L'application exemple Android permet de démarrer une session de télémétrie UWB avec l'application exemple iOS.