HCI 要求

主机控制器接口 (HCI) 用于与蓝牙控制器交互。

本文档列出了蓝牙 (BT) 和蓝牙低功耗 (BLE) 的要求,旨在让主机 BT 堆栈供应商和 BT 控制器供应商了解,必须遵循这些平台要求才能使用下面所述的功能集。

蓝牙 SIG 网站上提供了蓝牙核心 4.1 规范(在本文档中称为“BT 4.1 核心规范”)以及其他正式文档。

总体设计概览

芯片功能和配置

作为一个开放平台,Android 汇集了各种软件版本、原始设备制造商 (OEM)、供应商以及平台和芯片功能。

本文档介绍了一种可让 BT 控制器提供其功能(不在标准的 BT 4.1 核心规范内)的设计理念,以此来管理不断变化的格局以及迁移。然后,主机 BT 堆栈可以使用这些功能来确定要启用的功能。

支持开放式标准

Android 的一个目标是支持那些在蓝牙规范中获得正式批准的开放式标准。如果下文所述的某项功能在未来蓝牙规范的标准 HCI 方法中可用,那么我们就倾向于将该方法设为默认方法。

特定于供应商的功能

特定于供应商的命令:LE_Get_Vendor_Capabilities_Command

OCF(OpCode 命令字段):0x153

命令参数 大小 用途
不适用 空命令参数列表

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
max_advt_instances 1 个八位字节 支持的广告实例数量
offloaded_resolution_of_private-address 1 个八位字节 RPA 的 BT 芯片功能;如果芯片支持,则需要主机启用。
0 = 不能
1 = 能
total_scan_results_storage 2 个八位字节 用于扫描结果的存储空间(以字节为单位)
max_irk_list_sz 1 个八位字节 固件中支持的 IRK 条目数量
filtering_support 1 个八位字节 支持在控制器中进行过滤。
0 = 不支持
1 = 支持
max_filter 1 个八位字节 支持的过滤器数量
activity_energy_info_support 1 个八位字节 支持报告活动和功耗信息。
0 = 不能
1 = 能
version_supported 2 个八位字节
[0x00, 0x60]
指定支持的 Google 功能规范的版本。
字节[0] = 主要版本号
字节[1] = 次要版本号
total_num_of_advt_tracked 2 个八位字节 出于 OnLost/OnFound 目的跟踪的广告主的总数
extended_scan_support 1 个八位字节 支持更长的扫描时段和间隔
debug_logging_supported 1 个八位字节 支持从控制器记录二进制文件调试信息
LE_address_generation_offloading_support 1 个八位字节 0 = 不支持
1 = 支持

max_advt_instances parameter 表示控制器中的广告实例的总数。advt_instance ID 的范围将是 0 到 max_advt_instances-1

ID 等于 0 的广告实例将映射到现有(默认/标准)HCI 实例。在默认/标准 HCI 接口上运行时,应使用标准的 HCI 命令集。

多广告主支持

多广告主支持的目标如下:

  • 能够支持多个广告 (max_advt_instances)
  • 提供不同的传输功率以支持不同的范围
  • 支持不同的广告内容
  • 针对每位个广告主进行个性化回复
  • 保护每位广告主的隐私(不可跟踪)
  • 可连接

为了确保此规范接近现有标准,我们提供了下列特定于供应商的命令。它们派生自蓝牙核心 4.1 规范。

LE_Multi_Advt_Command

OCF:0x154

命令参数 大小 用途
Multi_advt_opcode 1 个八位字节 0x01 - Set_Advt_Param_Multi_Sub_Cmd
0x02 - Set_Advt_Data_Multi_Sub_Cmd
0x03 - Set_Scan_Resp_Data_Multi_Sub_Cmd
0x04 - Set_Random_Addr_Multi_Sub_Cmd
0x05 - Set_Advt_Enable_Multi_Sub_Cmd

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Multi_advt_opcode 1 个八位字节 0x01 - Set_Advt_Param_Multi_Command
0x02 - Set_Advt_Data_Multi_Command
0x03 - Set_Scan_Resp_Data_Multi_Command
0x04 - Set_Random_Addr_Multi_Command
0x05 - Set_Advt_Enable_Multi_Command

LE_Multi_Advt_Command:Set_Advt_Param_Multi_Sub_Cmd

基础参考(以下称为“规范”):BT 4.1 核心规范,第 964 页(LE 设置广告参数命令)

子 OCF:0x01

