UWB HAL 接口

AOSP超寬頻 (UWB) 堆疊使用FiRa 定義的 UCI 介面作為 HAL 表面。 HAL 介面使用不透明管道（ IUwbChip::sendUciMessage()和IUwbClientCallback::onUciMessage() ）來傳送和接收 UWB 命令介面 (UCI) 命令、回應和通知。所有 Android UWB 供應商都必須支援所有 FiRa 規範定義的訊息。 UWB 框架向後相容，並可與 UWB 供應商在裝置上實現的任何 UCI 版本搭配使用。由於 AOSP UWB 框架是一個模組，因此它還可以選擇性地添加對主要 FiRa 標準版本的 UCI 規範草案中批准的變更請求 (CR) 的支援。實施的任何此類 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);

}

UWB 框架的 HAL 呼叫流程

下圖說明了 UWB 框架對 UWB 堆疊初始化、UWB 堆疊取消初始化以及 UWB 會話啟動和停止進程的呼叫流程。

UWB 堆疊初始化

圖 1. UWB 堆疊初始化呼叫流程（UWB 切換開啟）

UWB 堆疊去初始化

圖 2. UWB 堆疊去初始化呼叫流程（UWB 切換關閉）

UWB 會話開始和停止

圖 3. UWB 會話啟動/停止流程

UWB國家代碼配置

如圖 1 所示，UWB 框架在 UWB 堆疊初始化期間使用供應商空間 UCI 指令ANDROID_SET_COUNTRY_CODE （GID= 0xC 、 OID= 0x1 ）設定 UWB 國家/地區代碼。 UWB 框架嘗試使用以下來源（按優先順序列出）來確定 UWB 國家/地區代碼。 UWB 框架停在確定國家代碼的第一個來源。

  1. 覆蓋國家/地區代碼：透過 adb shell 指令強制執行的國家/地區代碼（本地或自動測試）。
  2. 電話國家代碼：透過手機檢索的國家代碼。如果有多個 SIM 卡傳回不同的代碼，則所選的國家/地區代碼是不確定的。
  3. Wi-Fi 國家/地區代碼：透過 Wi-Fi (80211.ad) 擷取的國家代碼。
  4. 最後已知的電話國家/地區代碼：透過蜂窩網路檢索的最後已知的國家/地區代碼。如果有多個 SIM 卡傳回不同的代碼，則所選的國家/地區代碼是不確定的。
  5. 位置國家代碼：從LocationManager融合位置提供者檢索的國家代碼。
  6. OEM預設國家代碼：設備製造商設定的國家代碼。

如果 UWB 框架無法確定 UWB 國家/地區代碼，它將呼叫值為DEFAULT_COUNTRY_CODE ("00")的ANDROID_SET_COUNTRY_CODE UCI 指令，並通知 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_GET_DEVICE_INFO_RSP和UCI_GET_CAPS_INFO_RSP命令公開設備實現的 UCI 堆疊版本。該框架使用這些命令來獲取設備的 UCI 版本並相應地更改其行為。

UWB模組支援的CR草案列表

UWB 模組版本 #330810000 支援 FiRa 2.0 的以下 CR 草稿：

Android UCI 介面（FiRa 供應商部分）

UCI 規範為所有規範定義的訊息定義了一組群組識別碼 (GID) 和操作碼識別碼 (OID)。該規範還保留了一組專門供供應商使用的 GID。 AOSP UWB 堆疊使用其中一些供應商 GID 和 OID 來執行規範中未定義的 Android 特定命令。詳細資料請參閱UCI規範第8.4節。

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

供應商介面版本控制

UWB 供應商必須透過IUwbChip.getSupportedAndroidUciVersion()公開裝置上支援的android.hardware.uwb.fira_android HAL 套件的版本。該框架使用此版本控制資訊來處理向後相容性。

Android GID 和 OID 列表

下表列出了 Android 的 GID 和 OID。 GID 0xE和0xF保留供 Android OEM 使用。

全域ID奧德定義
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 位元組值發送。值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]

以下是APP_CONFIG中 TLV 的供應商保留部分中 AOSP 堆疊定義的類型長度值 (TLV)：

  • 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

以下是 AOSP 堆疊在CAPS_INFO中 TLV 的供應商保留部分中定義的 TLV：

  • GID：0000b（UWB核心組）
  • OID：000011b（ CORE_GET_CAPS_INFO_RSP ）

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

參數名稱長度
（八位元位元組）		標籤
（ID）		供應商介面版本描述
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值。位元掩碼，其中每個位元對應於SET_APP_CFG_CMD中的RANGE_DATA_NTF_CONFIG中使用的值。
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 中的狀態變更原因代碼

以下是在供應商空間中為SESSION_STATUS_NTF中 UWBS 傳回的狀態欄位定義的狀態變更原因代碼。當測距會話的狀態改變（例如，從ACTIVE變成IDLE ）時，UWBS 會發送此通知。

狀態改變原因代碼價值描述
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，因此會話狀態已變更。