Interface HAL UWB

La pile à bande ultralarge (UWB) de l'AOSP utilise l'interface UCI définie par FiRa comme surface HAL. L'interface HAL utilise un canal opaque (IUwbChip::sendUciMessage() et IUwbClientCallback::onUciMessage()) pour envoyer et recevoir des commandes, des réponses et des notifications de l'interface de commande UWB (UCI, UWB Command Interface). Tous les fournisseurs Android UWB doivent être compatibles avec tous les messages définis dans la spécification FiRa. Le framework UWB est rétrocompatible et fonctionne avec n'importe quelle version UCI implémentée par le fournisseur UWB sur l'appareil. Étant donné que le framework AOSP UWB est un module, il peut également ajouter sélectivement la prise en charge des demandes de modification (CR) approuvées à partir des spécifications UCI provisoires destinées aux principales versions des normes FiRa. Toute demande de modification de contenu provisoire implémentée est susceptible d'être modifiée.

Définition de l'interface

L'interface UWB HAL est définie à l'aide d'AIDL stable. L'interface principale utilise le package android.hardware.uwb.

Voici les deux interfaces principales du package android.hardware.uwb.

IUwbChip.aidl

package android.hardware.uwb;

interface IUwbChip {

 String getName();

 void open(in android.hardware.uwb.IUwbClientCallback clientCallback);

 void close();

 void coreInit();

 void sessionInit(int sessionId);

 int getSupportedAndroidUciVersion();

 int sendUciMessage(in byte[] data);

}

IUwbClientCallback.aidl

package android.hardware.uwb;

interface IUwbClientCallback {

 oneway void onUciMessage(in byte[] data);

 oneway void onHalEvent(in android.hardware.uwb.UwbEvent event, in android.hardware.uwb.UwbStatus status);

}

Flux d'appel HAL à partir du framework UWB

Les images suivantes illustrent le flux d'appels du framework UWB pour l'initialisation et la désinitialisation de la pile UWB, ainsi que pour les processus de démarrage et d'arrêt de la session UWB.

Figure 1 : Flux d'appel d'initialisation de la pile UWB (activation de l'UWB)

Figure 2. Flux d'appel de désinitialisation de la pile UWB (désactivation de l'UWB)

Figure 3. Flux de démarrage/d'arrêt de la session UWB

Configuration du code pays UWB

Comme le montre la figure 1, le framework UWB configure le code pays UWB lors de l'initialisation de la pile UWB à l'aide de la commande UCI de l'espace fournisseur ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). Le framework UWB tente de déterminer le code pays UWB à l'aide des sources suivantes (listées par ordre de priorité). Le framework UWB s'arrête à la première source où le code pays est déterminé.

1. Code pays forcé : code pays forcé par une commande adb shell (test local ou automatisé).
2. Code pays de la téléphonie : code pays récupéré via le réseau mobile. Si plusieurs cartes SIM renvoient des codes différents, le code pays choisi est non déterministe.
3. Code pays du Wi-Fi : code pays récupéré via le Wi-Fi (80211.ad).
4. Code pays de téléphonie connu le plus récent : code pays connu le plus récent récupéré via le réseau mobile. Si plusieurs cartes SIM renvoient des codes différents, le code pays choisi est non déterministe.
5. Code pays du lieu : code pays récupéré à partir du fournisseur de localisation LocationManager.
6. Code pays par défaut de l'OEM : code pays défini par le fabricant de l'appareil.

Si le framework UWB ne parvient pas à déterminer un code pays UWB, il appelle la commande UCI ANDROID_SET_COUNTRY_CODE avec une valeur de DEFAULT_COUNTRY_CODE ("00") et informe les applications UWB que l'état de la pile UWB est DISABLED. Plus tard, lorsque le framework UWB est en mesure de déterminer un code pays valide, il configure le nouveau code pays à l'aide de la commande ANDROID_SET_COUNTRY_CODE et informe les applications UWB que la pile UWB est READY.

Si l'UWB ne peut pas être utilisé en raison de réglementations locales dans un pays, le contrôleur UWB renvoie le code d'état STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Le framework UWB avertit ensuite les applications UWB que l'état de la pile UWB est DISABLED.