子命令参数 大小 用途
Advertising_Interval_Min 按规范 按规范
Advertising_Interval_Max 按规范 按规范
Advertising_Type 按规范 按规范
Own_Address_Type 按规范 按规范
Own_Address 按规范 按规范
Direct_Address_Type 按规范 按规范
Direct_Address 按规范 按规范
Advertising_Channel_Map 按规范 按规范
Adverstising_Filter_Policy 按规范 按规范
Advertising_Instance 1 个八位字节 指定上述参数对实例的适用性
Tx_power 1 个八位字节 Transmit_Power
单位 - 以 dBm 为单位(有符号整数)
范围(-70 到 +20)

在设置此多广告实例时,Own_Address 参数可以是主机配置的地址。这样,在传输第一个信标时能够获得一个可解析私有地址。无论采用何种连接,实例上的广告都会继续。主机 BT 堆栈可以发出命令,以在建立连接后开始在实例上投放广告。

系统将按照上述命令,针对此命令生成一个命令完成事件,如蓝牙核心 4.1 规范中所规定。如果广告实例或 Tx_Power 参数无效,则控制器会使用非成功(无效参数)代码响应。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Multi_advt_opcode 1 个八位字节 0x01 [Set_Advt_Param_Multi_Sub_Cmd]

LE_Multi_Advt_Command:Set_Advt_Data_Multi_Sub_Cmd

基础参考:BT 4.1 核心规范,第 969 页(LE 设置广告数据命令)

子 OCF:0x02

子命令参数 大小 用途
Advertising_Data_Length 按规范 按规范
Advertising_Data 按规范 按规范
Advertising_Instance 1 个八位字节 指定上述参数对实例的适用性

系统将按照上述命令,针对此命令生成一个命令完成事件,如蓝牙核心 4.1 规范中所规定。如果广告实例或 Tx_Power 参数无效,则控制器会使用非成功代码响应。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Multi_advt_opcode 1 个八位字节 0x02 [Set_Advt_Data_Multi_Sub_Cmd]

LE_Multi_Advt_Command:Set_Scan_Resp_Data_Multi_Sub_Cmd

基础参考:BT 4.1 核心规范,第 970 页(LE 设置扫描响应数据命令)

子 OCF:0x03

子命令参数 大小 用途
Scan_Response_Data_Length 按规范 按规范
Scan_Response_Data 按规范 按规范
Advertising_Instance 1 个八位字节 指定上述参数对实例的适用性

系统将按照上述命令,针对此命令生成一个命令完成事件,如蓝牙核心 4.1 规范中所规定。如果广告实例或 Tx_Power 参数无效,则控制器会使用非成功代码(无效参数)响应。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Multi_advt_opcode 1 个八位字节 0x03 [Set_Scan_Resp_Data_Multi_Sub_Cmd]

LE_Multi_Advt_Command:Set_Random_Addr_Multi_Sub_Cmd

基础参考:BT 4.1 核心规范,第 963 页(LE 设置随机地址命令)

子 OCF:0x04

子命令参数 大小 用途
随机地址 按规范 按规范
Advertising_Instance 1 个八位字节 指定上述参数对实例的适用性

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Multi_advt_opcode 1 个八位字节 0x04 [Set_Random_Addr_Multi_Sub_Cmd]

LE_Multi_Advt_Command:Set_Advt_Enable_Multi_Sub_Cmd

基础参考:BT 4.1 核心规范,第 971 页(该核心规范中的 LE 设置广告启用命令)

OCF:0x05

子命令参数 大小 用途
Advertising_Enable 1 个八位字节 1 表示启用。任何其他值均表示停用。
Advertising_Instance 1 个八位字节 指定上述参数对实例的适用性。实例 0 表示标准 HCI 实例。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Multi_advt_opcode 1 个八位字节 0x05 [Set_Advt_Enable_Multi_Sub_Cmd]

分流解析私有地址

此功能允许在控制器固件或硬件中解析私有地址,从而提供以下优势:

  • 缩短主机在解析私有地址时的延迟时间
  • 通过避免唤醒主机来节省电量

LE_Set_RPA_Timeout

OCF:0x15C

命令参数 大小 用途
LE_local_IRK 16 个八位字节 本地设备 IRK 用于生成可解析的随机地址。
tRPA_min 2 个八位字节 最短 RPA 生成超时时间(以秒为单位)。 控制器必须在超时期间或超时之后,针对任何广告/扫描/连接事件生成新的可解析地址。
有效范围:300-1800
tRPA_max 2 个八位字节 最长 RPA 生成超时时间(以秒为单位)。 控制器必须在超时期间或超时之前,针对任何广告/扫描/连接事件生成新的可解析地址。
有效范围:tRPA_min-1800
返回参数 大小 用途
Status 1 个八位字节 命令的状态。

