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)。這類草稿的草稿罐頭回應可能隨時會變更。

介面定義

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 殼層指令強制指定國家/地區代碼 (本機或自動化測試)。
  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_GET_DEVICE_INFO_RSP 和 UCI_GET_CAPS_INFO_RSP 指令，公開裝置實作的 UCI 堆疊版本。這個架構會使用這些指令擷取裝置的 UCI 版本，並據此變更行為。

UWB 模組支援的草稿 CR 清單

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

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

UCI 規格為所有規格定義訊息定義了一組群組 ID (GID) 和運算碼 ID (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 原始設備製造商使用。

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) 硬式編碼)。國家/地區代碼會以 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]

以下是 AOSP 堆疊在 APP_CONFIG 中 TLV 的供應商保留部分中定義的類型長度值 (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：支援 Channel 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)，UWBS 就會傳送這項通知。

狀態變更原因代碼 值 說明
REASON_ERROR_INVALID_CHANNEL_WITH_AOA 0x80

由於所設定的通道不支援 AoA 測距，因此會話狀態已變更。
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x81

由於與其他 CCC 或 FiRa ranging 工作階段發生衝突，因此工作階段狀態已變更。
REASON_REGULATION_UWB_OFF 0x82

由於 UWB 必須因法規而停用，因此工作階段狀態已變更。