Interface HAL du module UWB

L'AOSP pile ultralarge (UWB) utilise le Interface UCI définie par FiRa que la surface HAL. L'interface HAL utilise un tuyau opaque (IUwbChip::sendUciMessage() et IUwbClientCallback::onUciMessage()) pour envoyer le message et recevoir des commandes, réponses et notifications UWB. Tous les fournisseurs Android UWB doivent respecter toutes les spécifications FiRa définies messages. Le framework UWB est rétrocompatible et fonctionne avec toutes les UCI implémentée par le fournisseur de la UWB sur l'appareil. Étant donné que l'AOSP UWB est un module. il peut aussi prendre en charge de façon sélective les demandes de modification (RS) approuvées depuis ébauche des spécifications UCI ciblées pour les principales versions des normes FiRa. N'importe lequel de ces les versions préliminaires de RS mises en œuvre sont susceptibles d'être modifiées.

Définition de l'interface

L'interface HAL du module UWB est définie AIDL stable. L'interface principale utilise le package android.hardware.uwb.

Voici les deux principales interfaces de android.hardware.uwb. d'un package.

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 depuis le framework UWB

Les images suivantes illustrent le flux d'appel du framework UWB pour le Initialisation de la pile UWB, désinitialisation de la pile UWB et démarrage et session de la pile UWB et d'arrêter les processus.

Initialisation de la pile UWB

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

Désinitialisation de la pile UWB

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

Démarrage et arrêt de la session UWB

Figure 3. Démarrage/Arrêt de la session UWB

Configuration du code pays de l'UWB

Comme le montre la figure 1, le framework UWB configure le code pays de l'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éterminez le code pays de l'UWB à l'aide des sources suivantes (répertoriées dans la priorité commande). Le framework UWB s'arrête à la première source où le code pays est déterminé.

  1. Remplacer le code pays: code pays forcé via une commande adb shell (tests en local ou automatisés).
  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é par le Wi-Fi (80211.ad).
  4. Dernier code pays connu pour la téléphonie: dernier code pays connu récupéré via le réseau mobile. Si plusieurs cartes SIM renvoient des résultats différents , le code pays choisi n'est pas déterministe.
  5. Code pays de la zone géographique: code pays récupéré à partir du LocationManager Fused Location Provider.
  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 le ANDROID_SET_COUNTRY_CODE commande UCI avec la valeur DEFAULT_COUNTRY_CODE ("00") et informe les applications du module UWB que l'état de la pile UWB est DISABLED. Plus tard, lorsque le framework UWB est en mesure déterminez code pays valide, il configure le nouveau code de pays à l'aide de l'attribut 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 des réglementations locales en vigueur dans un pays, le contrôleur UWB renvoie le Code d'état STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Le framework UWB Informe 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 dans un 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 de la section 4.4.2 de la loi UCI. caractéristiques.

Gestion des versions d'interface

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

Liste des brouillons de RS compatibles avec le module UWB

Les brouillons de RS suivants pour FiRa 2.0 sont pris en charge par Module UWB, version 330810000:

Interface Android UCI (partie fournisseur FiRa)

La spécification UCI définit un ensemble d'identifiants de groupe (GID) et de codes d'opération. (OID) pour tous les messages définis par une spécification. La spécification réserve également un ensemble de GID exclusivement réservé à l'utilisation du fournisseur. L'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 section 8.4 de la UCI caractéristiques.

Ces messages de 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 de UWB doivent exposer la version de android.hardware.uwb.fira_android package HAL pris en charge sur l’appareil via IUwbChip.getSupportedAndroidUciVersion() Le framework utilise cette 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. 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 l'alimentation du module UWB. Disponible uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY est définie sur 1.
ANDROID_SET_COUNTRY_CODE = 0x1

Permet de définir le code pays de réglementation actuel (déterminé à l'aide de carte SIM ou Wi-Fi, ou codé en dur par l'OEM). Le code pays est envoyé sous la forme d'une valeur de deux octets correspondant au code pays ISO-3166. A La valeur 00 est utilisée pour indiquer que le code pays est inconnue.
ANDROID_RANGE_DIAGNOSTICS = 0x2 Utilisé par la notification pour obtenir les statistiques de diagnostic des distances de l'UWB. Disponible uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS défini à 1.
OEM = 0xE,0xF 0x00 - 0x3F Utilisation réservée aux OEM.

Extensions du fournisseur pour les messages définis dans la spécification UCI

