Communication à bande ultralarge (UWB)

La communication en bande ultralarge est une technologie radio axée sur la mesure précise de la distance (mesure de la position avec une précision de 10 cm) entre les appareils. Cette technologie radio peut utiliser une densité d'énergie faible pour les mesures à courte portée et effectuer une signalisation à large bande passante sur une grande partie du spectre radio. La bande passante de la technologie UWB est supérieure à 500 MHz (ou dépasse 20% de la bande passante fractionnaire).

Contrôleur/Initiateur par rapport à l'appareil contrôlé/Répondeur

La communication UWB s'effectue entre deux appareils, l'un étant un contrôleur et l'autre un dispositif contrôlé. Le contrôleur détermine le canal complexe (UwbComplexChannel) que les deux appareils partageront et est l'initiateur, tandis que le contrôlé est le répondeur.

Un contrôleur peut gérer plusieurs contrôleurs, mais un contrôleur ne peut s'abonner qu'à un seul contrôleur. Les configurations de contrôleur/initiateur et de contrôleur/répondeur sont acceptées.

Paramètres de mesure de la distance

Le contrôleur et le contrôlé doivent s'identifier et communiquer les paramètres de mesure de la portée pour commencer la mesure de la portée. Cet échange est laissé aux applications à implémenter à l'aide d'un mécanisme hors bande (OOB) sécurisé de leur choix, tel que le Bluetooth à basse consommation (BLE).

Les paramètres de portée incluent l'adresse locale, le canal complexe et la clé de session, entre autres. Notez que ces paramètres peuvent changer après la fin de la session de mesure de la portée et doivent être communiqués à nouveau pour redémarrer la mesure de la portée.

Évaluation de la distance en arrière-plan

Une application exécutée en arrière-plan peut démarrer une session de mesure de la distance UWB si l'appareil le prend en charge. Pour vérifier les fonctionnalités de votre appareil, consultez RangingCapabilities.

L'application ne reçoit pas de rapports de mesure de la distance lorsqu'elle s'exécute en arrière-plan. Elle reçoit des rapports de mesure de la distance lorsqu'elle passe au premier plan.

Configurations STS

L'application ou le service provisionne une clé de session pour chaque session à l'aide d'une séquence de code temporel chiffré (STS, Scrambled Timestamp Sequence). Le STS provisionné est plus sécurisé qu'une configuration STS statique. Le STS provisionné est compatible avec tous les appareils compatibles avec la technologie UWB exécutant Android 14 ou version ultérieure.

Pour les STS provisionnés:

1. Utilisez uwbConfigType dans RangingParameters, qui est compatible avec le STS provisionné.

2. Indiquez la clé de 16 octets dans le champ sessionKeyInfo.

Pour les STS statiques:

1. Utilisez le uwbConfigType dans RangingParameters compatible avec le STS statique.

2. Indiquez la clé de 8 octets dans le champ sessionKeyInfo.

Étapes

Pour utiliser l'API UWB, procédez comme suit:

1. Assurez-vous que les appareils Android sont équipés d'Android 12 ou version ultérieure et qu'ils prennent en charge le UWB à l'aide de PackageManager#hasSystemFeature("android.hardware.uwb").
2. Si vous effectuez une mesure de la portée avec des appareils IoT, assurez-vous qu'ils sont conformes à la norme FiRa MAC 1.3.
3. Découvrez les appareils pairs compatibles avec la technologie UWB à l'aide d'un mécanisme hors bande de votre choix, tel que BluetoothLeScanner.
4. Échangez les paramètres de mesure de la portée à l'aide d'un mécanisme OOB sécurisé de votre choix, tel que BluetoothGatt.
5. Si l'utilisateur souhaite arrêter la session, annulez la portée de la session.

Restrictions d'utilisation

Les restrictions suivantes s'appliquent à l'utilisation de l'API UWB:

1. L'application qui lance de nouvelles sessions de mesure de la portée UWB doit être une application ou un service de premier plan, sauf si la mesure de la portée en arrière-plan est prise en charge, comme illustré précédemment.
2. Lorsque l'application passe en arrière-plan (lorsque la session est en cours), il est possible qu'elle ne reçoive plus de rapports de mesure de la distance. La session UWB sera toutefois maintenue dans les couches inférieures. Lorsque l'application revient au premier plan, les rapports de mesure de la distance reprennent.

Exemples de code

Application exemple

Pour obtenir un exemple de bout en bout sur l'utilisation de la bibliothèque Jetpack UWB, consultez notre application exemple sur GitHub. Cet exemple d'application couvre la validation de la compatibilité UWB sur un appareil Android, l'activation du processus de découverte à l'aide d'un mécanisme hors bande et la configuration de la portée UWB entre deux appareils compatibles avec la BUL. L'exemple couvre également les cas d'utilisation de contrôle des appareils et de partage de contenus multimédias.

Détermination de la portée UWB

Cet exemple de code lance et termine la mesure de la portée UWB pour un appareil contrôlé:

// The coroutineScope responsible for handling uwb ranging.
// This will be initialized when startRanging is called.
var job: Job?

