Interfaz de la HAL de UWB

La pila de banda ultraancha (UWB) del AOSP usa la interfaz de UCI definida por FiRa como la superficie de la HAL. La interfaz HAL usa una canalización opaca (IUwbChip::sendUciMessage() y IUwbClientCallback::onUciMessage()) para enviar y recibir comandos, respuestas y notificaciones de la interfaz de comandos de UWB (UCI). Todos los proveedores de UWB para Android deben admitir todos los mensajes definidos en la especificación de FiRa. El framework de UWB es retrocompatible y funciona con cualquier versión de la UCI implementada por el proveedor de UWB en el dispositivo. Dado que el framework de UWB del AOSP es un módulo, también puede agregar de forma selectiva compatibilidad con las solicitudes de cambio (CR) aprobadas de las especificaciones de UCI en borrador destinadas a las principales versiones de los estándares de FiRa. Las CR de borrador que se implementen están sujetas a cambios.

Definición de la interfaz

La interfaz de la HAL de UWB se define con AIDL estable. La interfaz principal usa el paquete android.hardware.uwb.

A continuación, se muestran las dos interfaces principales del paquete 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);

}

Flujo de llamadas de la HAL desde el framework de UWB

En las siguientes imágenes, se ilustra el flujo de llamadas del framework de UWB para la inicialización y la desinicialización de la pila de UWB, y los procesos de inicio y detención de la sesión de UWB.

Figura 1: Flujo de llamadas de inicialización de la pila de UWB (activación de UWB)

Figura 2: Flujo de llamadas de desinicialización de la pila de UWB (palanca de UWB desactivada)

Figura 3: Flujo de inicio y detención de la sesión de UWB

Configuración del código de país de UWB

Como se muestra en la Figura 1, el framework de UWB configura el código de país de UWB durante la inicialización de la pila de UWB con el comando UCI ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) del espacio del proveedor. El framework de UWB intenta determinar el código de país de UWB con las siguientes fuentes (que se enumeran en orden de prioridad). El framework de UWB se detiene en la primera fuente en la que se determina el código de país.

1. Anulación del código de país: Código de país forzado a través de un comando de shell de adb (pruebas locales o automatizadas).
2. Código de país de telefonía: Es el código de país que se recupera a través de la red celular. Si hay varias SIM que devuelven códigos diferentes, el código de país elegido no es determinístico.
3. Código de país de Wi-Fi: Es el código de país recuperado a través de Wi-Fi (80211.ad).
4. Último código de país de telefonía conocido: Es el último código de país recuperado a través de la red celular. Si hay varias SIM que devuelven códigos diferentes, el código de país elegido no es determinístico.
5. Código de país de la ubicación: Es el código de país recuperado del proveedor de ubicación combinada LocationManager.
6. Código de país predeterminado del OEM: Es el código de país establecido por el fabricante del dispositivo.

Si el framework de UWB no puede determinar un código de país de UWB, llama al comando ANDROID_SET_COUNTRY_CODE de la UCI con un valor de DEFAULT_COUNTRY_CODE ("00") y notifica a las apps de UWB que el estado de la pila de UWB es DISABLED. Más adelante, cuando el framework de UWB pueda determinar un código de país válido, configurará el nuevo código de país con el comando ANDROID_SET_COUNTRY_CODE y notificará a las apps de UWB que la pila de UWB es READY.

Si no se puede usar la UWB debido a las reglamentaciones locales de un país, el controlador de UWB devuelve el código de estado STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Luego, el framework de UWB notifica a las apps de UWB que el estado de la pila de UWB es DISABLED.

Cuando un usuario viaja a un país diferente, el framework de UWB configura un nuevo código de país con el comando de UCI ANDROID_SET_COUNTRY_CODE. Según el código de estado que devuelva el controlador de UWB (en función de las reglamentaciones de UWB del país nuevo), esto podría generar un cambio en el estado de la pila de UWB.

Formato de comando definido por la especificación de la UCI de la FIRA

Para conocer el formato de los paquetes de control de la UCI, consulta la sección 4.4.2 de la especificación de la UCI.

Control de versiones de la interfaz

La especificación de la UCI permite que los proveedores de UWB expongan la versión de la pila de la UCI implementada por el dispositivo con los comandos UCI_GET_DEVICE_INFO_RSP y UCI_GET_CAPS_INFO_RSP. El framework usa estos comandos para recuperar la versión de la UCI del dispositivo y cambiar su comportamiento según corresponda.

Lista de CR de borrador compatibles con el módulo de UWB

La versión #330810000 del módulo UWB admite los siguientes CRs preliminares para FiRa 2.0:

• CR 287
• API de SUS y compatibilidad con especificaciones de UCI para los requisitos de la interfaz de llave digital de CCC

Interfaz de UCI de Android (parte del proveedor de FiRa)

La especificación de la UCI define un conjunto de identificadores de grupo (GID) y de identificadores de opcode (OID) para todos los mensajes definidos en la especificación. La especificación también reserva un conjunto de GID exclusivamente para el uso del proveedor. La pila de UWB del AOSP usa algunos de estos GID y OID del proveedor para comandos específicos de Android que no se definen en la especificación. Para obtener más detalles, consulta la sección 8.4 de la especificación de la UCI.

Estos mensajes del proveedor que usa Android se definen en el paquete HAL android.hardware.uwb.fira_android.

Control de versiones de la interfaz del proveedor

Los proveedores de UWB deben exponer la versión del paquete de HAL de android.hardware.uwb.fira_android compatible con el dispositivo a través de IUwbChip.getSupportedAndroidUciVersion(). El framework usa esta información de versiones para controlar la retrocompatibilidad.

Lista de GIDs y OIDs de Android

En la siguiente tabla, se enumeran los GID y OID para Android. Los GID 0xE y 0xF están reservados para que los usen los OEM de Android.

Extensiones de proveedores para mensajes definidos en la especificación de la UCI

En esta sección, se describen los detalles de las extensiones del proveedor para los mensajes definidos en la especificación de UCI.

SESSION_SET_APP_CONFIG_[CMD|RSP] y SESSION_GET_APP_CONFIG_[CMD|RSP]

A continuación, se indican los valores de longitud del tipo (TLV) definidos por la pila del AOSP en la parte reservada para el proveedor de los TLV en APP_CONFIG:

• GID: 0001b (grupo de configuración de la sesión de UWB)
• OID: 000011b (SESSION_SET_APP_CONFIG_CMD)
• OID: 000100b (SESSION_GET_APP_CONFIG_CMD)

En la siguiente tabla, se enumeran los parámetros de los mensajes de configuración de la sesión de UWB.

CORE_GET_CAPS_INFO_RSP

A continuación, se indican los TLV definidos por la pila de AOSP en la porción reservada para el proveedor de los TLV en CAPS_INFO:

• GID: 0000b (grupo principal de UWB)
• OID: 000011b (CORE_GET_CAPS_INFO_RSP)

En la siguiente tabla, se enumeran los parámetros de los mensajes de capacidad de UWB.

Códigos de estado

A continuación, se indican los códigos de estado en el espacio del proveedor. El subsistema de UWB (UWBS) las devuelve en las respuestas de la UCI (como SESSION_START_RSP).

Código de motivo de cambio de estado en SESSION_STATUS_NTF

A continuación, se indican los códigos de motivos de cambio de estado definidos en el espacio del proveedor para el campo de estado que devuelve un UWBS en SESSION_STATUS_NTF. El UWBS envía esta notificación cuando cambia el estado de una sesión de medición de distancia (por ejemplo, de ACTIVE a IDLE).