UWB HAL 介面

Android 開放原始碼計畫 超寬頻 (UWB) 堆疊 採用 FiRa 定義的 UCI 介面 在 HAL 介面上HAL 介面使用不透明管道 (IUwbChip::sendUciMessage() 和 IUwbClientCallback::onUciMessage()) 即將傳送 並接收 UWB 命令介面 (UCI) 指令、回應與通知。 所有 Android UWB 供應商都必須支援所有已定義的 FiRa 規格 訊息。UWB 架構具有回溯相容性，且適用於任何 UCI。 裝置上由 UWB 供應商實作的版本。由於 Android 開放原始碼計畫 UWB 是模組 也可以選擇性地為已核准的變更要求 (CR) 添加支援 草擬針對主要 FiRa 標準發布的 UCI 規格。任何如此 草稿的罐頭回應可能隨時會有變動。

介面定義

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);

}

UWB 架構的 HAL 呼叫流程

下圖說明 UWB 架構針對 UWB 堆疊初始化、UWB 堆疊反初始化、UWB 工作階段啟動和 及停止處理程序

UWB 堆疊初始化

圖 1. UWB 堆疊初始化呼叫流程 (開啟 UWB)

UWB 堆疊反初始化

圖 2. UWB 堆疊反初始化呼叫流程 (UWB 關閉)

UWB 工作階段開始和停止

圖 3. UWB 工作階段開始/停止流程

UWB 國家/地區代碼設定

如圖 1 所示，UWB 架構會設定 UWB 國家/地區代碼 使用供應商空間 UCI 指令在 UWB 堆疊初始化期間 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 架構的國家/地區代碼，則會呼叫 ANDROID_SET_COUNTRY_CODE 個 UCI 指令，值為 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 指令的國家/地區代碼。根據用途 UWB 控制器傳回的狀態碼 (根據 UWB 的 新的國家/地區)，就有可能導致 UWB 堆疊狀態發生變化。

FIRA UCI 規格定義的指令格式

如需 UCI 控制封包格式，請參閱 UCI 第 4.4.2 節 規格。

介面版本管理

UCI 規格讓 UWB 供應商公開 UCI 堆疊版本 使用 UCI_GET_DEVICE_INFO_RSP 和 UCI_GET_CAPS_INFO_RSP 指令。架構會使用這些指令，以擷取 裝置的 UCI 版本，並據此變更行為。

UWB 模組支援的草稿罐頭回應清單

支援下列 FiRa 2.0 罐頭回應草稿： UWB 模組版本 #330810000：

Android UCI 介面 (FiRa 供應商部分)

UCI 規格定義了一組群組 ID (GID) 和運算碼 所有規格定義訊息的識別碼 (OID)。規格 也保留一組專供供應商使用的 GID 使用。Android 開放原始碼計畫 UWB 堆疊會使用部分廠商 GID 和 OID 來執行 Android 專屬指令， 並未在規格中定義。詳情請參閱 UCI 第 8.4 節 規格。

Android 使用的供應商訊息定義於 android.hardware.uwb.fira_android HAL 套件。

供應商介面版本管理

UWB 供應商必須公開 android.hardware.uwb.fira_android 版本 透過裝置支援的 HAL 套件 IUwbChip.getSupportedAndroidUciVersion()。架構會使用此 以便處理回溯相容性

Android GID 和 OID 清單

下表列出 Android 適用的 GID 和 OID。GID 0xE 和 0xF 僅供 Android 原始設備製造商 (OEM) 使用。

GID OID 定義
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 由指令和回應使用，可取得 UWB 功率相關統計資料。 僅支援 UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY 已設為 1。
ANDROID_SET_COUNTRY_CODE = 0x1

用於設定目前的法規國家/地區代碼 ( SIM 卡、Wi-Fi，或是由原始設備製造商 (OEM) 硬式編碼)。國家/地區代碼已送出 為 ISO-3166 國家/地區代碼的 2 位元組值。A 罩杯 值 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]

以下是 Android 開放原始碼計畫堆疊所定義的類型長度值 (TLV) APP_CONFIG 中廠商已保留的部分：

  • GID：0001b (UWB 工作階段設定群組)
  • OID：000011b (SESSION_SET_APP_CONFIG_CMD)
  • OID：000100b (SESSION_GET_APP_CONFIG_CMD)

下表列出 UWB 工作階段設定訊息的參數。

參數名稱 長度
(八位元)		 代碼
(ID)		 供應商介面版本 說明
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 位元組位元遮罩來設定診斷報告。這個 位元遮罩在 Android 14 以上版本中為 1 個位元組 Android 13 以下版本：4 個位元組。

請只在 可退貨 (費用：CORE_GET_CAPS_INFO_RSP) SUPPORTED_DIAGNOSTICS，值為 1 代表支援診斷報表功能。

位元定義：

  • b0 (0x01)：啟用 RSSI 欄位
  • b1 (0x02)：啟用 AoA 欄位
  • b2 (0x04)：啟用 CIR 欄位

CORE_GET_CAPS_INFO_RSP

以下是供應商保留的 Android 開放原始碼計畫堆疊定義的 TLV 部分 TLV 範圍，CAPS_INFO：

  • GID：0000b (UWB 核心群組)
  • OID：000011b (CORE_GET_CAPS_INFO_RSP)

下表列出 UWB 功能訊息的參數。

參數名稱 長度
(八位元)		 代碼
(ID)		 供應商介面版本 說明
SUPPORTED_POWER_STATS_QUERY 1 0xC0 1

1 位元組值，表示支援 Power Stats 查詢。

值：

  • 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

狀態碼

以下是供應商空間中的狀態碼。這些函式會傳回 UWB 子系統 (UWBS) 的 UCI 回應 (例如 SESSION_START_RSP)。

狀態碼 值 說明
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

目前的測距工作階段無法傳回時傳回的狀態碼 而與其他 CCC 或 FiRa 計量工作階段相衝突。
STATUS_REGULATION_UWB_OFF 0x53

目前的測距工作階段無法傳回時傳回的狀態碼 是因 UWB 法規而發起的。

SESSION_STATUS_NTF 中的狀態變更原因代碼

以下是供應商空間中定義的狀態變更原因代碼。 UWBS 在 SESSION_STATUS_NTF 中傳回的狀態欄位。這則通知 在測距工作階段的狀態變更時 (例如 從 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， 合乎規定的原因