La pile UWB (bande ultralarge) 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).
Tous les fournisseurs Android UWB doivent prendre en charge tous les messages définis dans la spécification FiRa. Le framework UWB est rétrocompatible et fonctionne avec toute version UWB implémentée par le fournisseur de la UWB sur l'appareil. Étant donné que le framework UWB AOSP est un module, il peut également ajouter de manière sélective la prise en charge des demandes de modification (CR) approuvées à partir de spécifications provisoires de l'UCI ciblées pour les principales versions des normes FiRa. Toute version provisoire de CR implémentée est susceptible d'être modifiée.
Définition de l'interface
L'interface HAL du module UWB est définie à l'aide d'un AIDL stable.
L'interface principale utilise le package android.hardware.uwb.
Voici les deux principales interfaces 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 de la pile UWB, la désinitialisation de la pile UWB, ainsi que 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 la balise UWB)
Figure 2. Flux d'appels de désinitialisation de la pile UWB (désactivation de l'UWB)
Figure 3. Démarrage/Arrêt de la session UWB
Configuration du code pays UWB
Comme illustré dans 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é.
- Remplacement du code pays: code pays forcé via une commande adb shell (tests locaux ou automatisés).
- Code pays de la téléphonie: code pays récupéré via le réseau mobile. Si plusieurs SIM renvoient des codes différents, le code pays choisi n'est pas déterministe.
- Code pays Wi-Fi: code pays récupéré via le Wi-Fi (80211.ad).
- Dernier code pays de téléphonie connu: dernier 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.
- Code pays du lieu: code pays récupéré auprès du fournisseur de position fusionnée
LocationManager. - 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 peut 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 la technologie UWB ne peut pas être utilisée en raison de la réglementation locale d'un pays, le contrôleur UWB renvoie le code d'état STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Le framework UWB informe 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 (conformément aux réglementations UWB dans le nouveau pays), cela peut entraîner une modification de l'état de la pile UWB.
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 de prévisualisation compatibles avec le module UWB
Les brouillons de RS suivants pour FiRa 2.0 sont compatibles avec la version 330810000 du module UWB:
- CR 287
- Compatibilité avec les spécifications de l'API SUS et de l'UCI pour les exigences concernant l'interface de clé numérique CCC
Interface Android UCI (partie fournisseur FiRa)
La spécification UCI définit un ensemble d'identifiants de groupe (GID) et d'identifiants OPcode (OID) pour tous les messages définis par la spécification. La spécification réserve également un ensemble de GID réservés exclusivement à l'utilisation des fournisseurs. La pile UWB AOSP utilise certains de ces GID et OID de fournisseurs 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 sur l'appareil via IUwbChip.getSupportedAndroidUciVersion(). Le framework utilise ces informations de gestion des versions pour gérer la rétrocompatibilité.
Liste des GID et OID Android
Le tableau suivant répertorie les GID et les OID pour Android. Les GID 0xE et 0xF sont réservés aux OEM Android.
| GID | OID | Définition |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Utilisé par la commande et la réponse pour obtenir des statistiques sur la puissance UWB.
Accepté uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY est défini sur 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Utilisé pour définir le code pays réglementaire actuel (déterminé à l'aide d'une carte SIM ou d'un réseau Wi-Fi, ou codé en dur par l'OEM). Le code pays est envoyé sous forme de valeur de deux octets correspondant au code pays ISO-3166. La valeur |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Utilisé par la notification pour obtenir des statistiques de diagnostic de la portée UWB.
Accepté uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS est défini sur 1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Réservé à l'utilisation des OEM. |
Extensions des fournisseurs pour les messages définis dans la spécification UCI
Cette section décrit les extensions du fournisseur aux messages définis par la spécification UCI.
SESSION_SET_APP_CONFIG_[CMD|RSP] et SESSION_GET_APP_CONFIG_[CMD|RSP]
Vous trouverez ci-dessous les valeurs de longueur de type (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 répertorie les paramètres des messages de configuration de session UWB.
| Nom du paramètre | Longueur (octets) |
Tag (ID) |
Version de l'interface fournisseur | Description |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | Taux d'entrelacement si AOA_RESULT_REQ est défini sur 0xF0. Compatible uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING est défini sur 1. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | Valeur de 1 octet pour activer ou désactiver les rapports de diagnostic.
Ne configurez ce paramètre que lorsque Valeurs:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 ou 4 | 0xE9 |
2 | Masque de bits de 1 octet ou de 4 octets pour configurer les rapports de diagnostic. Ce masque de bits est de 1 octet sous Android 14 ou version ultérieure, et de 4 octets sous Android 13 ou version antérieure. Ne configurez ce paramètre que lorsque Définitions de bits:
|
CORE_GET_CAPS_INFO_RSP
Voici les TLV définies par la pile AOSP dans la partie réservée par le 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.
| Nom du paramètre | Longueur (octets) |
Tag (ID) |
Version de l'interface fournisseur | Description |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | Valeur de 1 octet indiquant la prise en charge de la requête sur les statistiques d'alimentation. Valeurs:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | Valeur de 1 octet indiquant la compatibilité avec la fonctionnalité d'entrelacement d'antenne. Valeurs:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Valeur de 4 octets indiquant l'intervalle minimal de plages minimal accepté en millisecondes. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | Masque de bits de 4 octets indiquant les valeurs RANGE_DATA_NTF_CONFIG acceptées.
Masque de bits où chaque bit correspond aux valeurs utilisées dans RANGE_DATA_NTF_CONFIG dans SET_APP_CFG_CMD. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | Valeur de 1 octet indiquant la prise en charge des rapports RSSI. Valeurs:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | Valeur d'un octet indiquant la prise en charge des rapports de diagnostic. Valeurs:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | Valeur de 4 octets indiquant la durée minimale de slot compatible en RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Valeur de 4 octets indiquant le nombre maximal de sessions de mesure de la distance FiRa pris en charge. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | Masque de bits de 2 octets pour indiquer les canaux compatibles avec la technologie AoA. Chaque Valeurs:
|
Codes d'état
Vous trouverez ci-dessous les codes d'état dans l'espace du fournisseur. Ils sont renvoyés dans les réponses UCI (telles que SESSION_START_RSP) par le sous-système UWB (UWBS).
| Code d'état | Valeur | Description |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Code d'état renvoyé lorsque la session de mesure de la portée actuelle ne peut pas être démarrée en raison d'un conflit avec d'autres sessions de mesure de la portée CCC ou FiRa. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Code d'état renvoyé lorsque la session de mesure de la portée actuelle ne peut pas être démarrée pour des raisons réglementaires UWB. |
Code de motif de changement d'état dans SESSION_STATUS_NTF
Vous trouverez ci-dessous les codes de raison de changement d'état définis dans l'espace du fournisseur pour le champ d'état renvoyé par un UWBS dans SESSION_STATUS_NTF. Cette notification est envoyée par le UWBS lorsque l'état d'une session de mesure de la distance change (par exemple, de ACTIVE à IDLE).
| Code de motif de changement d'état | Valeur | Description |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
L'état de la session a changé, car le canal configuré n'est pas compatible avec la mesure des distances AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
État de la session modifié en raison d'un conflit avec d'autres sessions de portée CCC ou FiRa. |
REASON_REGULATION_UWB_OFF |
0x82 |
L'état de la session a changé, car le UWB doit être désactivé pour des raisons réglementaires. |