Plage de portée entre les appareils

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 :

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.

Figure 1. Flux OOB pour les types de sessions.

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 RangingConfig spé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 SessionConfig spé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_DIRECTIONAL ou ANTENNA_MODE_OMNI) avec setAntennaMode sur SessionConfig.Builder après avoir vérifié les modes compatibles avec getSupportedAntennaModes sur UwbRangingCapabilities.

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 :

  1. Vérifiez que tous les appareils exécutent Android 16 (niveau d'API 36) ou version ultérieure.
  2. Demandez l'autorisation android.permission.RANGING dans le fichier manifeste d'application.
  3. Évaluez les capacités et la disponibilité des technologies de mesure de distance.
  4. Découvrez un appareil pair pour les opérations de télémétrie.
  5. É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.
  6. Lancez la télémétrie et acquérez des données de télémétrie en continu.
  7. 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 hasDistanceStandardDeviation et getDistanceStandardDeviationMeters sur RangingData pour 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 getRangingDataExtras sur RangingData pour récupérer un objet RangingDataExtras contenant des métadonnées spécifiques à la technologie, telles que BleSpecificData, UwbSpecificData ou WifiRttSpecificData.
  • État de mouvement de l'application similaire. Sur Android 17 (niveau d'API 37) ou version ultérieure, remplacez onMotionReceived dans RangingSession.Callback pour recevoir les mises à jour MotionState (MOTION_NOT_DETECTED, MOTION_SLIGHT, MOTION_MODERATE ou MOTION_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.

Figure 2 : Utilisation de l'UWB sur Android et iOS.