Interfaccia HAL UWB

Lo stack di banda ultralarga (UWB) AOSP utilizza l'interfaccia UCI definita da FiRa come superficie 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 UWB per Android devono supportare tutti i messaggi definiti nella 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 AOSP UWB è un modulo, può anche aggiungere selettivamente il supporto per le richieste di modifica (CR) approvate dalle specifiche UCI bozza destinate alle principali versioni degli standard FiRa. Eventuali proposte di modifica implementate sono soggette a modifiche.

Definizione dell'interfaccia

L'interfaccia UWB HAL è 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 dello stack UWB, la deinizializzazione dello stack UWB e i processi di avvio e arresto della sessione UWB.

Figura 1. Flusso di chiamate di inizializzazione dello stack UWB (opzione UWB attivata)

Figura 2. Flusso di chiamate di deinizializzazione dello stack UWB (opzione UWB disattivata)

Figura 3. Flusso di avvio/interruzione 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 fornitore 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 arresta alla prima origine in cui viene determinato il codice paese.

1. Override del codice paese: codice paese forzato tramite un comando adb shell (test locali o automatizzati).
2. Codice paese telefonia: il codice paese recuperato tramite la rete cellulare. Se sono presenti più SIM che restituiscono codici diversi, il codice paese scelto è non deterministico.
3. Codice paese Wi-Fi: codice paese recuperato tramite Wi-Fi (80211.ad).
4. Ultimo codice paese di telefonia noto: l'ultimo codice paese recuperato tramite rete cellulare. Se ci sono più SIM che restituiscono codici diversi, il codice paese scelto è non deterministico.
5. Codice paese della località: codice paese recuperato dal fornitore di servizi di localizzazione LocationManager.
6. 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 di DEFAULT_COUNTRY_CODE ("00") e comunica alle app UWB che lo stato dello stack UWB è DISABLED. In un secondo momento, 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 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 del nuovo paese), ciò potrebbe comportare una modifica dello stato dello stack UWB.

Formato dei comandi definito dalle specifiche UCI FIRA

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 modificare il suo comportamento di conseguenza.

Elenco delle CR bozza supportate dal modulo UWB

Le seguenti CR bozza per FiRa 2.0 sono supportate dalla versione n. 330810000 del modulo UWB:

• CR 287
• Supporto delle API SUS e delle specifiche UCI per i requisiti dell'interfaccia CCC Digital Key

Interfaccia UCI 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 nella specifica. La specifica riserva anche un insieme di GID riservati esclusivamente all'utilizzo da parte dei fornitori. Lo stack UWB AOSP 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 delle specifiche UCI.

Questi messaggi del fornitore utilizzati da Android sono definiti nel pacchetto HAL android.hardware.uwb.fira_android.

Controllo delle versioni dell'interfaccia fornitore

I fornitori UWB devono esporre la versione del pacchetto HAL android.hardware.uwb.fira_android supportato sul dispositivo tramite IUwbChip.getSupportedAndroidUciVersion(). Il framework utilizza queste informazioni sul controllo delle 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. Gli ID gruppo 0xE e 0xF sono riservati per l'utilizzo da parte degli OEM Android.

Estensioni del fornitore ai messaggi definiti nella specifica 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.

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 alla funzionalità UWB.

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 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 dello stato restituito da un UWBS in SESSION_STATUS_NTF. Questa notifica viene inviata dall'UWB quando lo stato di una sessione di misurazione cambia (ad esempio, da ACTIVE a IDLE).