建议的 HCI 状态值:
0x00 成功
0x01 未知命令(如果不受支持)
0x12 无效的命令参数(如果任意参数不在指定范围内)

LE_RPA_offload_Command

OCF:0x155

命令参数 大小 用途
RPA_offload_opcode 1 个八位字节 0x1 - 启用特定于客户的功能
0x2 - 将 IRK 添加到列表中
0x3 - 从列表中移除 IRK
0x4 - 清除 IRK 列表
0x5 - 读取 IRK 列表条目

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Event_RPA_offload_opcode 1 个八位字节 0x1 - 启用特定于客户的功能
0x2 - 将 IRK 添加到列表中
0x3 - 从列表中移除 IRK
0x4 - 清除 IRK 列表
0x5 - 读取 IRK 列表条目

LE_RPA_offload:Enable_cust_specific_sub_Command

子 OCF:0x01

子命令参数 大小 用途
enable_customer_specific_feature_set 1 个八位字节 0x01 - 启用分流 RPA 功能
0x00 - 停用分流 RPA 功能

RPA 分流需要由主机根据芯片功能启用。请参阅 LE_Get_Vendor_Capabilities_Command. 每个芯片在固件中具有不同的 max_irk_list_sz

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Event_cust_specific_feature_opcode 1 个八位字节 0x01 [启用特定于客户的功能]

LE_RPA_offload:Add_IRK_to_list_sub_Command

子 OCF:0x02

子命令参数 大小 用途
LE_IRK 16 个八位字节 LE IRK(第 1 个字节 LSB)
Address_Type 1 个八位字节 0:公开地址
1:随机地址
LE_Device_Address 6 个八位字节 与 IRK 相关联的公开地址或随机地址(第 1 个字节 LSB)

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Event_cust_specific_feature_opcode 1 个八位字节 0x02 [将 IRK 添加到列表中]
LE_IrkList_AvailableSpaces 1 个八位字节 完成当前操作后可用的 IRL 列表条目

LE_RPA_offload:Remove_IRK_to_list_sub_Command

子 OCF:0x03

子命令参数 大小 用途
Address_Type 1 个八位字节 0:公开地址
1:随机地址
LE_Device_Address 6 个八位字节 与 IRK 相关联的公开地址或随机地址

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Event_cust_specific_feature_opcode 1 个八位字节 0x03 [从列表中移除 IRK]
LE_IrkList_AvailableSpaces 1 个八位字节 完成当前操作后可用的 IRL 列表条目

LE_RPA_offload:Clear_IRK_list_sub_Command

子 OCF:0x04

子命令参数 大小 用途

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Event_cust_specific_feature_opcode 1 个八位字节 0x04 [清除 IRK 列表]
LE_IrkList_AvailableSpaces 1 个八位字节 完成当前操作 [max_irk_list_sz] 后可用的 IRL 列表条目

LE_RPA_offload:Read_IRK_list_sub_Command

子 OCF:0x05

子命令参数 大小 用途
LE_read_IRK_list_entry-index 1 个八位字节 IRK 列表 [0,max_irk_list_sz-1] 索引

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Event_cust_specific_feature_opcode 1 个八位字节 0x05 [读取 IRK 列表条目]
LE_Read_IRK_List_entry 1 个八位字节 主机想要读回的 IRK 索引(IRK 列表的最大大小为 32)
LE_IRK 16 个八位字节 IRK 值
Address_Type 1 个八位字节 0:公开地址
1:随机地址
LE_Device_Address 6 个八位字节 与 IRK 相关联的公开地址或随机地址
LE_Resolved_Private_Address 6 个八位字节 此 IRK 的当前已解析的可解析私有地址

批处理扫描结果

我们的一个设计目标是改善蓝牙 LE 扫描响应事件通知传送给主机的方式,从而节省主机电量。

通过降低控制器通知主机应用处理器扫描结果的频率,主机应用处理器可以更长时间保持在闲置/休眠状态。这会降低主机功耗。LE_Get_Vendor_Capabilities_Command 的返回参数 total_scan_results_storage 表示芯片最多可存储多少扫描结果。

此功能重点关注蓝牙控制器中 LE 扫描结果存储设备的管理和配置。该存储设备用于暂时批处理广告数据以及扫描由控制器接收以供稍后传送到主机的数据和元数据。

