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 會話啟動和停止進程的呼叫流程。
圖 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 框架停在確定國家代碼的第一個來源。
- 覆蓋國家/地區代碼:透過 adb shell 指令強制執行的國家/地區代碼(本地或自動測試)。
- 電話國家代碼:透過手機檢索的國家代碼。如果有多個 SIM 卡傳回不同的代碼,則所選的國家/地區代碼是不確定的。
- Wi-Fi 國家/地區代碼:透過 Wi-Fi (80211.ad) 擷取的國家代碼。
- 最後已知的電話國家/地區代碼:透過蜂窩網路檢索的最後已知的國家/地區代碼。如果有多個 SIM 卡傳回不同的代碼,則所選的國家/地區代碼是不確定的。
- 位置國家代碼:從
LocationManager
融合位置提供者檢索的國家代碼。 - 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 位元組值發送。值 | |
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 位元組值。僅當 價值觀:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 或 4 | 0xE9 | 2 | 用於配置診斷報告的 1 位元組或 4 位元組位遮罩。此位元遮罩在 Android 14 或更高版本中為 1 字節,在 Android 13 或更低版本中為 4 位元組。 僅當 位元定義:
|
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 位元組值表示支援電量統計查詢。 價值觀:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | 1 位元組值指示對天線交錯功能的支援。 價值觀:
|
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 報告的支援。 價值觀:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | 1 位元組值指示診斷報告的支持。 價值觀:
|
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 的頻道。位元遮罩中的每個 價值觀:
|
狀態代碼
以下是供應商空間中的狀態代碼。這些由 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,因此會話狀態已變更。 |