Interface UWB HAL

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.

Inicialização da pilha UWB

Figura 1. Fluxo de chamada de inicialização da pilha UWB (ativação UWB)

Desinicialização da pilha UWB

Figura 2. Fluxo de chamada de desinicialização da pilha UWB (desativação de UWB)

Início e parada da sessão 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.

  1. Substituir código do país: Código do país forçado por meio de um comando shell adb (teste local ou automatizado).
  2. 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.
  3. Código do país Wi-Fi: Código do país recuperado por Wi-Fi (80211.ad).
  4. Ú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.
  5. Código do país do local: código do país recuperado do provedor de localização fundida LocationManager .
  6. 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 00 é usado para indicar que o código do país é desconhecido.

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 CORE_GET_CAPS_INFO_RSP retornar SUPPORTED_DIAGNOSTICS com um valor 1 , indicando que o recurso de relatório de diagnóstico é suportado.

Valores:

  • 1 : Recurso habilitado
  • 0 : Recurso desabilitado

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 CORE_GET_CAPS_INFO_RSP retornar SUPPORTED_DIAGNOSTICS com um valor 1 , indicando que o recurso de relatório de diagnóstico é suportado.

Definições de bits:

  • b0 (0x01) : Ativa campos RSSI
  • b1 (0x02) : Ativa campos AoA
  • b2 (0x04) : Ativa campos CIR

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:

  • 1 : Recurso suportado
  • 0 : Recurso não suportado
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Valor de 1 byte indicando suporte para o recurso de intercalação de antena.

Valores:

  • 1 : Recurso suportado
  • 0 : Recurso não suportado
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:

  • 1 : Recurso suportado
  • 0 : Recurso não suportado
SUPPORTED_DIAGNOSTICS 1 0xE7 2

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

Valores:

  • 1 : Recurso suportado
  • 0 : Recurso não suportado
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 1 na máscara de bits corresponde a um canal UWB específico.

Valores:

  • 0x01 : Canal 5 suportado
  • 0x02 : Canal 6 suportado
  • 0x04 : Canal 8 suportado
  • 0x08 : Canal 9 suportado
  • 0x10 : Canal 10 suportado
  • 0x20 : Canal 12 suportado
  • 0x40 : Canal 13 suportado
  • 0x80 : Canal 14 suportado

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.