Interface de HAL para UWB

A pilha de banda ultralarga (UWB) do AOSP usa a interface UCI definida pela FiRa como a superfície HAL. A interface HAL usa um pipe 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 na especificação da FiRa. O framework UWB é compatível com versões anteriores e funciona com qualquer versão da UCI implementada pelo fornecedor de UWB no dispositivo. Como a estrutura UWB do AOSP é um módulo, ela também pode adicionar seletivamente suporte para solicitações de mudança (CRs, na sigla em inglês) aprovadas de especificações UCI provisórias destinadas a grandes lançamentos de padrões da FiRa. Qualquer CR em rascunho implementada está sujeita a mudanças.

Definição de interface

A interface HAL para UWB é definida usando a AIDL estável. A interface principal usa o pacote android.hardware.uwb.

Estas são as duas principais interfaces no 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 da HAL do framework UWB

As imagens a seguir ilustram o fluxo de chamadas do framework UWB para a inicialização e desinicialização da pilha UWB e os processos de início e interrupção da sessão UWB.

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

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

Figura 3. Fluxo de início/parada de sessão de UWB

Configuração do código do país para UWB

Conforme mostrado na Figura 1, o framework UWB configura o código do 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). O framework UWB tenta determinar o código do país UWB usando as seguintes fontes (listadas em ordem de prioridade). O framework UWB para na primeira fonte em que o código do país é determinado.

1. Substituir código do país: código do país forçado por um comando adb shell (teste local ou automatizado).
2. Código do país da telefonia: código do país recuperado por celular. Se houver vários SIMs que retornam códigos diferentes, o código do país escolhido será não determinístico.
3. Código do país do Wi-Fi: código do país recuperado pelo Wi-Fi (80211.ad).
4. Último código do país de telefonia conhecido: o último código do país recuperado por celular. Se houver vários chips que retornam 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 combinada LocationManager.
6. Código do país padrão do OEM: código do país definido pelo fabricante do dispositivo.

Se a estrutura UWB não conseguir determinar um código de país UWB, ela 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. Mais tarde, quando a estrutura UWB conseguir determinar um código de país válido, ela vai configurar o novo código usando o comando ANDROID_SET_COUNTRY_CODE e notificar os apps UWB de que a pilha UWB está READY.

Se a UWB não puder ser usada devido a regulamentações locais em um país, o controlador UWB vai 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 um país diferente, a estrutura UWB configura um novo código de país usando o comando ANDROID_SET_COUNTRY_CODE UCI. Dependendo do código de status retornado pelo controlador UWB (com base nas regulamentações de UWB no novo país), isso pode levar a uma mudança no estado da pilha UWB.

Formato de comando definido pela especificação UCI da FIRA

Para saber mais sobre 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 da UCI permite que os fornecedores de UWB exponham a versão da pilha da 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 CRs de rascunho compatíveis com o módulo UWB

As seguintes CRs de rascunho para FiRa 2.0 são compatíveis com a versão #330810000 do módulo UWB:

• CR 287
• Suporte a API SUS e especificação UCI para requisitos de interface de chave digital CCC

Interface UCI do Android (parte do fornecedor da FiRa)

A especificação UCI define um conjunto de identificadores de grupo (GIDs) e identificadores de opcode (OIDs) para todas as mensagens definidas na 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 de fornecedores para comandos específicos do Android que não estã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 compatível com o dispositivo usando IUwbChip.getSupportedAndroidUciVersion(). O framework 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 de OEMs do Android.

Extensões do fornecedor para mensagens definidas na especificação da 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 do tipo (TLVs, na sigla em inglês) definidos pela pilha do AOSP na parte reservada pelo 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 de sessão de UWB.

CORE_GET_CAPS_INFO_RSP

Estes são os TLVs definidos pela pilha do AOSP na parte reservada ao fornecedor 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 de UWB.

Códigos de status

Confira abaixo os códigos de status no espaço do fornecedor. Elas são retornadas em respostas da UCI (como SESSION_START_RSP) pelo subsistema UWB (UWBS).

Código do motivo da mudança 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. Essa notificação é enviada pelo UWBS quando o estado de uma sessão de alcance muda (por exemplo, de ACTIVE para IDLE).