Lo stack UWB (banda ultralarga) di AOSP utilizza l'interfaccia UCI definita da FiRa come interfaccia HAL. L'interfaccia HAL utilizza un canale opaco (IUwbChip::sendUciMessage() e IUwbClientCallback::onUciMessage()) per inviare e ricevere comandi, risposte e notifiche dell'interfaccia di comando UWB (UCI).
Tutti i fornitori di Android UWB devono supportare tutti i messaggi definiti dalla specifica FiRa. Il framework UWB è compatibile con le versioni precedenti e funziona con qualsiasi versione UCI implementata dal fornitore UWB sul dispositivo. Poiché il framework UWB AOSP è un modulo, può anche aggiungere in modo selettivo il supporto per le richieste di modifica approvate (RP) da bozze di specifiche UCI destinate alle principali release degli standard FiRa. Le bozze di queste RP implementate sono soggette a modifiche.
Definizione dell'interfaccia
L'interfaccia UWB HAL viene definita utilizzando
AIDL stabile.
L'interfaccia principale utilizza il pacchetto android.hardware.uwb.
Di seguito sono riportate le due interfacce principali del pacchetto 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);
}
Flusso di chiamate HAL dal framework UWB
Le seguenti immagini illustrano il flusso di chiamate dal framework UWB per l'inizializzazione e la disinizializzazione dello stack UWB, nonché per le procedure di avvio e interruzione della sessione UWB.
Figura 1. Flusso di chiamate di inizializzazione dello stack UWB (opzione UWB attivata)
Figura 2. Flusso di chiamata di deinizializzazione dello stack UWB (opzione di attivazione/disattivazione UWB disattivata)
Figura 3. Flusso di avvio/arresto della sessione UWB
Configurazione del codice paese UWB
Come mostrato nella Figura 1, il framework UWB configura il codice paese UWB
durante l'inizializzazione dello stack UWB utilizzando il comando UCI dello spazio del fornitore
ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). Il framework UWB tenta di
determinare il codice paese UWB utilizzando le seguenti origini (elencate in ordine di priorità). Il framework UWB si ferma alla prima origine in cui viene determinato il codice paese.
- Sostituisci il codice paese: il codice paese viene forzato tramite un comando adb shell (test locale o automatico).
- Codice paese per la telefonia: il codice paese recuperato tramite rete mobile. Se esistono più SIM che restituiscono codici diversi, il codice paese scelto è non deterministico.
- Codice paese Wi-Fi: codice paese recuperato tramite Wi-Fi (80211.ad).
- Ultimo codice paese noto per la telefonia: ultimo codice paese noto recuperato tramite la rete cellulare. Se ci sono più SIM che restituiscono codici diversi, il codice paese scelto non è deterministico.
- Codice paese della località: il codice paese recuperato dal fornitore di posizione
LocationManagerfusionato. - Codice paese predefinito OEM: il codice paese impostato dal produttore del dispositivo.
Se il framework UWB non è in grado di determinare un codice paese UWB, chiama il comando UCI ANDROID_SET_COUNTRY_CODE con un valore DEFAULT_COUNTRY_CODE ("00") e comunica alle app UWB che lo stato dello stack UWB è DISABLED. In seguito, quando il framework UWB è in grado di determinare un codice paese valido, configura il nuovo codice paese utilizzando il comando ANDROID_SET_COUNTRY_CODE e comunica alle app UWB che lo stack UWB è READY.
Se la tecnologia UWB non può essere utilizzata
a causa delle normative locali di un paese, il controller UWB restituisce il
codice di stato STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Il framework UWB poi
notifica alle app UWB che lo stato dello stack UWB è DISABLED.
Quando un utente si reca in un altro paese, il framework UWB configura un nuovo codice paese utilizzando il comando UCI ANDROID_SET_COUNTRY_CODE. A seconda del codice di stato restituito dal controller UWB (in base alle normative UWB nel nuovo paese), ciò potrebbe comportare una modifica dello stato dello stack UWB.
Formato del comando definito dalla specifica FIRA UCI
Per il formato dei pacchetti di controllo UCI, consulta la sezione 4.4.2 della specifica UCI.
Controllo delle versioni dell'interfaccia
La specifica UCI consente ai fornitori UWB di esporre la versione dello stack UCI implementata dal dispositivo utilizzando i comandi UCI_GET_DEVICE_INFO_RSP e UCI_GET_CAPS_INFO_RSP. Il framework utilizza questi comandi per recuperare la versione UCI del dispositivo e modificarne il comportamento di conseguenza.
Elenco di bozze di RP supportate dal modulo UWB
Le seguenti RP in versione bozza per FiRa 2.0 sono supportate dalla versione n. 330810000 del modulo UWB:
- CR 287
- Supporto dell'API SUS e delle specifiche UCI per i requisiti dell'interfaccia della chiave digitale CCC
Interfaccia UCI di Android (parte del fornitore FiRa)
La specifica UCI definisce un insieme di identificatori di gruppo (GID) e identificatori di opcode (OID) per tutti i messaggi definiti dalla specifica. La specifica inoltre riserva un insieme di GID riservati esclusivamente all'utilizzo da parte del fornitore. Lo stack AOSP UWB utilizza alcuni di questi GID e OID del fornitore per i comandi specifici di Android che non sono definiti nella specifica. Per maggiori dettagli, consulta la sezione 8.4 della specifica UCI.
Questi messaggi del fornitore utilizzati da Android sono definiti nel
android.hardware.uwb.fira_android pacchetto HAL.
Controllo delle versioni dell'interfaccia del fornitore
I fornitori di UWB devono esporre la versione del pacchetto HAL android.hardware.uwb.fira_android
supportata sul dispositivo tramite
IUwbChip.getSupportedAndroidUciVersion(). Il framework utilizza queste informazioni sul versionamento per gestire la compatibilità con le versioni precedenti.
Elenco di GID e OID di Android
Nella tabella seguente sono elencati i GID e gli OID per Android. I GID 0xE e 0xF
sono riservati all'utilizzo da parte degli OEM Android.
| GID | OID | Definizione |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Utilizzato dal comando e dalla risposta per ottenere statistiche relative alla potenza UWB.
Supportato solo se
UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY
è impostato su 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Utilizzato per impostare il codice paese normativo corrente (determinato tramite SIM o Wi-Fi oppure hardcoded dall'OEM). Il codice paese viene inviato
come valore di 2 byte corrispondente al codice paese ISO-3166. Un valore
di |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Utilizzato dalla notifica per ottenere le statistiche di diagnostica della misurazione della distanza UWB.
Supportato solo se
UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS è impostato su
1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Riservato per l'uso OEM. |
Estensioni del fornitore ai messaggi definiti dalla specifica UCI
Questa sezione descrive i dettagli delle estensioni del fornitore per i messaggi definiti dalle specifiche UCI.
SESSION_SET_APP_CONFIG_[CMD|RSP] e SESSION_GET_APP_CONFIG_[CMD|RSP]
Di seguito sono riportati i valori di lunghezza del tipo (TLV) definiti dallo stack AOSP nella
parte riservata del fornitore dei TLV in APP_CONFIG:
- GID: 0001b (gruppo di configurazione della sessione UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
Nella tabella seguente sono elencati i parametri per i messaggi di configurazione della sessione UWB.
| Nome parametro | Lunghezza (ottetti) |
Tag (ID) |
Versione interfaccia del fornitore | Descrizione |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | Rapporto di interlacciamento se AOA_RESULT_REQ è impostato su 0xF0. Supportata solo se il valore
UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING
è impostato su 1. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | Valore di 1 byte per attivare o disattivare i report di diagnostica.
Configura questo parametro solo quando Valori:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 o 4 | 0xE9 |
2 | Una maschera di bit di 1 o 4 byte per configurare i report di diagnostica. Questa maschera di bit è di 1 byte in Android 14 o versioni successive e di 4 byte in Android 13 o versioni precedenti. Configura questo parametro solo quando Definizioni dei bit:
|
CORE_GET_CAPS_INFO_RSP
Di seguito sono riportati i TLV definiti dallo stack AOSP nella parte riservata al fornitore dei TLV in CAPS_INFO:
- GID: 0000b (gruppo principale UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
La tabella seguente elenca i parametri per i messaggi relativi alle funzionalità UWB.
| Nome parametro | Lunghezza (ottetti) |
Tag (ID) |
Versione interfaccia del fornitore | Descrizione |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | Valore di 1 byte che indica il supporto per la query sulle statistiche sull'alimentazione. Valori:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | Un valore di 1 byte che indica il supporto della funzionalità di interlacciamento dell'antenna. Valori:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Valore di 4 byte che indica l'intervallo di misurazione minimo supportato in millisecondi. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | Maschera di bit di 4 byte che indica i valori supportati
RANGE_DATA_NTF_CONFIG.
Maschera di bit in cui ogni bit corrisponde ai valori utilizzati in
RANGE_DATA_NTF_CONFIG in SET_APP_CFG_CMD. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | Valore di 1 byte che indica il supporto dei report RSSI. Valori:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | Un valore di 1 byte che indica il supporto dei report di diagnostica. Valori:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | Valore di 4 byte che indica la durata minima dello slot supportata in RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Valore di 4 byte che indica il numero massimo supportato di sessioni di misurazione della distanza FiRa. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | Bitmask di 2 byte per indicare i canali che supportano AoA. Ogni
Valori:
|
Codici di stato
Di seguito sono riportati i codici di stato nello spazio del fornitore. Questi vengono restituiti nelle risposte UCI (ad esempio SESSION_START_RSP) dal sottosistema UWB (UWBS).
| Codice di stato | Valore | Descrizione |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Codice di stato restituito quando non è possibile avviare la sessione di misurazione corrente a causa di un conflitto con altre sessioni di misurazione CCC o FiRa. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Codice di stato restituito quando non è possibile avviare la sessione di misurazione corrente per motivi normativi relativi alla tecnologia UWB. |
Codice del motivo della modifica dello stato in SESSION_STATUS_NTF
Di seguito sono riportati i codici del motivo della modifica dello stato definiti nello spazio del fornitore per il campo stato restituito da un UWBS in SESSION_STATUS_NTF. Questa notifica viene inviata dall'UWBS quando cambia lo stato di una sessione di misurazione (ad esempio da ACTIVE a IDLE).
| Codice del motivo del cambiamento di stato | Valore | Descrizione |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
Lo stato della sessione è cambiato perché il canale configurato non supporta la misurazione AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
Lo stato della sessione è cambiato a causa di un conflitto con altre sessioni di misurazione CCC o FiRa. |
REASON_REGULATION_UWB_OFF |
0x82 |
Lo stato della sessione è cambiato perché la tecnologia UWB deve essere disattivata per motivi normativi. |