Lo stack AOSP a banda ultralarga (UWB) utilizza l' interfaccia UCI definita da FiRa come superficie HAL. L'interfaccia HAL utilizza una pipe opaca ( IUwbChip::sendUciMessage() e IUwbClientCallback::onUciMessage() ) per inviare e ricevere comandi, risposte e notifiche dell'interfaccia di comando UWB (UCI). Tutti i fornitori Android UWB devono supportare tutti i messaggi definiti dalle specifiche FiRa. Il framework UWB è compatibile con le versioni precedenti e funziona con qualsiasi versione UCI implementata dal fornitore UWB sul dispositivo. Poiché il framework AOSP UWB è un modulo , può anche aggiungere selettivamente il supporto per le richieste di modifica approvate (CR) dalla bozza delle specifiche UCI destinate alle principali versioni degli standard FiRa. Eventuali progetti di CR implementati sono soggetti a modifiche.
Definizione dell'interfaccia
L'interfaccia HAL UWB viene definita utilizzando AIDL stabile . L'interfaccia principale utilizza il pacchetto android.hardware.uwb .
Di seguito sono riportate le due interfacce principali nel 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 delle chiamate HAL dal framework UWB
Le immagini seguenti illustrano il flusso di chiamate dal framework UWB per l'inizializzazione dello stack UWB, la deinizializzazione dello stack UWB e i processi di avvio e arresto della sessione UWB.
Figura 1. Flusso delle chiamate di inizializzazione dello stack UWB (attivazione UWB)
Figura 2. Flusso delle chiamate di deinizializzazione dello stack UWB (disattivazione UWB)
Figura 3. Flusso di avvio/arresto della sessione UWB
Configurazione del codice paese UWB
Come illustrato nella Figura 1, il framework UWB configura il codice paese UWB durante l'inizializzazione dello stack UWB utilizzando il comando UCI vendor-space ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ). Il framework UWB tenta di determinare il codice paese UWB utilizzando le seguenti fonti (elencate in ordine di priorità). Il framework UWB si ferma alla prima fonte in cui viene determinato il codice paese.
- Sostituisci codice paese: codice paese forzato tramite un comando shell adb (test locale o automatizzato).
- Prefisso paese telefonia: codice paese recuperato tramite cellulare. Se sono presenti 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 di telefonia noto: ultimo codice paese noto recuperato tramite cellulare. Se sono presenti più SIM che restituiscono codici diversi, il codice paese scelto non è deterministico.
- Codice paese posizione: codice paese recuperato dal provider di posizioni fuse
LocationManager. - Codice paese predefinito OEM: 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 notifica alle app UWB che lo stato dello stack UWB è DISABLED . Successivamente, 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 notifica alle app UWB che lo stack UWB è READY .
Se UWB non può essere utilizzato a causa delle normative locali in un paese, il controller UWB restituisce il codice di stato STATUS_CODE_ANDROID_REGULATION_UWB_OFF . Il framework UWB notifica quindi alle app UWB che lo stato dello stack UWB è DISABLED .
Quando un utente si reca in un paese diverso, 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 portare a una modifica nello stato dello stack UWB.
Formato di comando definito dalle specifiche FIRA UCI
Per il formato dei pacchetti di controllo UCI, vedere la sezione 4.4.2 delle specifiche UCI .
Versionamento dell'interfaccia
La specifica UCI consente ai fornitori UWB di esporre la versione dello stack UCI implementato 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 delle bozze di CR supportate dal modulo UWB
Le seguenti bozze di CR per FiRa 2.0 sono supportate dalla versione del modulo UWB n. 330810000:
Interfaccia UCI Android (porzione del fornitore FiRa)
La specifica UCI definisce un insieme di identificatori di gruppo (GID) e identificatori di codice operativo (OID) per tutti i messaggi definiti dalla specifica. La specifica riserva inoltre una serie di GID riservati esclusivamente all'utilizzo da parte del fornitore. Lo stack UWB AOSP usa alcuni di questi GID e OID del fornitore per comandi specifici di Android che non sono definiti nella specifica. Per i dettagli, vedere la sezione 8.4 delle specifiche UCI .
Questi messaggi del fornitore utilizzati da Android sono definiti nel pacchetto HAL android.hardware.uwb.fira_android .
Versionamento dell'interfaccia del fornitore
I fornitori UWB devono esporre la versione del pacchetto HAL android.hardware.uwb.fira_android supportato nel dispositivo tramite IUwbChip.getSupportedAndroidUciVersion() . Il framework utilizza queste informazioni sulle versioni per gestire la compatibilità con le versioni precedenti.
Elenco di GID e OID Android
La tabella seguente elenca i GID e gli OID per Android. I GID 0xE e 0xF sono riservati agli OEM Android.
| GID | OID | Definizione |
|---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Utilizzato dal comando e dalla risposta per ottenere le 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 o codificato dall'OEM). Il codice paese viene inviato come valore di 2 byte corrispondente al codice paese ISO-3166. Un valore pari a | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Utilizzato dalla notifica per ottenere statistiche diagnostiche di portata UWB. Supportato solo se UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS è impostato su 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Riservato per uso OEM. |
Estensioni del fornitore ai messaggi definiti dalle specifiche UCI
Questa sezione descrive i dettagli delle estensioni del fornitore ai 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 al 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)
La tabella seguente elenca i parametri per i messaggi di configurazione della sessione UWB.
| Nome del parametro | Lunghezza (ottetti) | Etichetta (ID) | Versione dell'interfaccia del fornitore | Descrizione |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Rapporto di interleaving se AOA_RESULT_REQ è impostato su 0xF0 . Supportato solo se 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 a 1 byte per abilitare o disabilitare la segnalazione della diagnostica. Configurare questo parametro solo quando Valori:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 o 4 | 0xE9 | 2 | Maschera di bit da 1 byte o 4 byte per configurare il reporting diagnostico. Questa maschera di bit è di 1 byte in Android 14 o versioni successive e di 4 byte in Android 13 o versioni precedenti. Configurare 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)
Nella tabella seguente sono elencati i parametri per i messaggi di funzionalità UWB.
| Nome del parametro | Lunghezza (ottetti) | Etichetta (ID) | Versione dell'interfaccia del fornitore | Descrizione |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Valore di 1 byte che indica il supporto per la query sulle statistiche energetiche. Valori:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Valore di 1 byte che indica il supporto per la funzione di interleaving dell'antenna. Valori:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Valore di 4 byte che indica l'intervallo minimo supportato in millisecondi. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Maschera di bit da 4 byte che indica i valori RANGE_DATA_NTF_CONFIG supportati. 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 del reporting RSSI. Valori:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Valore a 1 byte che indica il supporto del reporting diagnostico. Valori:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | Valore a 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 FiRa. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | Maschera di bit da 2 byte per indicare i canali che supportano AoA. Ogni Valori:
|
Codici di stato
Di seguito sono riportati i codici di stato nello spazio fornitore. Questi vengono restituiti nelle risposte UCI (come 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 la sessione di misurazione corrente non può essere avviata a causa di un conflitto con altre sessioni di misurazione CCC o FiRa. |
STATUS_REGULATION_UWB_OFF | 0x53 | Codice di stato restituito quando la sessione corrente non può essere avviata per motivi normativi UWB. |
Codice motivo modifica stato in SESSION_STATUS_NTF
Di seguito sono riportati i codici motivo del cambiamento di stato definiti nello spazio fornitore per il campo stato restituito da un UWBS in SESSION_STATUS_NTF . Questa notifica viene inviata dall'UWBS quando lo stato di una sessione di intervallo cambia (ad esempio, da ACTIVE a IDLE ).
| Codice motivo cambio stato | Valore | Descrizione |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | Lo stato della sessione è cambiato perché il canale configurato non supporta l'intervallo AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | Lo stato della sessione è cambiato a causa di un conflitto con altre sessioni di intervallo CCC o FiRa. |
REASON_REGULATION_UWB_OFF | 0x82 | Lo stato della sessione è cambiato perché l'UWB deve essere disabilitato per un motivo normativo. |