Interfaz de la HAL de UWB

La pila de banda ultraancha (UWB) de AOSP usa la interfaz UCI definida por FiRa como la superficie de HAL. La interfaz de HAL usa un canal opaco (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 de 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 UCI que implemente el proveedor de UWB en el dispositivo. Debido a que el framework de UWB de AOSP es un módulo, también puede agregar de forma selectiva compatibilidad con solicitudes de cambios (CR) aprobadas de las especificaciones de UCI en borrador orientadas a las versiones principales de los estándares FiRa. Cualquier borrador de CR implementado está sujeto a cambios.

Definición de la interfaz

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

Las siguientes son 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 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 de la pila de UWB, 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 (activado el botón de activación de UWB)

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

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 de espacio del proveedor ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1). El framework de UWB intenta determinar el código de país de UWB con las siguientes fuentes (enumeradas 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: Es el 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 recuperado a través de un teléfono celular. Si hay varias SIM que muestran códigos diferentes, el código de país elegido es no determinista.
3. Código de país de Wi-Fi: 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 conocido que se recuperó a través de un teléfono celular. Si hay varias SIM que muestran códigos diferentes, el código de país elegido es no determinista.
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 que establece el fabricante del dispositivo.

Si el framework de UWB no puede determinar un código de país de UWB, llama al comando UCI ANDROID_SET_COUNTRY_CODE 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 puede determinar un código de país válido, configura el nuevo código de país con el comando ANDROID_SET_COUNTRY_CODE y notifica a las apps de UWB que la pila de UWB es READY.

Si no se puede usar UWB debido a las reglamentaciones locales de un país, el controlador de UWB muestra 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 otro país, el framework de UWB configura un código de país nuevo con el comando UCI ANDROID_SET_COUNTRY_CODE. Según el código de estado que devuelve el controlador UWB (según las reglamentaciones de UWB del país nuevo), esto podría provocar un cambio en el estado de la pila de UWB.

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

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

Control de versiones de la interfaz

La especificación de UCI permite que los proveedores de UWB expongan la versión de la pila de UCI que implementa 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 UCI del dispositivo y cambiar su comportamiento según corresponda.

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

Los siguientes borradores de CR para FiRa 2.0 son compatibles con la versión #330810000 del módulo UWB:

• CR 287
• Compatibilidad con la API de SUS y la especificación de UCI para los requisitos de la interfaz de la llave digital de CCC

Interfaz de UCI de Android (porción del proveedor de FiRa)

La especificación de 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 GIDs exclusivamente para el uso de los proveedores. La pila de UWB de AOSP usa algunos de estos OID y GID de proveedores para comandos específicos de Android que no se definen en la especificación. Para obtener más información, consulta la sección 8.4 de la especificación de UCI.

Estos mensajes del proveedor que usa Android se definen en el paquete HAL de 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 que se admite en el dispositivo a través de IUwbChip.getSupportedAndroidUciVersion(). El framework usa esta información de control de versiones para controlar la retrocompatibilidad.

Lista de GID y OID de Android

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

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

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

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

Los siguientes son los valores de longitud de tipo (TLV) definidos por la pila de AOSP en la parte reservada del 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

Los siguientes son los TLV que define la pila de AOSP en la parte reservada del 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 capacidades de UWB.

Códigos de estado

Los siguientes son los códigos de estado en el espacio del proveedor. El subsistema UWB (UWBS) las muestra en las respuestas de UCI (como SESSION_START_RSP).

Código de motivo de cambio de estado en SESSION_STATUS_NTF

Los siguientes son los códigos de motivos de cambio de estado definidos en el espacio del proveedor para el campo de estado que muestra un UWBS en SESSION_STATUS_NTF. La UWBS envía esta notificación cuando cambia el estado de una sesión de medición de rango (por ejemplo, de ACTIVE a IDLE).