Plage de portée entre les appareils

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Android 16 introduit le module de mesure de la distance, qui fournit une interface unifiée et normalisée pour une mesure précise de la distance entre les appareils. Vous pouvez utiliser cette surface d'API pour mesurer la distance et la position des appareils homologues sans avoir à gérer chaque technologie de mesure de la distance individuellement.

Le module de mesure de la distance est compatible avec les technologies suivantes:

• Bande ultralarge
• Sondage de canaux Bluetooth
• RTT NAN Wi-Fi
• Évaluation de la portée du RSSI Bluetooth

Fonctionnalités et disponibilités de la mesure de la distance

La classe RangingManager fournit aux applications des informations sur les technologies de mesure de la distance prises en charge par l'appareil local, ainsi que sur la disponibilité et les fonctionnalités de chaque technologie. Les applications peuvent s'inscrire à un Callback 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 mesure de la distance doit être un initiateur ou un répondeur. L'appareil initiateur lance la session de mesure de la portée avec un ou plusieurs appareils répondeurs. Un appareil répondeur ne répond qu'à une seule requête de mesure de la distance à la fois. Vous pouvez spécifier le rôle d'un appareil donné dans une session de mesure de la portée avec la classe RangingPreference.

Types de sessions de classement

Lorsque vous démarrez une session de mesure de la distance 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 mesure de la portée peut gérer les négociations hors bande pour vous, mais il est également compatible avec les implémentations hors bande personnalisées.

Implémentation par défaut de l'OOB

Dans ce type de session (RANGING_SESSION_OOB), le module de mesure de la portée gère les négociations hors bande pour démarrer une session de mesure de la portée. Il sélectionne les paramètres appropriés en fonction des préférences de mesure de la distance fournies par l'application et utilise les technologies appropriées en fonction de ce que les deux appareils acceptent. Ce type de session utilise un OOB specification standardisé.

Le module de mesure de la portée ne définit que le format et la séquence de données OOB à utiliser pour interagir avec un appareil homologue. Il ne gère pas la découverte d'appareils pairs ni l'établissement de connexions.

Implémentation personnalisée hors bande

Dans ce type de session (RANGING_SESSION_RAW), l'application contourne le flux OOB du module de mesure de la portée et gère sa propre négociation et ses propres paramètres OOB. Cela signifie que l'application doit déterminer les technologies compatibles avec l'appareil homologue, négocier les paramètres de mesure de la distance et commencer la session de mesure de la distance.

Préférences de portée

Utilisez un objet RangingPreference pour spécifier les paramètres souhaités pour une session de mesure de la distance. et vous devriez pouvoir :

• Rôle de l'appareil Indique si l'appareil sera l'initiateur ou le répondeur.
• Configuration de la mesure de la distance. Un objet RangingConfig spécifie le type de session de mesure de la portée et d'autres paramètres nécessaires pour démarrer une session de mesure de la portée.
• Configuration de la session Un objet SessionConfig spécifie les paramètres à appliquer à la session de mesure, tels que la limite de mesure, la fusion de capteurs, la configuration de la zone géographique et plus encore.

Autorisation de mesure de la portée

Le module de mesure de la distance nécessite une nouvelle autorisation unifiée (android.permission.RANGING) pour accéder à toutes les technologies de mesure de la distance actuelles et futures. Cette autorisation figure dans la liste NEARBY_DEVICES_PERMISSIONS.

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

Restrictions et limites

Le module de mesure de la distance peut limiter la mesure de la distance pour plusieurs raisons, y compris les suivantes:

• Les applications tierces ne sont autorisées à effectuer des mesures en arrière-plan qu'avec la bande ultralarge et uniquement sur les appareils compatibles. La mesure de la distance en arrière-plan avec d'autres technologies n'est pas autorisée.
• La mesure de la distance n'est pas autorisée lorsque le nombre maximal de sessions de mesure de la distance simultanées par appareil a été atteint.
• La mesure de la portée 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 de mesure de la portée présente également les limites connues suivantes:

• Le module de mesure de la distance n'est compatible qu'avec la diffusion de données de mesure de la distance aux appareils homologues pour l'ultra-large bande. Pour les autres technologies, le module de mesure de la distance n'envoie que des données de mesure de la distance à l'appareil initiateur.
• Le module de mesure de la distance n'accepte que l'ajout dynamique d'appareils en mode de mesure de la distance brute, et uniquement pour la bande ultralarge.
• Le module de mesure de la portée n'est pas compatible avec les sessions UWB de type "un à plusieurs" pour les implémentations OOB par défaut. Si vous transmettez plusieurs poignées d'appareil, le module crée une session individuelle pour chaque appareil associé compatible avec la bande ultralarge.

Effectuer une session de mesure de la distance

Pour effectuer une session de mesure de la distance à l'aide du module de mesure de la distance, procédez comme suit:

1. Vérifiez que tous les appareils fonctionnent sous Android 16 ou version ultérieure.
2. Demandez l'autorisation android.permission.RANGING dans le fichier manifeste de l'application.
3. Évaluez les capacités et la disponibilité des technologies de mesure de la distance.
4. Détecter un appareil homologue pour les opérations de mesure de la distance
5. Établissez une connexion pour un échange hors bande à l'aide de l'un des types de session décrits dans la section Types de session de balayage.
6. Lancer la mesure de la distance et acquérir en continu des données de mesure de la distance.
7. Arrêtez la session de mesure de la portée.

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: 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()
    }
}

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();
    }
}

Application exemple

Pour obtenir un exemple de bout en bout sur l'utilisation du module de mesure de la distance, consultez l'application exemple dans AOSP. Cet exemple d'application couvre toutes les technologies de mesure de la distance prises en charge par le module de mesure de la distance et inclut des flux pour les deux types de sessions compatibles.