Стек AOSP для сверхширокополосной связи (UWB) использует определенный в FiRa интерфейс UCI в качестве поверхности HAL. Интерфейс HAL использует непрозрачный канал ( IUwbChip::sendUciMessage() и IUwbClientCallback::onUciMessage() ) для отправки и получения команд, ответов и уведомлений интерфейса команд UWB (UCI). Все производители Android-устройств с поддержкой UWB должны поддерживать все сообщения, определенные в спецификации FiRa. Фреймворк UWB обратно совместим и работает с любой версией UCI, реализованной производителем UWB на устройстве. Поскольку фреймворк AOSP UWB является модулем , он также может выборочно добавлять поддержку утвержденных запросов на изменения (CR) из черновых спецификаций UCI, предназначенных для основных релизов стандартов FiRa. Любые реализованные черновые запросы на изменения могут быть изменены.
Определение интерфейса
Интерфейс UWB HAL определяется с использованием стабильной версии AIDL . Основной интерфейс использует пакет android.hardware.uwb .
Ниже представлены два основных интерфейса из пакета 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);
}
HAL call flow from UWB framework
На следующих изображениях показана последовательность вызовов из среды UWB для процессов инициализации стека UWB, деинициализации стека UWB, а также запуска и остановки сеанса UWB.
Рисунок 1. Схема выполнения вызова инициализации стека UWB (переключение UWB включено).
Рисунок 2. Схема вызова деинициализации стека UWB (переключение UWB выключено).
Рисунок 3. Схема запуска/остановки сеанса UWB.
Конфигурация кода страны UWB
Как показано на рисунке 1, платформа UWB настраивает код страны UWB во время инициализации стека UWB с помощью команды UCI в пространстве поставщика ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ). Платформа UWB пытается определить код страны UWB, используя следующие источники (перечислены в порядке приоритета). Платформа UWB останавливается на первом источнике, где определяется код страны.
- Переопределение кода страны: код страны принудительно устанавливается с помощью команды adb shell (локально или при автоматическом тестировании).
- Код страны для телефонной связи: код страны, полученный через сотовую связь. Если несколько SIM-карт возвращают разные коды, выбор кода страны будет непредсказуемым.
- Код страны Wi-Fi: Код страны получен через Wi-Fi (80211.ad).
- Последний известный код страны для телефонной связи: последний известный код страны, полученный через сотовую связь. Если несколько SIM-карт возвращают разные коды, выбор кода страны будет непредсказуемым.
- Код страны местоположения: Код страны, полученный из объединенного поставщика местоположения
LocationManager. - Код страны по умолчанию от производителя: код страны, устанавливаемый производителем устройства.
Если платформа UWB не может определить код страны UWB, она вызывает команду UCI ANDROID_SET_COUNTRY_CODE со значением DEFAULT_COUNTRY_CODE ("00") и уведомляет приложения UWB о том, что состояние стека UWB — DISABLED . Позже, когда платформа UWB сможет определить действительный код страны, она настраивает новый код страны с помощью команды ANDROID_SET_COUNTRY_CODE и уведомляет приложения UWB о том, что стек UWB — READY .
Если использование UWB невозможно из-за местных правил в стране, контроллер UWB возвращает код состояния STATUS_CODE_ANDROID_REGULATION_UWB_OFF . Затем платформа UWB уведомляет приложения UWB о том, что состояние стека UWB — DISABLED .
Когда пользователь перемещается в другую страну, платформа UWB настраивает новый код страны с помощью команды UCI ANDROID_SET_COUNTRY_CODE . В зависимости от кода состояния, возвращаемого контроллером UWB (на основе правил UWB в новой стране), это может привести к изменению состояния стека UWB.
Формат команд, определенный спецификацией FIRA UCI
Формат управляющих пакетов UCI описан в разделе 4.4.2 спецификации UCI .
Версионирование интерфейса
Спецификация UCI позволяет производителям UWB-устройств раскрывать версию стека UCI, реализованного устройством, с помощью команд UCI_GET_DEVICE_INFO_RSP и UCI_GET_CAPS_INFO_RSP . Платформа использует эти команды для получения версии UCI устройства и соответствующего изменения его поведения.
Список черновых запросов на изменение (CR), поддерживаемых модулем UWB.
Следующие черновые запросы на изменения (CR) для FiRa 2.0 поддерживаются модулем UWB версии #330810000:
Интерфейс Android UCI (часть, предоставленная производителем FiRa)
Спецификация UCI определяет набор идентификаторов групп (GID) и идентификаторов кодов операций (OID) для всех сообщений, определенных спецификацией. Спецификация также резервирует набор GID, предназначенных исключительно для использования поставщиками. Стек AOSP UWB использует некоторые из этих GID и OID поставщиков для команд, специфичных для Android, которые не определены в спецификации. Подробности см. в разделе 8.4 спецификации UCI .
Эти сообщения от поставщиков, используемые Android, определены в пакете HAL android.hardware.uwb.fira_android .
Версионирование интерфейса поставщика
Производители UWB-устройств должны предоставлять информацию о поддерживаемой на устройстве версии пакета HAL android.hardware.uwb.fira_android через IUwbChip.getSupportedAndroidUciVersion() . Фреймворк использует эту информацию о версиях для обеспечения обратной совместимости.
Список идентификаторов GID и OID Android
В следующей таблице перечислены GID и OID для Android. GID 0xE и 0xF зарезервированы для использования производителями Android-устройств.
| ГИД | ОИД | Определение |
|---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Используется командой и ответом для получения статистики, связанной с энергопотреблением UWB. Поддерживается только в том случае, если для UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY установлено значение 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Используется для установки текущего нормативного кода страны (определяется с помощью SIM-карты или Wi-Fi, либо жестко задается производителем оборудования). Код страны передается в виде 2-байтового значения, соответствующего коду страны ISO-3166. Значение | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Используется уведомлением для получения диагностической статистики UWB-измерений. Поддерживается только в том случае, если для UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS установлено значение 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Предназначено для использования производителями оригинального оборудования (OEM). |
Расширения поставщика для сообщений, определенных в спецификации UCI.
В этом разделе подробно описываются расширения от поставщиков для сообщений, определенных в спецификации UCI.
SESSION_SET_APP_CONFIG_[CMD|RSP] и SESSION_GET_APP_CONFIG_[CMD|RSP]
Ниже приведены значения длины типов (TLV), определенные стеком AOSP в зарезервированной поставщиком части TLV в APP_CONFIG :
- GID: 0001b (Группа конфигурации UWB-сессии)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
В таблице ниже перечислены параметры сообщений конфигурации UWB-сессии.
| Имя параметра | Длина (октеты) | Ярлык (IDs) | Версия интерфейса поставщика | Описание |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Коэффициент чередования, если AOA_RESULT_REQ установлено в 0xF0 . Поддерживается только если UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING установлено в 1 . |
NB_OF_AZIMUTH_MEASUREMENTS | 1 | 0xE4 | 1 | |
NB_OF_ELEVATION_MEASUREMENTS | 1 | 0xE5 | 1 | |
ENABLE_DIAGNOSTICS | 1 | 0xE8 | 2 | Однобайтовое значение для включения или отключения диагностической отчетности. Настраивайте этот параметр только в том случае, если Ценности:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 или 4 | 0xE9 | 2 | Битовая маска размером 1 или 4 байта используется для настройки диагностических отчетов. В Android 14 и выше эта битовая маска составляет 1 байт, а в Android 13 и ниже — 4 байта. Настраивайте этот параметр только в том случае, если Определения битов:
|
CORE_GET_CAPS_INFO_RSP
Ниже приведены TLV-файлы, определенные стеком AOSP в зарезервированной поставщиком части TLV-файлов в CAPS_INFO :
- GID: 0000b (группа ядра UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
В таблице ниже перечислены параметры сообщений, описывающих возможности UWB.
| Имя параметра | Длина (октеты) | Ярлык (IDs) | Версия интерфейса поставщика | Описание |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Однобайтовое значение, указывающее на поддержку запроса статистики энергопотребления. Ценности:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Однобайтовое значение, указывающее на поддержку функции чередования антенн. Ценности:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | 4-байтовое значение, указывающее поддерживаемый минимальный интервал измерения в миллисекундах. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | 4-байтовая битовая маска, указывающая поддерживаемые значения RANGE_DATA_NTF_CONFIG . Битовая маска, где каждый бит соответствует значениям, используемым в RANGE_DATA_NTF_CONFIG в SET_APP_CFG_CMD . |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | Однобайтовое значение, указывающее на поддержку передачи данных по уровню сигнала RSSI. Ценности:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Однобайтовое значение, указывающее на поддержку формирования диагностических отчетов. Ценности:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | 4-байтовое значение, указывающее поддерживаемую минимальную продолжительность слота в RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | 4-байтовое значение, указывающее максимальное количество поддерживаемых сеансов измерения расстояния FiRa. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | Двухбайтовая битовая маска, указывающая каналы, поддерживающие AoA. Каждая Ценности:
|
Коды состояния
Ниже приведены коды состояния в пространстве поставщика. Они возвращаются в ответах UCI (например, SESSION_START_RSP ) подсистемой UWB (UWBS).
| Код состояния | Ценить | Описание |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Код состояния возвращается, когда текущая сессия измерения расстояния не может быть запущена из-за конфликта с другими сессиями измерения расстояния CCC или FiRa. |
STATUS_REGULATION_UWB_OFF | 0x53 | Код состояния возвращается, когда текущая сессия измерения расстояния не может быть запущена по причинам, связанным с требованиями нормативных документов UWB. |
Код причины изменения состояния в SESSION_STATUS_NTF
Ниже приведены коды причин изменения состояния, определенные в пространстве поставщика для поля статуса, возвращаемого UWBS в SESSION_STATUS_NTF . Это уведомление отправляется UWBS при изменении состояния сеанса измерения расстояния (например, с ACTIVE на IDLE ).
| код причины изменения состояния | Ценить | Описание |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | Состояние сессии изменилось, поскольку настроенный канал не поддерживает определение угла прихода сигнала (AoA). |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | Состояние сессии изменилось из-за конфликта с другими сессиями определения расстояния CCC или FiRa. |
REASON_REGULATION_UWB_OFF | 0x82 | Состояние сессии изменилось, поскольку технология UWB должна быть отключена по нормативным требованиям. |