固件应支持可以同时进行的两类批处理:

  • 截断。包含以下信息元素:{MAC, TX Power, RSSI, Timestamp}
  • 完整。包含以下信息元素:{MAC, TX Power, RSSI, Timestamp, Adv Data, Scan Response}

LE_Batch_Scan_Command

OCF:0x156

命令参数 大小 用途
Batch_Scan_opcode 1 个八位字节 0x1 - 启用特定于客户的功能
0x2 - 设置批量扫描存储设备参数
0x3 - 设置批量扫描参数
0x4 - 读取批量扫描结果参数

系统将针对此命令生成一个命令完成事件。 启用特定于客户的功能不会启动扫描。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Batch_Scan_opcode 1 个八位字节 0x1 - 启用特定于客户的功能
0x2 - 设置批量扫描存储设备参数
0x3 - 设置批量扫描参数
0x4 - 读取批量扫描结果参数

LE_Batch_Scan_Command:启用特定于客户的功能

子 OCF:0x01

子命令参数 大小 用途
enable_customer_specific_feature_set 1 个八位字节 0x01 - 启用批量扫描功能
0x00 - 停用批量扫描功能

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Batch_Scan_opcode 1 个八位字节 0x1 - 启用特定于客户的功能
0x2 - 设置批量扫描存储设备参数
0x3 - 设置批量扫描参数
0x4 - 读取批量扫描结果参数

LE_Batch_Scan_Command:设置批量扫描存储设备参数子命令

子 OCF:0x02

子命令参数 大小 用途
Batch_Scan_Full_Max 1 个八位字节 分配到完整样式的最大存储空间(以 % 形式表示)[范围:0-100]
Batch_Scan_Truncated_Max 1 个八位字节 分配到截断样式的最大存储空间(以 % 形式表示)[范围:0-100]
Batch_Scan_Notify_Threshold 1 个八位字节 单个存储池的设置通知等级(以 % 形式表示)[范围:0-100]。
设置为 0 会停用通知。 系统会生成特定于供应商的 HCI 事件(存储阈值违规子事件)

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Batch_scan_opcode 1 个八位字节 0x02 [设置批量扫描参数]

LE_Batch_Scan_Command:设置批量扫描参数子命令

子 OCF:0x03

子命令参数 大小 用途
Batch_Scan_Mode 1 个八位字节 0x00 - 批量扫描已停用
0x01 - 已启用截断模式
0x02 - 已启用完整模式
0x03 - 已启用截断模式和完整模式
Duty_cycle_scan_window 4 个八位字节 批量扫描的扫描时间(插槽数)
Duty_cyle_scan_interval 4 个八位字节 批量扫描的间隔时间(插槽数)
own_address_type 1 个八位字节 0x00 - 公共设备地址
0x01 - 随机设备地址
Batch_scan_Discard_Rule 1 个八位字节 0 - 舍弃最早的广告
1 - 舍弃 RSSI 最弱的广告

此子命令会开始批量扫描(如果启用)。在截断扫描中,结果以截断形式存储,其中截断样式的唯一密钥 = {BD_ADDR, scan_interval}。这意味着,系统针对每个扫描间隔只记录一个 BD_ADDR will。针对截断模式保存的记录如下:{BD_ADDR, Tx Power, RSSI, Timestamp}。

如果启用完整模式,系统会使用主动扫描并记录扫描响应。完整样式的唯一密钥 = {MAC, Ad packet},与扫描间隔无关。针对完整模式保存的记录如下:{BD_ADDR, Tx Power, RSSI, Timestamp, Ad packet, Scan Response}。在完整样式下,如果在不同的扫描间隔多次看到同一个广告包,则仅记录一次。不过,在截断模式下,重要的是 BA_ADDR 在不同扫描间隔的显示情况(每个扫描间隔显示一次)。RSSI 是扫描间隔内唯一广告的所有重复项的平均值。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Batch_scan_opcode 1 个八位字节 0x03 [设置批量扫描参数]

LE_Batch_Scan_Command:读取批量扫描结果子命令

子 OCF:0x04

子命令参数 大小 用途
Batch_Scan_Data_read 1 个八位字节 0x01 - 截断模式数据
0x02 - 完整模式数据

系统将针对此命令生成一个命令完成事件。 当主机发出此命令时,控制器中的结果可能无法完全放入一个命令完成事件。主机会反复发出此命令,直到命令完成事件中的相应结果显示记录数为 0,这表示控制器没有更多要传输给主机的记录。每个命令完成事件可以只包含一种数据类型(完整或截断)的多个记录。

