A pilha
ultra-wideband (UWB) do AOSP
usa a
interface UCI definida pelo FiRa
como a superfície HAL. A interface HAL usa um tubo opaco
(IUwbChip::sendUciMessage() e IUwbClientCallback::onUciMessage()) para enviar
e receber comandos, respostas e notificações da interface de comando UWB (UCI, na sigla em inglês).
Todos os fornecedores de UWB do Android precisam oferecer suporte a todas as mensagens definidas
pela especificação FiRa. O framework UWB é compatível com versões anteriores e funciona com qualquer versão
de UCI implementada pelo fornecedor UWB no dispositivo. Como o framework UWB do AOSP
é um módulo,
ele também pode adicionar seletivamente suporte a solicitações de mudança (CRs, na sigla em inglês) aprovadas de
especificações de UCI de rascunho direcionadas a principais versões de padrões FiRa. Todos os
rascunhos de CR implementados estão sujeitos a mudanças.
Definição da interface
A interface HAL para UWB é definida usando a
AIDL estável.
A interface principal usa o pacote android.hardware.uwb.
Confira abaixo 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 chamada de HAL do framework de UWB
As imagens a seguir ilustram o fluxo de chamadas do framework UWB para a inicialização da pilha UWB, a desativaçã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 (comutador UWB ativado)
Figura 2. Fluxo de chamada de desativação da pilha UWB (comutador da UWB desativado)
Figura 3. Fluxo de início/parada da sessão de UWB
Configuração do código de país da UWB
Conforme mostrado na Figura 1, o framework UWB configura o código de país da 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). O framework UWB tenta
determinar o código de país da UWB usando as seguintes fontes (listadas em ordem de
prioridade). O framework UWB para na primeira origem em que o código do país é
determinado.
- Substituir o código do país: o código do país é forçado por um comando de shell adb (teste local ou automatizado).
- Código de país de telefonia: código de país recuperado por celular. Se houver vários cartões SIM que retornarem códigos diferentes, o código do país escolhido não será determinístico.
- Código do país do Wi-Fi: código do país recuperado pelo Wi-Fi (80211.ad).
- Último código de país de telefonia conhecido: o último código de país conhecido recuperado pelo celular. Se houver vários chips que retornam códigos diferentes, o código de país escolhido não será determinístico.
- Código do país do local: código do país recuperado do provedor de localização combinada
LocationManager. - Código de país padrão do OEM: código do país definido pelo fabricante do dispositivo.
Se o framework UWB não conseguir determinar um código de país UWB, ele vai chamar o
comando UCI ANDROID_SET_COUNTRY_CODE com um valor de
DEFAULT_COUNTRY_CODE ("00") e notificar os apps UWB de que
o estado da pilha UWB é DISABLED. Depois, quando o framework de UWB conseguir
determinar um
código de país válido, ele vai configurar o novo código de país usando o
comando ANDROID_SET_COUNTRY_CODE e notificar os apps de UWB de que a pilha UWB
é READY.
Se a UWB não puder ser usada
devido às regulamentações locais de um país, o controlador de UWB vai retornar o
código de status STATUS_CODE_ANDROID_REGULATION_UWB_OFF. O framework UWB notifica
os apps UWB de que o estado da pilha UWB é DISABLED.
Quando um usuário viaja para outro país, o framework 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 do UWB no
novo país), isso pode levar a uma mudança no estado da pilha UWB.
Formato de comando definido pela especificação FIRA UCI
Para saber o formato dos pacotes de controle da UCI, consulte a seção 4.4.2 da especificação da UCI.
Controle de versões da 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. O framework usa esses comandos para buscar a
versão da UCI do dispositivo e mudar o comportamento de acordo com ela.
Lista de rascunhos de respostas automáticas compatíveis com o módulo da UWB
Os seguintes rascunhos de CRs para FiRa 2.0 têm suporte do módulo UWB, versão #330810000:
Interface do UCI do Android (parte do fornecedor do 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 exclusivamente para uso do fornecedor. A pilha UWB do AOSP usa alguns desses GIDs e OIDs do fornecedor para comandos específicos do Android que não são definidos na especificação. Para mais 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.
Controle de versões da interface do fornecedor
Os fornecedores de UWB precisam expor a versão do pacote HAL
android.hardware.uwb.fira_android com suporte no dispositivo usando
IUwbChip.getSupportedAndroidUciVersion(). O framework usa essas
informações de versionamento para processar 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 OEMs do Android.
| GID | OID | Definição |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Usado pelo comando e pela resposta para receber estatísticas relacionadas à energia do UWB.
Suporte apenas se
UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY
estiver definido como 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Usado para definir o código de país regulamentar atual (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 de país ISO-3166. Um valor de |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Usado pela notificação para receber estatísticas de diagnóstico de alcance de UWB.
Suporte apenas se
UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS for definido
como 1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Reservado para uso do OEM. |
Extensões do fornecedor para mensagens definidas pela especificação do 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]
Confira abaixo os valores de comprimento de tipo (TLVs) definidos pela pilha do AOSP na
parte reservada do fornecedor dos TLVs no APP_CONFIG:
- GID: 0001b (grupo de configuração da 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 das mensagens de configuração de sessão de 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 for definida
como 0xF0. Suporte disponível apenas se o
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 a geração de relatórios de diagnóstico.
Configure esse 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. Essa máscara de bits tem 1 byte no Android 14 ou mais recente e 4 bytes no Android 13 ou versões anteriores. Configure esse parâmetro somente quando o
Definições de bits:
|
CORE_GET_CAPS_INFO_RSP
Confira abaixo os TLVs definidos pela pilha AOSP na parte reservada
do fornecedor dos TLVs em CAPS_INFO:
- GID: 0000b (grupo principal do UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
A tabela a seguir lista os parâmetros das mensagens de recursos do 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 que indica suporte à consulta de estatísticas de energia. Valores:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | Valor de 1 byte que indica suporte para o recurso de intertravamento de antena. Valores:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Valor de 4 bytes que indica o intervalo de alcance mínimo compatível em milissegundos. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | Máscara de bits de 4 bytes que indica os valores
RANGE_DATA_NTF_CONFIG compatíveis.
Bitmask em que cada bit corresponde a valores usados em
RANGE_DATA_NTF_CONFIG em SET_APP_CFG_CMD. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | Valor de 1 byte que indica o suporte a relatórios RSSI. Valores:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | Valor de 1 byte que indica o suporte para 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 quatro bytes indicando o número máximo aceito de sessões de alcance FiRa. |
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 abaixo os códigos de status no espaço do fornecedor. Eles são retornados nas
respostas do 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 um 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 medição atual não pode ser iniciada devido a regulamentações do UWB. |
Código do motivo da alteração de estado em SESSION_STATUS_NTF
Confira a seguir 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. Essa notificação
é enviada pelo UWBS quando o estado de uma sessão de detecção 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 foi alterado porque o canal configurado não oferece suporte ao posicionamento de AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
O estado da sessão mudou devido a um conflito com outras sessões de alcance CCC ou FiRa. |
REASON_REGULATION_UWB_OFF |
0x82 |
O estado da sessão foi alterado porque a UWB precisa ser desativada por um motivo regulamentar. |