// A code snippet that initiates uwb ranging for a Controlee.
suspend fun startRanging() {

    // Get the ranging parameter of a partnering Controller using an OOB mechanism of choice.
    val partnerAddress : Pair<UwbAddress, UwbComplexChannel> = listenForPartnersAddress()

    // Create the ranging parameters.
    val partnerParameters = RangingParameters(
        uwbConfigType = UwbRangingParameters.UWB_CONFIG_ID_1,
        // SessionKeyInfo is used to encrypt the ranging session.
        sessionKeyInfo = null,
        complexChannel = partnerAddress.second,
        peerDevices = listOf(UwbDevice.createForAddress(partnerAddress.first)),
        updateRateType = UwbRangingParameters.RANGING_UPDATE_RATE_AUTOMATIC
    )

    // Initiate a session that will be valid for a single ranging session.
    val clientSession = uwbManager.clientSessionScope()

    // Share the localAddress of the current session to the partner device.
    broadcastMyParameters(clientSession.localAddress)

    val sessionFlow = clientSession.prepareSession(partnerParameters)

    // Start a coroutine scope that initiates ranging.
    CoroutineScope(Dispatchers.Main.immediate).launch {
        sessionFlow.collect {
            when(it) {
                is RangingResultPosition -> doSomethingWithPosition(it.position)
                is RangingResultPeerDisconnected -> peerDisconnected(it)
            }
        }
    }
}

// A code snippet that cancels uwb ranging.
fun cancelRanging() {

    // Canceling the CoroutineScope will stop the ranging.
    job?.let {
        it.cancel()
    }
}

Compatibilité avec RxJava3

La prise en charge de Rxjava3 est désormais disponible pour faciliter l'interopérabilité avec les clients Java. Cette bibliothèque permet d'obtenir des résultats de mesure de la distance en tant que flux Observable ou Flowable, et de récupérer le UwbClientSessionScope en tant qu'objet Single.

private final UwbManager uwbManager;

// Retrieve uwbManager.clientSessionScope as a Single object
Single<UwbClientSessionScope> clientSessionScopeSingle =
                UwbManagerRx.clientSessionScopeSingle(uwbManager);
UwbClientSessionScope uwbClientSessionScope = clientSessionScopeSingle.blockingGet();

// Retrieve uwbClientSessionScope.prepareSession Flow as an Observable object
Observable<RangingResult> rangingResultObservable =
                UwbClientSessionScopeRx.rangingResultsObservable(clientSessionScope,
                        rangingParameters);

// Consume ranging results from Observable
rangingResultObservable.subscribe(
   rangingResult -> doSomethingWithRangingResult(result), // onNext
   (error) -> doSomethingWithError(error), // onError
   () -> doSomethingOnResultEventsCompleted(), //onCompleted
);
// Unsubscribe
rangingResultObservable.unsubscribe();
   

// Retrieve uwbClientSessionScope.prepareSession Flow as a Flowable object
Flowable<RangingResult> rangingResultFlowable =
                UwbClientSessionScopeRx.rangingResultsFlowable(clientSessionScope,
                        rangingParameters);

// Consume ranging results from Flowable using Disposable
Disposable disposable = rangingResultFlowable
   .delay(1, TimeUnit.SECONDS)
   .subscribeWith(new DisposableSubscriber<RangingResult> () {
      @Override public void onStart() {
          request(1);
      }
      
      @Override public void onNext(RangingResult rangingResult) {
             doSomethingWithRangingResult(rangingResult);
             request(1);
      }


      @Override public void onError(Throwable t) {
             t.printStackTrace();
      }


         @Override public void onComplete() {
            doSomethingOnEventsCompleted();
         }
   });

// Stop subscription
disposable.dispose();

Compatibilité avec l'écosystème

Voici les appareils partenaires et les SDK tiers compatibles.

Appareils mobiles compatibles avec la bande ultralarge

Depuis janvier 2025, les appareils suivants sont compatibles avec la bibliothèque Android UWB Jetpack:

Remarque: La mesure de la distance UWB en arrière-plan est compatible avec tous les appareils, à l'exception des suivants:

• Pixel 6 Pro et Pixel 7 Pro
• Téléphones Samsung équipés d'Android 13 ou version antérieure
• Téléphones Samsung chinois équipés d'Android 14 ou version antérieure

SDK tiers

Depuis avril 2023, ces solutions partenaires sont compatibles avec la bibliothèque Jetpack actuelle.

• Kit de développement UWB Estimote
• Mobile Knowledge MK UWB Kit Mobile Edition 2.0.

Problème connu: ordre des octets inversé pour les champs d'adresse MAC et d'ID de fournisseur STS statique

Sur Android 13 ou version antérieure, la pile UWB Android inverse de manière incorrecte l'ordre des octets pour les champs suivants:

• Adresse MAC de l'appareil
• Adresse MAC de destination
• ID de fournisseur STS statique

L'ordre des octets est inversé, car la pile Android traite ces champs comme des valeurs, et non comme des tableaux. Nous collaborons avec FiRa pour mettre à jour la spécification UCI (CR-1112) afin d'indiquer explicitement que ces champs doivent être traités comme des tableaux.

Ce problème sera résolu via la mise à jour de GMS Core dans la version 2320XXXX. Pour être conformes aux appareils Android à partir de ce moment, les fournisseurs IoT doivent modifier votre implémentation afin d'éviter d'inverser l'ordre des octets de ces champs.