控制器和主机时间参考不同步。因此,时间戳需要特别说明。时间戳的单位为 50 毫秒。时间戳的值取决于主机指定 Read_Batch_Scan_Results_Sub_cmd 的时间。 如果固件中命令到达时间为 T_c,则在固件中截取时间戳的实际时间为 T_fw. 报告时间将是 (T_c - T_fw)T_cT_fw 在固件时域中。这样一来,主机能够计算事件发生的时间。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Batch_scan_opcode 1 个八位字节 0x03 [设置批量扫描参数]
Batch_Scan_data_read 1 个八位字节 标识格式(截断或完整)
num_of_records 1 个八位字节 Batch_Scan_data_read 的记录数
format_of_data 变量 截断模式:
Address[0]:6 个八位字节
Address_Type[0]:1 个八位字节
Tx_Pwr[0]:1 个八位字节
RSSI[0]:1 个八位字节
Timestamp[0]:2 个八位字节
[多个采用上述格式的记录 (num_of_records)]

完整模式:
Address[0]:6 个八位字节
Address_Type[0]:1 个八位字节
Tx_Pwr[0]:1 个八位字节
RSSI[0]:1 个八位字节
Timestamp[0]:2 个八位字节
Adv packet_len[0]:1 个八位字节
Adv_packet[0]:Adv_packet_len 个八位字节
Scan_data_resp_len[0]:1 个八位字节
Scan_data_resp[0]:Scan_data_resp 个八位字节
[多个采用上述格式的记录 (num_of_records)]

广告包内容过滤器

可借此在控制器中启用/停用/设置广告包内容过滤器 (APCF)。

LE_APCF_Command

OCF:0x157

命令参数 大小 用途
APCF_opcode 1 个八位字节 0x00 - APCF 启用
0x01 - APCF 设置过滤参数
0x02 - APCF 广播地址
0x03 - APCF 服务 UUID
0x04 - APCF 服务请求 UUID
0x05 - APCF 本地名称
0x06 - APCF 制造商数据
0x07 - APCF 服务数据

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 返回状态
APCF_opcode 1 个八位字节 0x00 - APCF 启用
0x01 - APCF 设置过滤参数
0x02 - APCF 广播地址
0x03 - APCF 服务 UUID
0x04 - APCF 服务请求 UUID
0x05 - APCF 本地名称
0x06 - APCF 制造商数据
0x07 - APCF 服务数据

LE_APCF_Command:Enable_sub_cmd

子 OCF:0x00

子命令参数 大小 用途
APCF_enable 1 个八位字节 0x01 - 启用 APCF 功能
0x00 - 停用 APCF 功能

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x0 - APCF 启用
APCF_Enable 1 个八位字节 通过 APCF_enable 设置启用/停用

LE_APCF_Command:set_filtering_parameters_sub_cmd

该子命令用于添加或删除芯片过滤的某个过滤器规范或清除过滤器列表。

子 OCF:0x01

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会清除特定过滤器以及其他表中的相关功能条目。
执行清除操作会清除所有过滤器以及其他表中的相关条目。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_Feature_Selection 2 个八位字节 所选功能的位掩码:
位 0:设为启用广播地址过滤器
位 1:设为启用服务数据更改过滤器
位 2:设为启用服务 UUID 检查
位 3:设为启用服务请求 UUID 检查
位 4:设为启用本地名称检查
位 5:设为启用制造商数据检查
位 6:设为启用服务数据检查
APCF_List_Logic_Type 2 个八位字节 针对 APCF_Feature_Selection. 中指定的每个功能选项(按位位置)的逻辑操作
仅在启用功能时有效。
位位置值:
0:OR
1:AND
如果选择“AND”逻辑,则广告包仅在其包含列表中的所有条目时传递过滤器。
如果选择“OR”逻辑,则广告包只要包含列表中的任何条目,就会传递过滤器。
APCF_Filter_Logic_Type 1 个八位字节 0x00:OR
0x01:AND
注意:APCF_Feature_Selection, 的前三个字段的类型为“不适用”,这始终是“AND”逻辑。它们仅适用于 APCF_Feature_Selection. 的四个字段(位 3 位 6)
rssi_high_thresh 1 个八位字节 [以 dBm 为单位] 只有该信号高于 RSSI 高阈值时,广告主才会被视为可见。否则,固件必须表现得就像从未见过一样。
delivery_mode 1 个八位字节 0x00 - immediate
0x01 - on_found
0x02 - batched
onfound_timeout 2 个八位字节 仅当 delivery_mode on_found 时有效
[以毫秒为单位]
固件在报告之前停留和收集其他广告所用的时间。
onfound_timeout_cnt 1 个八位字节 仅当 delivery_modeon_found 时有效
[计数]
如果 onFound 中的广告在 onfound_timeout 期间停留在固件中,则会收集一些广告并检查计数。 如果计数超过 onfound_timeout_cnt,之后会立即报告为 OnFound
rssi_low_thresh 1 个八位字节 仅当 delivery_modeon_found 时有效 [以 dBm 为单位]。
如果已接收包的 RSSI 低于 RSSI 低阈值,则视为未看到该广告主包。
onlost_timeout 2 个八位字节 仅当 delivery_modeon_found 时有效
[以毫秒为单位]
如果系统在发现某个广告后,在 lost_timeout 期间未连续看到该广告,则会将其报告为已丢失。报告已丢失情况是即时进行的。
num_of_tracking_entries 2 个八位字节 仅当 delivery_modeon_found 时有效
[计数]
根据过滤器跟踪的广告主的总数。

