La pila de banda ultra ancha (UWB) de AOSP utiliza la interfaz UCI definida por FiRa como superficie HAL. La interfaz HAL utiliza una tubería opaca ( IUwbChip::sendUciMessage() y IUwbClientCallback::onUciMessage() ) para enviar y recibir comandos, respuestas y notificaciones de la interfaz de comandos UWB (UCI). Todos los proveedores de Android UWB deben admitir todos los mensajes definidos por la especificación FiRa. El marco UWB es compatible con versiones anteriores y funciona con cualquier versión de UCI implementada por el proveedor de UWB en el dispositivo. Debido a que el marco AOSP UWB es un módulo , también puede agregar selectivamente soporte para solicitudes de cambio (CR) aprobadas a partir de borradores de especificaciones UCI destinadas a las principales versiones de estándares de FiRa. Cualquier borrador de CR implementado está sujeto a cambios.
Definición de interfaz
La interfaz UWB HAL se define utilizando AIDL estable . La interfaz principal utiliza 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 HAL desde el marco UWB
Las siguientes imágenes ilustran el flujo de llamadas desde el marco de trabajo 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 sesiones de UWB.
Figura 1. Flujo de llamadas de inicialización de la pila UWB (activación de UWB)
Figura 2. Flujo de llamadas de desinicialización de la pila UWB (desactivación de UWB)
Figura 3. Flujo de inicio/detención de sesión UWB
Configuración del código de país UWB
Como se muestra en la Figura 1, el marco UWB configura el código de país UWB durante la inicialización de la pila UWB utilizando el comando UCI del espacio del proveedor ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ). El marco UWB intenta determinar el código de país UWB utilizando las siguientes fuentes (enumeradas en orden de prioridad). El marco UWB se detiene en la primera fuente donde se determina el código de país.
- Anular código de país: código de país forzado mediante un comando adb shell (prueba local o automatizada).
- Código de país de telefonía: Código de país recuperado a través del celular. Si hay varias SIM que devuelven códigos diferentes, el código de país elegido no es determinista.
- Código de país 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: último código de país conocido recuperado a través del celular. Si hay varias SIM que devuelven códigos diferentes, el código de país elegido no es determinista.
- Código de país de ubicación: código de país recuperado del proveedor de ubicación fusionado
LocationManager. - Código de país predeterminado del OEM: código de país establecido por el fabricante del dispositivo.
Si el marco UWB no puede determinar un código de país UWB, llama al comando UCI ANDROID_SET_COUNTRY_CODE con un valor de DEFAULT_COUNTRY_CODE ("00") y notifica a las aplicaciones UWB que el estado de la pila UWB está DISABLED . Más adelante, cuando el marco UWB puede determinar un código de país válido, configura el nuevo código de país usando el comando ANDROID_SET_COUNTRY_CODE y notifica a las aplicaciones UWB que la pila UWB está READY .
Si no se puede utilizar UWB debido a las regulaciones locales de un país, el controlador UWB devuelve el código de estado STATUS_CODE_ANDROID_REGULATION_UWB_OFF . Luego, el marco UWB notifica a las aplicaciones UWB que el estado de la pila UWB está DISABLED .
Cuando un usuario viaja a un país diferente, el marco UWB configura un nuevo código de país usando el comando UCI ANDROID_SET_COUNTRY_CODE . Dependiendo del código de estado devuelto por el controlador UWB (según las regulaciones de UWB en el nuevo país), esto podría provocar un cambio en el estado de la pila de UWB.
Formato de comando definido por la especificación FIRA UCI
Para conocer el formato de los paquetes de control UCI, consulte la sección 4.4.2 de la especificación UCI .
Versionado de la interfaz
La especificación UCI permite a los proveedores de UWB exponer la versión de la pila UCI implementada por el dispositivo mediante los comandos UCI_GET_DEVICE_INFO_RSP y UCI_GET_CAPS_INFO_RSP . El marco utiliza estos comandos para obtener la versión UCI del dispositivo y cambiar su comportamiento en consecuencia.
Lista de proyectos de CR respaldados por el módulo UWB
Los siguientes borradores de CR para FiRa 2.0 son compatibles con la versión del módulo UWB #330810000:
Interfaz UCI de Android (parte del proveedor de FiRa)
La especificación UCI define un conjunto de identificadores de grupo (GID) e identificadores de código de operación (OID) para todos los mensajes definidos por la especificación. La especificación también reserva un conjunto de GID reservados exclusivamente para uso del proveedor. La pila AOSP UWB utiliza algunos de estos GID y OID de proveedores para comandos específicos de Android que no están definidos en la especificación. Para más detalles, consulte la sección 8.4 de la especificación UCI .
Estos mensajes de proveedores utilizados por 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 HAL android.hardware.uwb.fira_android compatible con el dispositivo a través de IUwbChip.getSupportedAndroidUciVersion() . El marco utiliza esta información de versiones para manejar la compatibilidad con versiones anteriores.
Lista de GID y OID de Android
La siguiente tabla enumera los GID y OID para Android. Los GID 0xE y 0xF están reservados para que los utilicen los OEM de Android.
| GID | OID | Definición |
|---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Utilizado por el comando y la respuesta para obtener estadísticas relacionadas con la energía UWB. Solo se admite si UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY está establecido en 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Se utiliza para configurar 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 correspondiente al código de país ISO-3166. Se utiliza un valor de | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Utilizado por la notificación para obtener estadísticas de diagnóstico de alcance UWB. Solo se admite si UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS está establecido en 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Reservado para uso OEM. |
Extensiones de proveedores a mensajes definidos por la especificación UCI
Esta sección describe detalles de las extensiones de proveedores para mensajes definidos por especificaciones 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 AOSP en la parte reservada por el proveedor de los TLV en APP_CONFIG :
- GID: 0001b (grupo de configuración de sesión UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
La siguiente tabla enumera los parámetros para los mensajes de configuración de sesión UWB.
| Nombre del parámetro | Longitud (octetos) | Etiqueta (identificaciones) | Versión de la interfaz del proveedor | Descripción |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Relación de entrelazado si AOA_RESULT_REQ se establece en 0xF0 . Solo se admite si UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING está establecido en 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 habilitar o deshabilitar los informes de diagnóstico. Configure este parámetro solo cuando Valores:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 o 4 | 0xE9 | 2 | Máscara de bits de 1 o 4 bytes para configurar informes de diagnóstico. Esta máscara de bits es de 1 byte en Android 14 o superior y de 4 bytes en Android 13 o inferior. Configure este parámetro solo cuando Definiciones de bits:
|
CORE_GET_CAPS_INFO_RSP
Los siguientes son los TLV definidos por la pila AOSP en la parte reservada por el proveedor de los TLV en CAPS_INFO :
- GID: 0000b (grupo principal UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
La siguiente tabla enumera los parámetros para los mensajes de capacidad UWB.
| Nombre del parámetro | Longitud (octetos) | Etiqueta (identificaciones) | 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 compatibilidad con la función de entrelazado de antena. Valores:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Valor de 4 bytes que indica el intervalo de alcance mínimo admitido en milisegundos. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Máscara de bits de 4 bytes que indica los valores RANGE_DATA_NTF_CONFIG admitidos. Máscara de bits donde cada bit corresponde a los valores utilizados en RANGE_DATA_NTF_CONFIG en SET_APP_CFG_CMD . |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | Valor de 1 byte que indica la compatibilidad con informes RSSI. Valores:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Valor de 1 byte que indica la compatibilidad con informes de diagnóstico. Valores:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | Valor de 4 bytes que indica la duración mínima de ranura admitida en RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | Valor de 4 bytes que indica el número máximo admitido de sesiones de alcance 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. Estos se devuelven en respuestas UCI (como SESSION_START_RSP ) por el subsistema UWB (UWBS).
| Código de estado | Valor | Descripción |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Código de estado devuelto cuando la sesión de alcance actual no se puede iniciar debido a un conflicto con otras sesiones de alcance de CCC o FiRa. |
STATUS_REGULATION_UWB_OFF | 0x53 | Código de estado devuelto cuando la sesión de alcance actual no se puede iniciar 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 motivo de cambio de estado definidos en el espacio del proveedor para el campo de estado devuelto por una UWBS en SESSION_STATUS_NTF . La UWBS envía esta notificación cuando el estado de una sesión de alcance cambia (por ejemplo, de ACTIVE a IDLE ).
| Código de motivo de 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 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 alcance de CCC o FiRa. |
REASON_REGULATION_UWB_OFF | 0x82 | El estado de la sesión cambió porque la UWB debe deshabilitarse por una razón regulatoria. |