A pilha de banda ultralarga (UWB) AOSP usa a interface UCI definida por FiRa como superfície HAL. A interface HAL usa um canal opaco ( IUwbChip::sendUciMessage() e IUwbClientCallback::onUciMessage() ) para enviar e receber comandos, respostas e notificações da interface de comando UWB (UCI). Todos os fornecedores de Android UWB devem oferecer suporte a todas as mensagens definidas pela especificação FiRa. A estrutura UWB é compatível com versões anteriores e funciona com qualquer versão UCI implementada pelo fornecedor UWB no dispositivo. Como a estrutura AOSP UWB é um módulo , ela também pode adicionar seletivamente suporte para solicitações de mudança aprovadas (CRs) a partir de rascunhos de especificações UCI direcionadas para os principais lançamentos de padrões FiRa. Quaisquer projetos de CR implementados estão sujeitos a alterações.
Definição de interface
A interface UWB HAL é definida usando AIDL estável . A interface principal usa o pacote android.hardware.uwb .
A seguir estão as duas interfaces principais do pacote 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);
}
Fluxo de chamadas HAL da estrutura UWB
As imagens a seguir ilustram o fluxo de chamadas da estrutura UWB para a inicialização da pilha UWB, a desinicialização da pilha UWB e os processos de início e parada da sessão UWB.
Figura 1. Fluxo de chamada de inicialização da pilha UWB (ativação UWB)
Figura 2. Fluxo de chamada de desinicialização da pilha UWB (desativação de UWB)
Figura 3. Fluxo de início/parada de sessão UWB
Configuração do código de país UWB
Conforme mostrado na Figura 1, a estrutura UWB configura o código de país UWB durante a inicialização da pilha UWB usando o comando UCI do espaço do fornecedor ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ). A estrutura UWB tenta determinar o código do país UWB usando as seguintes fontes (listadas em ordem de prioridade). A estrutura UWB para na primeira fonte onde o código do país é determinado.
- Substituir código do país: Código do país forçado por meio de um comando shell adb (teste local ou automatizado).
- Código do país de telefonia: Código do país recuperado através do celular. Se houver vários SIMs que retornem códigos diferentes, o código do país escolhido será não determinístico.
- Código do país Wi-Fi: Código do país recuperado por Wi-Fi (80211.ad).
- Último código de país de telefonia conhecido: Último código de país conhecido recuperado através do celular. Se houver vários SIMs que retornem códigos diferentes, o código do país escolhido será não determinístico.
- Código do país do local: código do país recuperado do provedor de localização fundida
LocationManager. - Código de país padrão OEM: Código de país definido pelo fabricante do dispositivo.
Se a estrutura UWB não conseguir determinar um código de país UWB, ela chamará o comando UCI ANDROID_SET_COUNTRY_CODE com um valor DEFAULT_COUNTRY_CODE ("00") e notificará os aplicativos UWB de que o estado da pilha UWB é DISABLED . Posteriormente, quando a estrutura UWB for capaz de determinar um código de país válido, ela configura o novo código de país usando o comando ANDROID_SET_COUNTRY_CODE e notifica os aplicativos UWB de que a pilha UWB está READY .
Se o UWB não puder ser usado devido às regulamentações locais de um país, o controlador UWB retornará o código de status STATUS_CODE_ANDROID_REGULATION_UWB_OFF . A estrutura UWB notifica os aplicativos UWB de que o estado da pilha UWB é DISABLED .
Quando um usuário viaja para um país diferente, a estrutura UWB configura um novo código de país usando o comando UCI ANDROID_SET_COUNTRY_CODE . Dependendo do código de status retornado pelo controlador UWB (com base nas regulamentações UWB do novo país), isso pode levar a uma alteração no estado da pilha UWB.
Formato de comando definido pela especificação FIRA UCI
Para o formato dos pacotes de controle UCI, consulte a seção 4.4.2 da especificação UCI .
Versionamento de interface
A especificação UCI permite que os fornecedores de UWB exponham a versão da pilha UCI implementada pelo dispositivo usando os comandos UCI_GET_DEVICE_INFO_RSP e UCI_GET_CAPS_INFO_RSP . A estrutura usa esses comandos para buscar a versão UCI do dispositivo e alterar seu comportamento de acordo.
Lista de rascunhos de CRs suportados pelo módulo UWB
Os seguintes rascunhos de CRs para FiRa 2.0 são suportados pela versão do módulo UWB #330810000:
Interface Android UCI (parte do fornecedor FiRa)
A especificação UCI define um conjunto de identificadores de grupo (GIDs) e identificadores de opcode (OIDs) para todas as mensagens definidas pela especificação. A especificação também reserva um conjunto de GIDs reservados exclusivamente para uso do fornecedor. A pilha UWB do AOSP usa alguns desses GIDs e OIDs de fornecedores para comandos específicos do Android que não estão definidos na especificação. Para obter detalhes, consulte a seção 8.4 da especificação UCI .
Essas mensagens do fornecedor usadas pelo Android são definidas no pacote HAL android.hardware.uwb.fira_android .
Versionamento da interface do fornecedor
Os fornecedores de UWB devem expor a versão do pacote HAL android.hardware.uwb.fira_android compatível com o dispositivo por meio de IUwbChip.getSupportedAndroidUciVersion() . A estrutura usa essas informações de controle de versão para lidar com a compatibilidade com versões anteriores.
Lista de GIDs e OIDs do Android
A tabela a seguir lista os GIDs e OIDs para Android. Os GIDs 0xE e 0xF são reservados para uso dos OEMs do Android.
| GID | OID | Definição |
|---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Usado pelo comando e resposta para obter estatísticas relacionadas à energia UWB. Suportado apenas se UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY estiver definido como 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Usado para definir o código regulatório atual do país (determinado usando SIM ou Wi-Fi, ou codificado pelo OEM). O código do país é enviado como um valor de 2 bytes correspondente ao código do país ISO-3166. Um valor | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Usado pela notificação para obter estatísticas de diagnóstico de alcance UWB. Suportado apenas se UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS estiver definido como 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Reservado para uso OEM. |
Extensões do fornecedor para mensagens definidas pela especificação UCI
Esta seção descreve detalhes das extensões do fornecedor para mensagens definidas pela especificação UCI.
SESSION_SET_APP_CONFIG_[CMD|RSP] e SESSION_GET_APP_CONFIG_[CMD|RSP]
A seguir estão os valores de comprimento de tipo (TLVs) definidos pela pilha AOSP na parte reservada do fornecedor dos TLVs em APP_CONFIG :
- GID: 0001b (grupo de configuração de sessão UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
A tabela a seguir lista os parâmetros para mensagens de configuração de sessão UWB.
| Nome do parâmetro | Comprimento (octetos) | Marcação (IDs) | Versão da interface do fornecedor | Descrição |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Proporção de intercalação se AOA_RESULT_REQ estiver definido como 0xF0 . Suportado apenas se UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING estiver definido como 1 . |
NB_OF_AZIMUTH_MEASUREMENTS | 1 | 0xE4 | 1 | |
NB_OF_ELEVATION_MEASUREMENTS | 1 | 0xE5 | 1 | |
ENABLE_DIAGNOSTICS | 1 | 0xE8 | 2 | Valor de 1 byte para ativar ou desativar relatórios de diagnóstico. Configure esse parâmetro somente quando Valores:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 ou 4 | 0xE9 | 2 | Máscara de bits de 1 ou 4 bytes para configurar relatórios de diagnóstico. Essa máscara de bits tem 1 byte no Android 14 ou superior e 4 bytes no Android 13 ou inferior. Configure esse parâmetro somente quando Definições de bits:
|
CORE_GET_CAPS_INFO_RSP
A seguir estão os TLVs definidos pela pilha AOSP na parte reservada do fornecedor dos TLVs em CAPS_INFO :
- GID: 0000b (grupo principal UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
A tabela a seguir lista os parâmetros para mensagens de capacidade UWB.
| Nome do parâmetro | Comprimento (octetos) | Marcação (IDs) | Versão da interface do fornecedor | Descrição |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Valor de 1 byte indicando suporte para consulta de estatísticas de energia. Valores:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Valor de 1 byte indicando suporte para o recurso de intercalação de antena. Valores:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Valor de 4 bytes que indica o intervalo mínimo suportado em milissegundos. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Máscara de bits de 4 bytes indicando os valores RANGE_DATA_NTF_CONFIG suportados. Bitmask onde cada bit corresponde aos valores usados em RANGE_DATA_NTF_CONFIG em SET_APP_CFG_CMD . |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | Valor de 1 byte indicando o suporte de relatórios RSSI. Valores:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Valor de 1 byte indicando o suporte de relatórios de diagnóstico. Valores:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | Valor de 4 bytes que indica a duração mínima do slot suportada no RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | Valor de 4 bytes que indica o número máximo suportado de sessões de alcance FiRa. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | Máscara de bits de 2 bytes para indicar os canais que suportam AoA. Cada Valores:
|
Códigos de status
A seguir estão os códigos de status no espaço do fornecedor. Eles são retornados em respostas UCI (como SESSION_START_RSP ) pelo subsistema UWB (UWBS).
| Código de status | Valor | Descrição |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Código de status retornado quando a sessão de alcance atual não pode ser iniciada devido a conflito com outras sessões de alcance CCC ou FiRa. |
STATUS_REGULATION_UWB_OFF | 0x53 | Código de status retornado quando a sessão de alcance atual não pode ser iniciada devido a motivos regulatórios de UWB. |
Código de motivo da alteração de estado em SESSION_STATUS_NTF
A seguir estão os códigos de motivo da mudança de estado definidos no espaço do fornecedor para o campo de status retornado por um UWBS em SESSION_STATUS_NTF . Esta notificação é enviada pelo UWBS quando o estado de uma sessão variada muda (por exemplo, de ACTIVE para IDLE ).
| Código de motivo da mudança de estado | Valor | Descrição |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | O estado da sessão foi alterado porque o canal configurado não oferece suporte ao intervalo AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | O estado da sessão foi alterado devido a conflitos com outras sessões de alcance CCC ou FiRa. |
REASON_REGULATION_UWB_OFF | 0x82 | O estado da sessão foi alterado porque o UWB deve ser desativado por um motivo regulatório. |