La pile ultra-large bande (UWB) 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 par 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 de manière sélective la prise en charge des demandes de modification (CR) approuvées à partir des projets de spécifications UCI ciblées pour les principales versions des normes FiRa. Tous les projets de CR mis en œuvre sont susceptibles d’être modifiés.
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'appels 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 et les processus de démarrage et d'arrêt de session UWB.
Figure 1. Flux d'appels d'initialisation de la pile UWB (option UWB activée)
Figure 2. Flux d'appels de désinitialisation de la pile UWB (désactivation de l'UWB)
Figure 3. Flux de démarrage/arrêt de session UWB
Configuration du code pays UWB
Comme le montre la figure 1, le cadre UWB configure le code de 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 cadre UWB tente de déterminer le code de pays UWB à l'aide des sources suivantes (répertoriées par ordre de priorité). Le cadre UWB s'arrête à la première source où le code du pays est déterminé.
- Remplacer le code du pays : code du pays forcé via une commande shell adb (test local ou automatisé).
- Indicatif du pays de téléphonie : indicatif du pays récupéré via le réseau cellulaire. Si plusieurs cartes SIM renvoient des codes différents, le code du pays choisi n'est pas déterministe.
- Indicatif pays Wi-Fi : indicatif du pays récupéré via Wi-Fi (80211.ad).
- Dernier indicatif de pays de téléphonie connu : dernier indicatif de pays connu récupéré via le cellulaire. Si plusieurs cartes SIM renvoient des codes différents, le code du pays choisi n'est pas déterministe.
- Code de pays de localisation : code de pays récupéré du fournisseur de localisation fusionné
LocationManager. - Code pays par défaut OEM : code pays défini par le fabricant de l'appareil.
Si l'infrastructure UWB ne parvient pas à déterminer un code de pays UWB, elle appelle la commande UCI ANDROID_SET_COUNTRY_CODE avec la valeur 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 capable de déterminer un code de pays valide, il configure le nouveau code de pays à l'aide de la commande ANDROID_SET_COUNTRY_CODE et informe les applications UWB que la pile UWB est READY .
Si UWB ne peut pas être utilisé en raison des réglementations locales 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 voyage dans un autre pays, le framework UWB configure un nouveau code de 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 du 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 le format des paquets de contrôle UCI, voir la section 4.4.2 de la spécification UCI .
Gestion des versions d'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 projets de CR pris en charge par le module UWB
Les projets de CR suivants pour FiRa 2.0 sont pris en charge par la version du module UWB #330810000 :
- CR 287
- Prise en charge de l'API SUS et des spécifications UCI pour les exigences de 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 d'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'usage du fournisseur. La pile AOSP UWB 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 plus de détails, voir 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 fournisseur
Les fournisseurs UWB doivent exposer la version du package HAL android.hardware.uwb.fira_android pris en charge sur l'appareil via IUwbChip.getSupportedAndroidUciVersion() . Le framework utilise ces informations de version pour gérer la compatibilité ascendante.
Liste des GID et OID Android
Le tableau suivant répertorie les GID et 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 les statistiques liées à l'alimentation UWB. Pris en charge uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY est défini sur 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Utilisé pour définir le code de pays réglementaire actuel (déterminé à l'aide de la carte SIM ou du Wi-Fi, ou codé en dur par l'OEM). Le code du pays est envoyé sous forme de valeur de 2 octets correspondant au code du pays ISO-3166. La valeur | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Utilisé par la notification pour obtenir les statistiques de diagnostic de portée UWB. Pris en charge uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS est défini sur 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Réservé à un usage OEM. |
Extensions du fournisseur aux messages définis par la spécification UCI
Cette section décrit les détails des 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]
Voici 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.
| Le nom du paramètre | Longueur (octets) | Étiqueter (pièces d'identité) | 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 . Pris en charge 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. Configurez ce paramètre uniquement lorsque Valeurs:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 ou 4 | 0xE9 | 2 | Masque de bits de 1 ou 4 octets pour configurer les rapports de diagnostic. Ce masque de bits fait 1 octet sous Android 14 ou version ultérieure et 4 octets sous Android 13 ou version antérieure. Configurez ce paramètre uniquement lorsque Définitions de bits :
|
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 central UWB)
- OID : 000011b (
CORE_GET_CAPS_INFO_RSP)
Le tableau suivant répertorie les paramètres des messages de fonctionnalité UWB.
| Le nom du paramètre | Longueur (octets) | Étiqueter (pièces d'identité) | 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 de statistiques d'alimentation. Valeurs:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Valeur de 1 octet indiquant la prise en charge de la fonction d’entrelacement d’antenne. Valeurs:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Valeur de 4 octets indiquant l'intervalle de portée minimum pris en charge en millisecondes. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Masque de bits de 4 octets indiquant les valeurs RANGE_DATA_NTF_CONFIG prises en charge. 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 du reporting RSSI. Valeurs:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Valeur de 1 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 créneau prise en charge dans RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | Valeur de 4 octets indiquant le nombre maximum de sessions de télémétrie FiRa prises en charge. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | Masque de bits de 2 octets pour indiquer les canaux prenant en charge l'AoA. Chaque Valeurs:
|
Codes d'état
Voici les codes d'état dans l'espace fournisseur. Ceux-ci 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 télémétrie en cours ne peut pas être démarrée en raison d'un conflit avec d'autres sessions de télémétrie CCC ou FiRa. |
STATUS_REGULATION_UWB_OFF | 0x53 | Code d'état renvoyé lorsque la session de télémétrie en cours ne peut pas être démarrée pour des raisons réglementaires UWB. |
Code de motif de changement d'état dans SESSION_STATUS_NTF
Voici 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 télémétrie change (par exemple, de ACTIVE à IDLE ).
| Code motif du changement d’état | Valeur | Description |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | L'état de la session a changé car le canal configuré ne prend pas en charge la plage AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | L'état de la session a changé en raison d'un conflit avec d'autres sessions de télémétrie CCC ou FiRa. |
REASON_REGULATION_UWB_OFF | 0x82 | L'état de la session a changé car l'UWB doit être désactivé pour une raison réglementaire. |