Lorsqu'un utilisateur se rend dans un autre pays, le framework UWB configure un nouveau code pays à l'aide de la commande UCI ANDROID_SET_COUNTRY_CODE. En fonction du code d'état renvoyé par le contrôleur UWB (en fonction des réglementations UWB dans le nouveau pays), l'état de la pile UWB peut changer.

Format de commande défini par la spécification FIRA UCI

Pour connaître le format des paquets de contrôle UCI, consultez la section 4.4.2 de la spécification UCI.

Gestion des versions de l'interface

La spécification UCI permet aux fournisseurs UWB d'exposer la version de la pile UCI implémentée par l'appareil à l'aide des commandes UCI_GET_DEVICE_INFO_RSP et UCI_GET_CAPS_INFO_RSP. Le framework utilise ces commandes pour récupérer la version UCI de l'appareil et modifier son comportement en conséquence.

Liste des CR provisoires compatibles avec le module UWB

Les CR préliminaires suivants pour FiRa 2.0 sont compatibles avec la version #330810000 du module UWB :

• CR 287
• Prise en charge de l'API SUS et de la spécification UCI pour les exigences de l'interface de clé numérique CCC

Interface UCI Android (partie fournisseur FiRa)

La spécification UCI définit un ensemble d'identifiants de groupe (GID) et d'identifiants d'opcode (OID) pour tous les messages définis par la spécification. La spécification réserve également un ensemble d'identifiants de groupe (GID) exclusivement destinés à l'utilisation par les fournisseurs. La pile UWB AOSP utilise certains de ces GID et OID de fournisseur pour les commandes spécifiques à Android qui ne sont pas définies dans la spécification. Pour en savoir plus, consultez la section 8.4 de la spécification UCI.

Ces messages du fournisseur utilisés par Android sont définis dans le package HAL android.hardware.uwb.fira_android.

Gestion des versions de l'interface du fournisseur

Les fournisseurs UWB doivent exposer la version du package HAL android.hardware.uwb.fira_android compatible avec l'appareil via IUwbChip.getSupportedAndroidUciVersion(). Le framework utilise ces informations de version pour gérer la rétrocompatibilité.

Liste des GID et OID Android

Le tableau suivant liste les GID et les OID pour Android. Les GID 0xE et 0xF sont réservés aux OEM Android.

Extensions de fournisseur aux messages définis dans les spécifications UCI

Cette section décrit en détail les extensions de fournisseur aux messages définis par la spécification UCI.

SESSION_SET_APP_CONFIG_[CMD|RSP] et SESSION_GET_APP_CONFIG_[CMD|RSP]

Voici les valeurs de type-longueur (TLV) définies par la pile AOSP dans la partie réservée au fournisseur des TLV dans APP_CONFIG :

• GID : 0001b (groupe de configuration de session UWB)
• OID : 000011b (SESSION_SET_APP_CONFIG_CMD)
• OID : 000100b (SESSION_GET_APP_CONFIG_CMD)

Le tableau suivant liste les paramètres des messages de configuration de session UWB.

CORE_GET_CAPS_INFO_RSP

Voici les TLV définis par la pile AOSP dans la partie réservée au fournisseur des TLV dans CAPS_INFO :

• GID : 0000b (groupe de base UWB)
• OID : 000011b (CORE_GET_CAPS_INFO_RSP)

Le tableau suivant répertorie les paramètres des messages de capacité UWB.

Codes d'état

Vous trouverez ci-dessous les codes d'état dans l'espace fournisseur. Elles sont renvoyées dans les réponses UCI (telles que SESSION_START_RSP) par le sous-système UWB (UWBS).

Code de motif de changement d'état dans SESSION_STATUS_NTF

Vous trouverez ci-dessous les codes de motif de changement d'état définis dans l'espace fournisseur pour le champ d'état renvoyé par un UWBS dans SESSION_STATUS_NTF. Cette notification est envoyée par l'UWBS lorsque l'état d'une session de mesure de distance change (par exemple, de ACTIVE à IDLE).