Стек сверхширокополосной связи (UWB) AOSP использует интерфейс UCI, определенный FiRa, в качестве поверхности HAL. Интерфейс HAL использует непрозрачный канал ( IUwbChip::sendUciMessage() и IUwbClientCallback::onUciMessage() ) для отправки и получения команд, ответов и уведомлений командного интерфейса UWB (UCI). Все поставщики Android UWB должны поддерживать все сообщения, определенные спецификацией FiRa. Платформа UWB обратно совместима и работает с любой версией UCI, реализованной на устройстве поставщиком UWB. Поскольку структура AOSP UWB представляет собой модуль , она также может выборочно добавлять поддержку утвержденных запросов на изменения (CR) из проектов спецификаций UCI, предназначенных для основных выпусков стандартов FiRa. Любые реализованные проекты CR могут быть изменены.
Определение интерфейса
Интерфейс 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 из платформы UWB
Следующие изображения иллюстрируют поток вызовов из платформы 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 (локальное или автоматическое тестирование).
- Телефонный код страны: код страны, полученный через сотовую связь. Если имеется несколько SIM-карт, которые возвращают разные коды, выбранный код страны является недетерминированным.
- Код страны Wi-Fi: код страны, полученный через Wi-Fi (80211.ad).
- Последний известный телефонный код страны: последний известный код страны, полученный через сотовую связь. Если имеется несколько SIM-карт, которые возвращают разные коды, выбранный код страны является недетерминированным.
- Код страны местоположения: код страны, полученный от объединенного поставщика местоположений
LocationManager. - Код страны OEM по умолчанию: код страны, установленный производителем устройства.
Если платформа 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 настраивает новый код страны с помощью команды ANDROID_SET_COUNTRY_CODE UCI. В зависимости от кода состояния, возвращаемого контроллером СШП (в соответствии с правилами СШП в новой стране), это может привести к изменению состояния стека СШП.
Формат команды, определенный спецификацией FIRA UCI
Формат пакетов управления UCI см. в разделе 4.4.2 спецификации UCI .
Управление версиями интерфейса
Спецификация UCI позволяет поставщикам UWB предоставлять версию стека UCI, реализованную устройством, с помощью команд UCI_GET_DEVICE_INFO_RSP и UCI_GET_CAPS_INFO_RSP . Платформа использует эти команды для получения версии UCI устройства и соответствующего изменения его поведения.
Список проектов CR, поддерживаемых модулем СШП
Следующие проекты 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 зарезервированы для использования OEM-производителями Android.
| ГИД | OID | Определение |
|---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Используется командой и ответом для получения статистики, связанной с мощностью UWB. Поддерживается, только если для UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY установлено значение 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Используется для установки текущего нормативного кода страны (определяется с помощью SIM-карты или Wi-Fi или жестко запрограммирован OEM-производителем). Код страны отправляется в виде 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.
| Имя параметра | Длина (октеты) | Ярлык (идентификаторы) | Версия интерфейса поставщика | Описание |
|---|---|---|---|---|
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 | 1-байтовое значение для включения или отключения отчетов о диагностике. Настраивайте этот параметр только тогда, когда Ценности:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 или 4 | 0xE9 | 2 | 1-байтовая или 4-байтовая битовая маска для настройки отчетов о диагностике. Эта битовая маска имеет размер 1 байт в Android 14 или более поздней версии и 4 байта в Android 13 или более ранней версии. Настраивайте этот параметр только тогда, когда Определения битов:
|
CORE_GET_CAPS_INFO_RSP
Ниже приведены TLV, определенные стеком AOSP в зарезервированной поставщиком части TLV в CAPS_INFO :
- GID: 0000b (основная группа СШП)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
В следующей таблице перечислены параметры сообщений о возможностях UWB.
| Имя параметра | Длина (октеты) | Ярлык (идентификаторы) | Версия интерфейса поставщика | Описание |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Значение в 1 байт, указывающее поддержку запроса статистики энергопотребления. Ценности:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Значение в 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 | Значение в 1 байт, указывающее на поддержку отчетов RSSI. Ценности:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | 1-байтовое значение, указывающее на поддержку отчетов о диагностике. Ценности:
|
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 | 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 необходимо отключить по нормативным причинам. |