RSSI 值必须使用二进制补码来表示负值。

主机应该能够配置多个 APCF_Application_Address_type 设置为 0x02 的过滤器(适用于所有广播地址),以管理各种过滤器组合。

过滤、批处理和报告是相互关联的概念。 每个广告及相关扫描响应都必须逐个通过所有过滤器。因此,生成的操作 (delivery_mode)) 与过滤紧密关联。 传送模式如下所示:report_immediately,batchonFound. OnLost 值与 OnFound 相关,从某种意义上说,该值丢失后,会紧跟 OnFound

下面的处理流程介绍了概念模式。

收到广告(或扫描响应)帧时,该帧会按序列顺序应用到所有过滤器。广告可能导致系统根据一个过滤器立即进行报告并因其他过滤器操作立即进行批处理。

RSSI 级别阈值(高和低)能够控制帧何时可见以进行过滤器处理,即使控制器收到有效的包也是如此。在传送模式设置为“立即”或“批处理”时,系统会考虑某个帧的 RSSI,以进一步进行控制器处理。不同的应用需要不同的报告和批处理行为。这样一来,多个应用能够有直接报告和/或固件中的批处理结果。例如,一个应用已启用批量扫描,之后另一个应用发起常规 LE 扫描。在发起批量扫描之前,框架/应用会设置相应的过滤器。之后,当第二个应用发起常规扫描时,之前的批处理操作将继续。 不过,由于常规扫描,因此这类似于从概念上添加空过滤器(以及所有现有过滤器)和 LE 扫描命令。处于活动状态时,LE 扫描命令参数的优先级更高。停用常规 LE 扫描时,控制器将还原到之前的批量扫描(如果存在)。

OnFound 传送模式取决于配置的过滤器。触发过滤器操作成功的组合被认为是跟踪 onLost 的实体。相应的事件是 LE 广告跟踪子事件。

过滤器的 OnFound/OnLost 转换(如果启用)将如下所示:

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x02 - APCF 设置过滤参数
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 过滤器表中的可用条目数

LE_APCF_Command:broadcast_address_sub_cmd

该子命令用于添加或删除芯片过滤的某个广告主地址或清除广告主地址列表。

子 OCF:0x02

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的指定广播地址。
执行清除操作会清除指定过滤器中的所有广播地址。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_Broadcaster_Address 6 个八位字节 要添加到广播地址列表或从中删除的 6 字节设备地址
APCF_Application_Address_type 1 个八位字节 0x00:公开
0x01:随机
0x02:不适用(地址类型不适用)

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x02 - APCF 广播地址
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 广播地址表中仍可用的空闲条目数

LE_APCF_Command:service_uuid_sub_cmd

该子命令用于添加或删除芯片过滤的某个服务 UUID 或清除服务 UUID 列表。

子 OCF:0x03

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的指定服务 UUID。
执行清除操作会清除指定过滤器中的所有服务 UUID。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_UUID 2 个、4 个、16 个八位字节 要添加到列表或从中删除的服务 UUID(16 位、32 位或 128 位)。
APCF_UUID_MASK 2 个、4 个、16 个八位字节 要添加到列表中的服务 UUID 掩码(16 位、32 位或 128 位)。其长度应与 APCF_UUID. 相同。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x03 - APCF 服务 UUID
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 服务 UUID 表中仍可用的空闲条目数

LE_APCF_Command:solicitation_uuid_sub_cmd

该子命令用于添加或删除芯片过滤的某个请求 UUID 或清除请求 UUID 列表。

