СШП HAL-интерфейс

Стек сверхширокополосной связи (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.

Инициализация стека UWB

Рис. 1. Последовательность вызовов инициализации стека UWB (включение UWB)

Деинициализация стека UWB

Рис. 2. Последовательность вызовов деинициализации стека UWB (выключение UWB)

Начало и остановка сеанса UWB

Рисунок 3. Порядок запуска/остановки сеанса UWB

Конфигурация кода страны UWB

Как показано на рисунке 1, платформа UWB настраивает код страны UWB во время инициализации стека UWB с помощью команды UCI в пространстве поставщика ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ). Структура UWB пытается определить код страны UWB, используя следующие источники (перечисленные в порядке приоритета). Структура UWB останавливается на первом источнике, где определяется код страны.

  1. Переопределить код страны: код страны, принудительно введенный с помощью команды оболочки adb (локальное или автоматическое тестирование).
  2. Телефонный код страны: код страны, полученный через сотовую связь. Если имеется несколько SIM-карт, которые возвращают разные коды, выбранный код страны является недетерминированным.
  3. Код страны Wi-Fi: код страны, полученный через Wi-Fi (80211.ad).
  4. Последний известный телефонный код страны: последний известный код страны, полученный через сотовую связь. Если имеется несколько SIM-карт, которые возвращают разные коды, выбранный код страны является недетерминированным.
  5. Код страны местоположения: код страны, полученный от объединенного поставщика местоположений LocationManager .
  6. Код страны 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. Значение 00 используется для указания того, что код страны неизвестен.

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-байтовое значение для включения или отключения отчетов о диагностике. Настраивайте этот параметр только тогда, когда CORE_GET_CAPS_INFO_RSP возвращает SUPPORTED_DIAGNOSTICS со значением 1 , указывающим, что функция отчетов о диагностике поддерживается.

Ценности:

  • 1 : функция включена
  • 0 : функция отключена.

DIAGRAMS_FRAME_REPORTS_FIELDS 1 или 4 0xE9 2

1-байтовая или 4-байтовая битовая маска для настройки отчетов о диагностике. Эта битовая маска имеет размер 1 байт в Android 14 или более поздней версии и 4 байта в Android 13 или более ранней версии.

Настраивайте этот параметр только тогда, когда CORE_GET_CAPS_INFO_RSP возвращает SUPPORTED_DIAGNOSTICS со значением 1 , указывающим, что функция отчетов о диагностике поддерживается.

Определения битов:

  • b0 (0x01) : активировать поля RSSI.
  • b1 (0x02) : активировать поля AoA.
  • b2 (0x04) : активировать поля CIR.

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 байт, указывающее поддержку запроса статистики энергопотребления.

Ценности:

  • 1 : функция поддерживается.
  • 0 : Функция не поддерживается.
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Значение в 1 байт, указывающее поддержку функции перемежения антенн.

Ценности:

  • 1 : Функция поддерживается.
  • 0 : Функция не поддерживается.
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.

Ценности:

  • 1 : функция поддерживается
  • 0 : Функция не поддерживается.
SUPPORTED_DIAGNOSTICS 1 0xE7 2

1-байтовое значение, указывающее на поддержку отчетов о диагностике.

Ценности:

  • 1 : функция поддерживается
  • 0 : Функция не поддерживается.
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. Каждая 1 в битовой маске соответствует определенному каналу UWB.

Ценности:

  • 0x01 : поддерживается канал 5.
  • 0x02 : поддерживается канал 6.
  • 0x04 : поддерживается канал 8.
  • 0x08 : поддерживается канал 9.
  • 0x10 : поддерживается канал 10.
  • 0x20 : поддерживается канал 12.
  • 0x40 : поддерживается канал 13.
  • 0x80 : поддерживается канал 14.

Коды состояния

Ниже приведены коды состояния в пространстве поставщика. Они возвращаются в ответах 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 необходимо отключить по нормативным причинам.