La pila de banda ultraancha (UWB) de AOSP usa la interfaz de UCI definida por FiRa como la superficie de HAL. La interfaz 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 por la especificación de FiRa. El framework de UWB es retrocompatible y funciona con cualquier versión de UWB implementada por 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 cambio aprobadas (CR) de borradores de especificaciones de la UCI segmentadas para 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 deinicialización de la pila de UWB y los procesos de inicio y detención de 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/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.
- 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).
- 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 no es determinista.
- Código de país de Wi-Fi: Código de país recuperado a través de Wi-Fi (80211.ad).
- Último código de país de telefonía conocido: Es el último código de país conocido que se recuperó mediante redes móviles. Si hay varias tarjetas SIM que muestran códigos diferentes, el código de país elegido no es determinista.
- Código de país de la ubicación: Es el código de país recuperado del proveedor de ubicación combinada
LocationManager. - 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 un país diferente, el framework de UWB configura un código de país nuevo con el comando de UCI ANDROID_SET_COUNTRY_CODE. Según el código de estado que muestre el controlador de UWB (según las reglamentaciones de UWB del país nuevo), esto puede provocar un cambio en el estado de la pila de UWB.
Formato de comando definido por especificación 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 UWB permite que los proveedores de UWB expongan la versión de la pila de UCI que implementa el dispositivo a través de 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 CR en borrador admitidas por el módulo de 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 GID reservados exclusivamente para el uso del proveedor. 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 HAL android.hardware.uwb.fira_android compatible con el dispositivo a través de IUwbChip.getSupportedAndroidUciVersion(). El framework usa esta información sobre el 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.
| GID | OID | Definición |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
El comando y la respuesta lo usan para obtener estadísticas relacionadas con la energía de UWB.
Solo se admite si UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY se establece como 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Se usa para establecer el código regulatorio de país actual (determinado mediante SIM o Wi-Fi, o codificado por el OEM). El código de país se envía como un valor de 2 bytes que corresponde al código de país ISO-3166. Se usa un valor de |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
La notificación lo usa para obtener estadísticas de diagnóstico de rango UWB.
Solo se admite si UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS se establece como 1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Reservado para uso del OEM. |
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 para los mensajes definidos por 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.
| Nombre del parámetro | Longitud (octetos) |
Etiqueta (IDs) |
Versión de la interfaz del proveedor | Descripción |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | Proporción de intercalación si AOA_RESULT_REQ se establece en 0xF0. Solo se admite si UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING se establece como 1. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | Es un valor de 1 byte para habilitar o inhabilitar los informes de diagnóstico.
Configura este parámetro solo cuando Valores:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 o 4 | 0xE9 |
2 | máscara de bits de 1 byte o 4 bytes para configurar los informes de diagnóstico. Esta máscara de bits es de 1 byte en Android 14 o versiones posteriores y de 4 bytes en Android 13 o versiones anteriores. Configura este parámetro solo cuando Definiciones de bits:
|
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 para los mensajes de capacidad de UWB.
| Nombre del parámetro | Longitud (octetos) |
Etiqueta (IDs) |
Versión de la interfaz del proveedor | Descripción |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | Valor de 1 byte que indica compatibilidad con la consulta de estadísticas de energía. Valores:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | Valor de 1 byte que indica la compatibilidad con la función de intercalación de antena. Valores:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Es un valor de 4 bytes que indica el intervalo de rango mínimo admitido en milisegundos. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | Máscara de bits de 4 bytes que indica los valores de RANGE_DATA_NTF_CONFIG compatibles.
Máscara de bits en la que cada bit corresponde a valores usados en RANGE_DATA_NTF_CONFIG en SET_APP_CFG_CMD. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | Es un valor de 1 byte que indica la compatibilidad con los informes de RSSI. Valores:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | Es un valor de 1 byte que indica la compatibilidad con los informes de diagnóstico. Valores:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | Es un valor de 4 bytes que indica la duración mínima del intervalo compatible en RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Es un valor de 4 bytes que indica la cantidad máxima admitida de sesiones de rango FiRa. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | Máscara de bits de 2 bytes para indicar los canales que admiten AoA. Cada Valores:
|
Códigos de estado
Los siguientes son los códigos de estado en el espacio del proveedor. El subsistema de UWB (UWBS) los muestra en las respuestas de UWB (como SESSION_START_RSP).
| Código de error | Valor | Descripción |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Código de estado que se muestra cuando no se puede iniciar la sesión de medición de rango actual debido a un conflicto con otras sesiones de medición de rango de CCC o FiRa. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Código de estado que se muestra cuando no se puede iniciar la sesión de medición de rango actual debido a motivos regulatorios de UWB. |
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 rango (por ejemplo, de ACTIVE a IDLE).
| Código de motivo del cambio de estado | Valor | Descripción |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
El estado de la sesión cambió porque el canal configurado no admite el rango de AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
El estado de la sesión cambió debido a un conflicto con otras sesiones de rango de CCC o FiRa. |
REASON_REGULATION_UWB_OFF |
0x82 |
El estado de la sesión cambió porque la UWB debe inhabilitarse por motivos regulatorios. |