UWB HAL 接口

AOSP 超宽带 (UWB) 堆栈使用 FiRa 定义的 UCI 接口作为 HAL Surface。HAL 接口使用不透明管道（IUwbChip::sendUciMessage() 和 IUwbClientCallback::onUciMessage()）发送和接收 UWB 命令接口 (UCI) 命令、响应和通知。所有 Android UWB 供应商都必须支持所有根据 FiRa 规范定义的消息。UWB 框架可向后兼容，可与 UWB 供应商在设备上实现的任何 UCI 版本配合使用。由于 AOSP UWB 框架是一个模块，因此它还可以有选择地添加对已根据草稿 UCI 规范（适用于主要 FiRa 标准版本）获得批准的更改请求 (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 模块支持的草稿更改请求列表

UWB 模块版本 #330810000 支持以下 FiRa 2.0 草稿更改请求：

Android UCI 接口（FiRa 供应商部分）

UCI 规范为所有根据该规范定义的消息规定了一组群组标识符 (GID) 和操作码标识符 (OID)。该规范还预留了一组专供供应商使用的 GID。AOSP UWB 堆栈对该规范中未定义的 Android 专用命令使用其中部分供应商 GID 和 OID。如需了解详情，请参阅 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 使用。

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 字节值的形式发送。值 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 返回值为 1 的 SUPPORTED_DIAGNOSTICS（表示支持诊断报告功能）时，才配置此参数。

位定义：

  • 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 表示支持的 RANGE_DATA_NTF_CONFIG 值的 4 字节位掩码。位掩码中的每个位对应于 SET_APP_CFG_CMD 中 RANGE_DATA_NTF_CONFIG 使用的值。
SUPPORTED_RSSI_REPORTING 1 0xE6 2

表示是否支持 RSSI 报告的 1 字节值。

值：

  • 1：支持此功能
  • 0：不支持此功能
SUPPORTED_DIAGNOSTICS 1 0xE7 2

表示是否支持诊断报告的 1 字节值。

值：

  • 1：支持此功能
  • 0：不支持此功能
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 表示 RSTU 支持的最小槽时长的 4 字节值。
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 表示支持的 FiRa 测距会话数上限的 4 字节值。
SUPPORTED_CHANNELS_AOA 2 0xEA 2

表示支持 AoA 的通道的 2 字节位掩码。位掩码中的每个 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 因监管原因必须停用。