子 OCF:0x04

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的请求 UUID 地址。
执行清除操作会清除指定过滤器中的所有请求 UUID。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_UUID 2 个、4 个、16 个八位字节 要添加到列表或从中删除的请求 UUID(16 位、32 位或 128 位)。
APCF_UUID_MASK 2 个、4 个、16 个八位字节 要添加到列表中的请求 UUID 掩码(16 位、32 位或 128 位)。其长度应与 APCF_UUID. 相同。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x04 - APCF 请求 UUID
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 请求 UUID 表中仍可用的空闲条目数

LE_APCF_Command:local_name_sub_cmd

该子命令用于添加或删除芯片过滤的某个本地名称字符串或清除本地名称字符串列表。

子 OCF:0x05

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的指定本地名称字符串。
执行清除操作会清除指定过滤器中的所有本地名称字符串。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_LocName_Mandata_or_SerData 大小可变 本地名称字符串。

注意:
i) 目前本地名称字符串中的字符数上限为 29
ii) 执行“清除”操作时不适用 (0x2)

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x05 - APCF 本地名称
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 本地名称表中仍可用的空闲条目数

LE_APCF_Command:manf_data_sub_cmd

该子命令用于添加或删除芯片过滤的某个制造商数据字符串或清除制造商数据字符串列表。

子 OCF:0x06

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的指定制造商数据字符串。
执行清除操作会清除指定过滤器中的所有制造商数据字符串。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_LocName_Mandata_or_SerData 大小可变 制造商数据字符串。

注意:
i) 目前本地名称字符串中的字符数上限为 29
ii) 执行“清除”操作时不适用 (0x2)
APCF_ManData_Mask 大小可变 要添加到列表中的制造商数据掩码。其长度应与 APCF_LocName_or_ManData_or_SerData 相同。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x06 - APCF 制造商数据
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 制造商数据表中仍可用的空闲条目数。

LE_APCF_Command:service_data_sub_cmd

该子命令用于添加或删除芯片过滤的某个服务数据字符串或清除服务数据字符串列表。

子 OCF:0x07

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的指定服务数据字符串。
执行清除操作会清除指定过滤器中的所有服务数据字符串。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_LocName_Mandata_or_SerData 大小可变 服务数据字符串。

注意:
i) 目前本地名称字符串中的字符数上限为 29
ii) 执行“清除”操作时不适用 (0x2)
APCF_LocName_Mandata_or_SerData_Mask 大小可变 要添加到列表中的服务数据掩码。其长度应与 APCF_LocName_or_ManData_or_SerData. 相同。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0x07 - APCF 服务数据
APCF_Action 1 个八位字节 回声返回命令的 APCF_Action
APCF_AvailableSpaces 1 个八位字节 服务数据表中仍可用的空闲条目数。

控制器活动和功耗信息命令

这些信息的目的是提高主机系统功能,以分析所有组件的总活动,包括 BT 控制器及其宏状态,以及应用和框架中所发生的情况。为此,BT 堆栈和控制器需要提供以下信息:

  • BT 堆栈:报告该控制器当前的宏操作状态
  • 固件:报告总活动和功耗信息

BT 主机堆栈宏状态,具体在用户级确定:

  • 闲置:[page scan, LE advt, inquiry scan]
  • 扫描:[paging/inquiry/trying to connect]
  • 活动:[ACL link on, SCO link ongoing, sniff mode]

控制器在其生命周期跟踪的活动包括 Tx 时间、Rx 时间、闲置时间,以及消耗的总功率。从主机读取这些信息时,系统会将其清除。

特定于供应商的命令:LE_Get_Controller_Activity_Energy_Info

OCF:0x159

子命令参数 大小 用途
不适用 空命令参数

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
total_tx_time_ms 4 个八位字节 执行 Tx 所需的总时间
total_rx_time_ms 4 个八位字节 执行 Rx 所需的总时间
total_idle_time_ms 4 个八位字节 总闲置时间(非休眠低功耗状态)
total_energy_used 4 个八位字节 使用的总功率 [电流 (mA)、电压 (V) 和时间(毫秒)的乘积]

LE 扩展设置扫描参数命令

该命令可用于在控制器中延长扫描时段和间隔。根据 BT 4.1 核心规范,扫描时段和间隔的上限为 10.24 秒,而这会限制扫描间隔超过 10.24 秒的应用。

基础参考:BT 4.1 核心规范,第 973 页(LE 设置扫描参数命令)

OCF:0x15A

