Interface de HAL para UWB

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.

Inicialização da pilha UWB

Figura 1. Fluxo de chamadas de inicialização de pilha UWB (alternância de UWB ativada)

Desinicialização da pilha UWB

Figura 2. Fluxo de chamadas de desinicialização da pilha UWB (botão UWB desativado)

Início e interrupção da sessão de UWB

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.

  1. Substituir código do país: código do país forçado por meio de um comando adb shell (testes locais ou automatizados).
  2. 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.
  3. Código do país do Wi-Fi: o código do país extraído pelo Wi-Fi (80211.ad).
  4. Ú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.
  5. Código de país do local: código do país extraído do LocationManager provedor de localização combinada.
  6. 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:

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 00 é usado para indicar que o código do país é desconhecido.

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 CORE_GET_CAPS_INFO_RSP retorna SUPPORTED_DIAGNOSTICS com um valor de 1: indica que o recurso de relatórios de diagnóstico está suporte.

Valores:

  • 1: recurso ativado
  • 0: recurso desativado

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 CORE_GET_CAPS_INFO_RSP SUPPORTED_DIAGNOSTICS com um valor de 1 indicando que há suporte para o recurso de relatórios de diagnóstico.

Definições de bit:

  • b0 (0x01): ativar campos RSSI
  • b1 (0x02): ativar campos de AoA
  • b2 (0x04): ativar campos do CIR

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:

  • 1: recurso compatível
  • 0: recurso incompatível
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Valor de 1 byte indicando suporte para a intercalação de antenas .

Valores:

  • 1: recurso compatível
  • 0: recurso incompatível
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:

  • 1: recurso compatível
  • 0: recurso incompatível
SUPPORTED_DIAGNOSTICS 1 0xE7 2

Valor de 1 byte indicando o suporte de relatórios de diagnóstico.

Valores:

  • 1: recurso compatível
  • 0: recurso incompatível
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 1 no bitmask corresponde a um canal UWB específico.

Valores:

  • 0x01: canal 5 compatível
  • 0x02: canal 6 compatível
  • 0x04: canal 8 compatível
  • 0x08: canal 9 compatível
  • 0x10: canal 10 compatível
  • 0x20: canal 12 compatível
  • 0x40: canal 13 compatível
  • 0x80: canal 14 compatível

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.