UWB HAL 介面

AOSP 超寬頻 (UWB) 堆疊會使用 FiRa 定義的 UCI 介面做為 HAL 介面。HAL 介面會使用不透明管道 (IUwbChip::sendUciMessage() 和 IUwbClientCallback::onUciMessage()) 傳送及接收 UWB 指令介面 (UCI) 指令、回應和通知。所有 Android UWB 供應商都必須支援 FiRa 規格定義的所有訊息。UWB 架構可向後相容，並適用於裝置上 UWB 供應商實作的任何 UCI 版本。由於 AOSP UWB 架構是模組，因此也能選擇性地新增對已核准變更要求 (CR) 的支援，這些要求來自針對主要 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 工作階段啟動和停止程序。

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

圖 2. 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 國家/地區代碼，就會呼叫 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 節。

介面版本管理

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

UWB 模組支援的 CR 草案清單

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

• CR 287
• 支援 CCC 數位車鑰介面的 SUS API 和 UCI 規格 需求

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 原始設備製造商使用。

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 會期設定訊息的參數。

CORE_GET_CAPS_INFO_RSP

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

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

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

狀態碼

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

SESSION_STATUS_NTF 中的狀態變更原因代碼

以下是供應商空間中定義的狀態變更原因代碼，適用於 SESSION_STATUS_NTF 中 UWBS 傳回的狀態欄位。當測距工作階段的狀態變更時 (例如從 ACTIVE 變更為 IDLE)，UWBS 會傳送這項通知。