命令参数 大小 用途
LE_Ex_Scan_Type 1 个八位字节 0x00 - 被动扫描。不应发送 SCAN_REQ 包(默认)。
0x01 - 主动扫描。 可以发送 SCAN_REQ 包。
LE_Ex_Scan_Interval 4 个八位字节 指的是从控制器开始其最后一次 LE 扫描到开始后续 LE 扫描的时间间隔。
范围:0x0004 到 0x00FFFFFF
默认值:0x0010(10 毫秒)
时间 = N * 0.625 毫秒
时间范围:2.5 毫秒到 10442.25 秒
LE_Ex_Scan_Window 4 个八位字节 LE 扫描持续的时间。LE_Scan_Window 应小于或等于 LE_Scan_Interval
范围:0x0004 到 0xFFFF
默认值:0x0010(10 毫秒)
时间 = N * 0.625 毫秒
时间范围:2.5 毫秒到 40.95 秒
Own_Address_Type 1 个八位字节 0x00 - 公共设备地址(默认)
0x01 - 随机设备地址
LE_Ex_Scan_Filter_Policy 0x00 - 接受所有广告包(默认)。 应该忽略未针对此设备处理的已定位广告包。
0x01 - 忽略设备中未在仅限白名单列表中的广告包。
应该忽略未针对此设备处理的已定位广告包。

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
Status 1 个八位字节 命令完成状态

获取控制器调试信息命令

该信息元素的目的是以二进制的形式通过主机获取控制器调试信息,以进行后处理和分析。这有助于调试现场问题,并为工程师提供工具包来记录信息以进行分析。控制器可以在主机通过事件(控制器调试信息子事件)请求时提供信息,也可以在控制器需要时自主提供信息。例如,报告固件状态信息、崩溃转储信息、记录信息等。

OCF:0x15B

命令参数 大小 用途
不适用 空命令参数列表

系统将针对此命令生成一个命令完成事件。

返回参数 大小 用途
状态 1 个八位字节 命令完成状态

HCI 事件(特定于供应商)

在某些情况下,需要特定于供应商的 HCI 事件。请参考 BT 4.1 核心规范第 486 页的图 5.4。事件参数 0 将始终包含第一个子事件代码,系统据此对 HCI 事件的其余部分进行解码。

事件参数 大小 用途
HCI_vendor_specific_event_code 1 个八位字节 0xFF
sub_event_code 1 个八位字节 子事件代码的大小为 1 个八位字节,该字节紧跟在 HCI 事件包中的参数长度后。

存储阈值违规子事件

此事件表示超出了存储阈值。

子事件代码 = 0x54

子事件参数 大小 用途

LE 多广告状态更改子事件

此事件表示广告实例已更改其状态。目前,该事件仅用于表示因连接而停止的广告实例。

子事件代码 = 0x55

子事件参数 大小 用途
Advertising_instance 1 个八位字节 标识特定广告实例。
有效值为 0 到 max_advt_instances -1
State_Change_Reason 1 个八位字节 0x00:收到的连接
Connection_handle 2 个八位字节 标识导致 advt 实例被停用的连接(如果无效,则为 0xFFFF)

LE 广告跟踪子事件

此事件表示广告主何时被发现或丢失。

子事件代码 = 0x56

子事件参数 大小 用途
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
Advertiser_State 1 个八位字节 0x00:已找到广告主
0x01:广告主已丢失
Advt_Info_Present 1 个八位字节 0x00:存在广告主信息 (Advt_Info)
0x01:不存在广告主信息 (Advt_Info)
Advertiser_Address 6 个八位字节 公开地址或随机地址
Advertiser_Address_Type 1 个八位字节 0x00:公开地址
0x01:随机地址
Advt_Info Tx_Pwr[0]:1 个八位字节
RSSI[0]:1 个八位字节
Timestamp[0]:2 个八位字节
Adv packet_len[0]:1 个八位字节
Adv_packet[0]Adv_packet_len 个八位字节
Scan_data_resp_len[0]:1 个八位字节
Scan_data_resp[0]Scan_data_resp 个八位字节

控制器调试信息子事件

控制器使用此事件来向主机提供二进制文件调试信息。

子事件代码 = 0x57

子事件参数 大小 用途
debug_block_byte_offset_start 2 个八位字节 从头调试块字节偏移量
last_block 1 个八位字节 0x00:存在更多调试数据
0x01:最后一个二进制文件块;没有更多调试数据
cur_pay_load_sz 2 个八位字节 当前事件中的二进制文件块大小
Debug_Data 变量 cur_payload_sz 的调试数据