Cette section décrit en détail les extensions des fournisseurs visant l'UCI. et les messages définis par une spécification.

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 le partie des TLV réservée par le fournisseur 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 à 0xF0. Compatible uniquement si UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING définie 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 permettant d'activer ou de désactiver les rapports de diagnostic. Ne configurez ce paramètre que si CORE_GET_CAPS_INFO_RSP renvoie SUPPORTED_DIAGNOSTICS avec une valeur de 1 indique que la fonctionnalité de création de rapports sur les diagnostics est compatibles.

Valeurs:

  • 1: fonctionnalité activée
  • 0: fonctionnalité désactivée
DIAGRAMS_FRAME_REPORTS_FIELDS 1 ou 4 0xE9 2

Masque de bits de 1 ou 4 octets pour configurer les rapports de diagnostic. Ce le masque de bits est de 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 Retours pour CORE_GET_CAPS_INFO_RSP SUPPORTED_DIAGNOSTICS avec une valeur de 1 indiquant que la fonctionnalité de création de rapports sur les diagnostics est disponible.

Définitions de bits:

  • b0 (0x01): activer les champs RSSI
  • b1 (0x02): activer les champs AoA
  • b2 (0x04): activez les champs CIR

CORE_GET_CAPS_INFO_RSP

Vous trouverez ci-dessous les TLV définis par la pile AOSP du fournisseur des TLV dans CAPS_INFO:

  • GID: 0000b (groupe principal du module 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 de statistiques d'alimentation.

Valeurs:

  • 1: fonctionnalité compatible
  • 0: fonctionnalité non disponible
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Valeur de 1 octet indiquant la compatibilité avec l'entrelacement de l'antenne .

Valeurs:

  • 1: fonctionnalité compatible
  • 0: fonctionnalité non disponible
SUPPORTED_MIN_RANGING_INTERVAL_MS 4 0xE4 2 Valeur de 4 octets indiquant l'intervalle minimal accepté pour les distances en millisecondes.
SUPPORTED_RANGE_DATA_NTF_CONFIG 4 0xE5 2 Masque de bits de 4 octets indiquant Valeurs RANGE_DATA_NTF_CONFIG. Masque de bits dans lequel 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:

  • 1: fonctionnalité compatible
  • 0: fonctionnalité non disponible
SUPPORTED_DIAGNOSTICS 1 0xE7 2

Valeur de 1 octet indiquant la prise en charge des rapports de diagnostic.

Valeurs:

  • 1: fonctionnalité compatible
  • 0: fonctionnalité non disponible
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 Valeur de 4 octets indiquant la durée d'emplacement minimale acceptée en RSTU.
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 Valeur de 4 octets indiquant le nombre maximal accepté de plages FiRa sessions.
SUPPORTED_CHANNELS_AOA 2 0xEA 2

Masque de bits de 2 octets pour indiquer les canaux compatibles avec AoA. Chaque 1 dans le masque de bits correspond à un canal UWB spécifique.

Valeurs:

  • 0x01: canal 5 accepté
  • 0x02: canal 6 accepté
  • 0x04: canal 8 accepté
  • 0x08: canal 9 accepté
  • 0x10: canal 10 accepté
  • 0x20: canal 12 compatible
  • 0x40: canal 13 compatible
  • 0x80: canal 14 accepté

Codes d'état

Voici les codes d'état dans l'espace des fournisseurs. Elles sont renvoyées dans Réponses UCI (telles que SESSION_START_RSP) du sous-système UWB (UWB).

Code d'état Valeur Description
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

Code d'état renvoyé lorsque la session de mesure des distances en cours ne peut pas être a débuté en raison d'un conflit avec d'autres sessions de mesure de la distance de la CCC ou de la FiRa.
STATUS_REGULATION_UWB_OFF 0x53

Code d'état renvoyé lorsque la session de mesure des distances en cours ne peut pas être pour des raisons réglementaires UWB.

Code du 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 des fournisseurs pour le champ d'état renvoyé par un service UWBS dans SESSION_STATUS_NTF. Cette notification est envoyé par UWBS lorsque l'état d'une session de mesure des distances change (par exemple, de ACTIVE à IDLE).

Code du 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é prend en charge la fourchette de l'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 CCC ou FiRa et la détermination de la tendance des sessions.
REASON_REGULATION_UWB_OFF 0x82

L'état de la session a été modifié, car l'UWB doit être désactivé en raison d'une une raison réglementaire.