O AOSP
Pilha de banda ultralarga (UWB)
usa o
Interface UCI definida pelo Figma
como a superfície da HAL. A interface HAL usa um cano opaco
(IUwbChip::sendUciMessage() e IUwbClientCallback::onUciMessage()) para enviar
e receber comandos, respostas e notificações da interface de comando da UWB (UCI).
Todos os fornecedores de UWB do Android precisam oferecer suporte a todas as especificações FiRa definidas
mensagens. O framework UWB é compatível com versões anteriores e funciona com qualquer UCI
a versão implementada pelo fornecedor de UWB no dispositivo. Como a UWB do AOSP
é um módulo,
ele também pode adicionar seletivamente suporte para solicitações de alteração aprovadas (CRs, na sigla em inglês) de
elabora especificações da UCI direcionadas para os principais lançamentos de padrões FiRa. Qualquer um desses
os rascunhos de respostas automáticas implementados estão sujeitos a alterações.
Definição de interface
A interface HAL de UWB é definida usando
AIDL estável.
A interface principal usa o pacote android.hardware.uwb.
Estas são as duas interfaces principais no 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 chamada de HAL do framework UWB
As imagens a seguir ilustram o fluxo de chamadas da estrutura UWB para o Inicialização da pilha UWB, desinicialização da pilha UWB e início e início da sessão UWB e interromper processos.
Figura 1. Fluxo de chamadas de inicialização de pilha UWB (alternância de UWB ativada)
Figura 2. Fluxo de chamadas de desinicialização da pilha UWB (botão UWB desativado)
Figura 3. Fluxo de início/parada da sessão UWB
Configuração do código do país da UWB
Como mostrado na Figura 1, o framework da UWB configura o código do país da UWB.
durante a inicialização da pilha UWB usando o comando da UCI no espaço do fornecedor
ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). A estrutura de UWB tenta
determine o código do país da UWB usando as seguintes fontes (listadas em prioridade)
). A estrutura UWB é interrompida na primeira fonte em que o código do país é
determinados.
- Substituir código do país: código do país forçado por meio de um comando adb shell (testes locais ou automatizados).
- Código do país da telefonia: código do país recuperado pela rede celular. Se vários chips retornam códigos diferentes, o código do país escolhido é não determinista.
- Código do país do Wi-Fi: o código do país extraído pelo Wi-Fi (80211.ad).
- Último código de país da telefonia conhecido: último código de país conhecido recuperado pela rede celular. Se vários chips retornarem números diferentes códigos de país, o código de país escolhido não é determinístico.
- Código de país do local: código do país extraído do
LocationManagerprovedor de localização combinada. - Código do país padrão do OEM: código do país definido pelo fabricante do dispositivo.
Se a estrutura da UWB não puder determinar um código do país da UWB, ele chamará o método
comando ANDROID_SET_COUNTRY_CODE da UCI com um valor de
DEFAULT_COUNTRY_CODE ("00") e notifica os apps de UWB que
o estado da pilha UWB é DISABLED. Depois, quando a estrutura UWB for capaz de
determinar um
código de país válido, ele configura o novo código de país usando o
ANDROID_SET_COUNTRY_CODE e notifica os apps UWB de que a pilha UWB
é READY.
Se não for possível usar UWB
devido às regulamentações locais em um país, o controlador da UWB retornará o
Código de status STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Em seguida, a estrutura UWB
notifica os apps UWB de que o estado da pilha UWB é DISABLED.
Quando um usuário viaja para outro país, a estrutura UWB configura uma nova
código do país usando o comando ANDROID_SET_COUNTRY_CODE da UCI. Dependendo
código de status retornado pelo controlador da UWB (com base nos regulamentos da UWB na
novo país), isso poderá levar a uma alteração no estado da pilha UWB.
Formato de comando definido pela especificação da UCI FIRA
Para o formato dos pacotes de controle da UCI, consulte seção 4.4.2 da UCI especificação.
Controle de versões da interface
A especificação da UCI permite que os fornecedores de UWB exponham a versão da pilha da UCI.
implementado pelo dispositivo usando as APIs UCI_GET_DEVICE_INFO_RSP e
UCI_GET_CAPS_INFO_RSP. O framework usa esses comandos para buscar a
A versão UCI do dispositivo e mude o comportamento dela.
Lista de rascunhos de respostas automáticas compatíveis com o módulo da UWB
Os seguintes rascunhos de respostas automáticas para a FiRa 2.0 são compatíveis com Versão do módulo UWB #330810000:
- CR 287 (link em inglês)
- Suporte às especificações da UCI e API SUS para a interface de chave digital CCC Requisitos
Interface da UCI do Android (parte do fornecedor FiRa)
A especificação da UCI define um conjunto de identificadores de grupo (GIDs) e código de operação identificadores (OIDs, na sigla em inglês) de todas as mensagens definidas pela especificação. A especificação também reserva um conjunto de GIDs reservados exclusivamente para uso do fornecedor. A 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 mais detalhes, consulte seção 8.4 da UCI especificação.
Essas mensagens de fornecedor usadas pelo Android são definidas no
Pacote HAL android.hardware.uwb.fira_android.
Controle de versões da interface do fornecedor
Os fornecedores de UWB precisam expor a versão do android.hardware.uwb.fira_android
para o pacote HAL compatível com o dispositivo por
IUwbChip.getSupportedAndroidUciVersion(). O framework usa isso
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. GIDs 0xE e 0xF
são reservados aos OEMs do Android.
| GID | ID | Definição |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Usado pelo comando e pela resposta para obter estatísticas relacionadas à energia UWB.
Compatível apenas se
UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY
é definido como 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Usado para definir o código regulamentar atual do país (determinado pela
chip ou Wi-Fi ou fixado no código pelo OEM. O código do país é enviado
como um valor de 2 bytes correspondente ao código de país ISO-3166. Um
|
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Usado pela notificação para receber estatísticas de diagnóstico de alcance da UWB.
Compatível apenas se
UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS está definido
para 1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Reservado para uso de OEM. |
Extensões do fornecedor para mensagens definidas da especificação da UCI
Esta seção descreve detalhes das extensões de fornecedores para a UCI mensagens definidas pela especificação.
SESSION_SET_APP_CONFIG_[CMD|RSP] e SESSION_GET_APP_CONFIG_[CMD|RSP]
Confira a seguir os valores de comprimento de tipo (TLVs) definidos pela pilha do AOSP no
parte reservada do fornecedor dos TLVs em APP_CONFIG:
- GID: 0001b (grupo de configuração da sessão de UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
A tabela a seguir lista os parâmetros das mensagens de configuração da sessão UWB.
| Nome do parâmetro | Comprimento (octetos) |
Tag (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
para 0xF0. Suportado apenas se o
UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING
Defina 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 os relatórios de diagnóstico.
Configurar este parâmetro somente quando Valores:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 ou 4 | 0xE9 |
2 | Bitmask de 1 ou 4 bytes para configurar relatórios de diagnóstico. Isso Bitmask tem 1 byte no Android 14 ou versões mais recentes e 4 bytes no Android 13 ou versões anteriores. Configure este parâmetro somente quando o
Devolução por Definições de bit:
|
CORE_GET_CAPS_INFO_RSP
Confira a seguir os TLVs definidos pela pilha do AOSP na lista de fornecedores reservados
dos TLVs em CAPS_INFO:
- GID: 0000b (grupo principal de UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
A tabela a seguir lista os parâmetros das mensagens de capacidade da UWB.
| Nome do parâmetro | Comprimento (octetos) |
Tag (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 a intercalação de antenas . Valores:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Valor de 4 bytes indicando o intervalo mínimo de alcance compatível em milésimos de segundo. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | Bitmask de 4 bytes indicando o suporte
RANGE_DATA_NTF_CONFIG.
Bitmask em que cada bit corresponde aos valores usados na
RANGE_DATA_NTF_CONFIG em SET_APP_CFG_CMD. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | Valor de 1 byte indicando o suporte a 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 quatro bytes indicando a duração mínima de slot compatível em RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Valor de 4 bytes indicando o número máximo aceito de alcance FiRa de conteúdo. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | Bitmask de 2 bytes para indicar os canais que oferecem suporte ao AoA. Cada
Valores:
|
Códigos de status
Confira a seguir 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 iniciado devido a um conflito com outras sessões de alcance do CCC ou FiRa. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Código de status retornado quando a sessão de alcance atual não pode ser começaram por motivos regulatórios da UWB. |
Código do motivo da alteração de estado em SESSION_STATUS_NTF
A seguir estão os códigos de motivo para 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
é enviado pelo UWBS quando o estado de uma sessão de alcance muda (por exemplo,
de ACTIVE para IDLE).
| Código do motivo da mudança de estado | Valor | Descrição |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
O estado da sessão mudou porque o canal configurado não são compatíveis com o alcance AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
O estado da sessão mudou devido a um conflito com outro CCC ou FiRa de alcance. |
REASON_REGULATION_UWB_OFF |
0x82 |
O estado da sessão mudou porque a UWB precisa ser desativada devido a uma por motivos regulamentares. |