HCI 要求

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

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

本文档将“蓝牙核心 5.2 规范”简称为“规范”。蓝牙 SIG 网站上提供了蓝牙核心 5.2 规范以及其他正式文档。

总体设计概览

芯片功能和配置

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

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

支持开放式标准

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

特定于供应商的功能

特定于供应商的命令:LE_Get_Vendor_Capabilities_Command

OpCode 命令字段 (OCF):0x153

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

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
max_advt_instances
(已废弃)
1 个八位字节 支持的通告实例数量。

在 v0.98 之后预留
此参数已在 Google 功能规范 v0.98 及更高版本中废弃,并由 BT 规范 5.0 及更高版本中提供的“LE 扩展通告功能”取代
offloaded_resolution_of_private-address
(已废弃)
1 个八位字节 RPA 的 BT 芯片功能。
如果芯片支持,则需要由主机启用。
0 = 不能
1 = 能

在 v0.98 之后预留
此参数已在 Google 功能规范 v0.98 及更高版本中废弃,并由 BT 规范 4.2 及更高版本中提供的“隐私功能”取代
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 个八位字节 指定支持的 Google 功能规范版本
byte[0] = 主要版本号
byte[1] = 次要版本号

v1.00
byte[0] = 0x01
byte[1] = 0x00
total_num_of_advt_tracked 2 个八位字节 出于 OnLost/OnFound 目的跟踪的通告者的总数
extended_scan_support 1 个八位字节 支持更长的扫描时段和间隔
debug_logging_supported 1 个八位字节 支持从控制器记录二进制文件调试信息
LE_address_generation_offloading_support
(已废弃)
1 个八位字节 0 = 不支持
1 = 支持

在 v0.98 之后预留
此参数已在 Google 功能规范 v0.98 及更高版本中废弃,并由 BT 规范 4.2 及更高版本中提供的“隐私功能”取代
A2DP_source_offload_capability_mask 4 个八位字节 支持的编解码器类型的位掩码
位 0 - SBC
位 1 - AAC
位 2 - APTX
位 3 - APTX HD
位 4 - LDAC
位 5-31 为预留位
bluetooth_quality_report_support 1 个八位字节 支持报告蓝牙质量事件
0 = 不能
1 = 能
dynamic_audio_buffer_support 4 个八位字节 支持蓝牙控制器中的动态音频缓冲区
支持的编解码器类型的位掩码
位 0 - SBC
位 1 - AAC
位 2 - APTX
位 3 - APTX HD
位 4 - LDAC
位 5-31 为预留位

批处理扫描结果

我们的一个设计目标是改善蓝牙 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)。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 服务数据
0x08 - APCF 传输发现服务
0x09 - APCF 通告类型过滤器
0x10 ~ 0xAF - 预留以供日后使用
0xB0 ~ 0xDF - 预留以供供应商使用
0xE0 ~ 0xFE - 预留以供日后使用
0xFF - APCF 读取扩展功能

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

返回参数 大小 用途
Status 1 个八位字节 返回状态
APCF_opcode 1 个八位字节 0x00 - APCF 启用
0x01 - APCF 设置过滤参数
0x02 - APCF 广播地址
0x03 - APCF 服务 UUID
0x04 - APCF 服务请求 UUID
0x05 - APCF 本地名称
0x06 - APCF 制造商数据
0x07 - APCF 服务数据
0x08 - APCF 传输发现服务
0x09 - APCF 通告类型过滤器
0x10 ~ 0xAF - 预留以供日后使用
0xB0 ~ 0xDF - 预留以供供应商使用
0xE0 ~ 0xFE - 预留以供日后使用
0xFF - 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:设置为启用服务数据检查
位 7:设置为启用传输发现服务检查
位 8:设置为启用通告类型检查
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_modeon_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_immediatelybatchonFoundOnLost 值与 OnFound 相关,具体体现在,该值丢失后,会紧跟 OnFound

以下处理流程介绍了概念模式:

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

RSSI 级别阈值(高和低)能够控制帧何时可见以进行过滤器处理,即使控制器收到有效的包也是如此。在传送模式设置为“立即”或“批处理”时,系统会考虑某个帧的 RSSI,以进一步进行控制器处理。不同的应用需要不同的报告和批处理行为。这样一来,多个应用能够同时直接报告和/或批处理固件中的结果。例如,一个应用已启用批量扫描,之后另一个应用发起常规 LE 扫描。在发起批量扫描之前,框架/应用会设置相应的过滤器。之后,当第二个应用发起常规扫描时,之前的批处理操作将继续。不过,由于常规扫描,这类似于从概念上添加 null 过滤器(以及所有现有过滤器)和 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 大小可变 本地名称字符串。

备注:
  • 目前本地名称字符串中的字符数上限为 29
  • 执行清除操作 (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 大小可变 制造商数据字符串。

备注:
  • 目前本地名称字符串中的字符数上限为 29
  • 执行清除操作 (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 大小可变 服务数据字符串。

备注:
  • 目前本地名称字符串中的字符数上限为 29
  • 执行清除操作 (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 个八位字节 服务数据表中仍可用的空闲条目数

LE_APCF_Command:ad_type_sub_cmd

该子命令用于添加或删除芯片过滤的某个通告类型,或清除芯片过滤的某个通告类型列表。请使用 read_extended_features_sub_cmd 检查是否支持此命令。

子 OCF:0x09

子命令参数 大小 用途
APCF_Action 1 个八位字节 0x00 - 添加
0x01 - 删除
0x02 - 清除
执行删除操作会删除指定过滤器中的指定通告类型。
执行清除操作会清除指定过滤器中的所有通告类型。
APCF_Filter_Index 1 个八位字节 过滤器索引 (0, max_filter-1)
APCF_AD_TYPE 1 个八位字节 要添加到列表或从中删除的通告类型。当 APCF_Action 的值为 0x02(清除)时,请忽略
APCF_AD_DATA_Length 大小可变 0x00 - 表示不过滤数据内容
APCF_Action 为 0x02(清除)时,请忽略
APCF_AD_DATA 大小可变 当 APCF_Action 的值为 0x02(清除)时,请忽略
APCF_AD_DATA_MASK 大小可变 当 APCF_Action 的值为 0x02(清除)时,请忽略
其长度应与 APCF_AD_DATA 相同。

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

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

LE_APCF_Command:read_extended_features_sub_cmd

此子命令用于读取扩展的 APCF 功能。

子 OCF:0xFF

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

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
APCF_opcode 1 个八位字节 0xFF - APCF_Read_Extended_Features
APCF_extended_features 2 个八位字节

支持的扩展功能的位掩码:

  • 位 0:支持传输发现服务过滤器
  • 位 1:支持通告类型过滤器
  • 位 2 ~ 15:预留以供日后使用

位的值

  • 0 = 不支持
  • 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 扩展设置扫描参数命令

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

基础参考:蓝牙核心 5.2 规范,第 2493 页(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

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

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

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

A2DP 硬件分流支持

A2DP 分流功能支持将 A2DP 音频编码过程分流到连接至 BT 控制器的音频处理器。编码音频数据流直接从音频处理器传送到 BT 控制器,整个过程无需 BT 主机参与。BT 主机仍负责配置和控制 A2DP 会话。

OCF:0x15D

启动 A2DP 分流

子 OCF:0x01

可使用此命令配置 A2DP 分流过程和启动 A2DP 流。

命令参数 大小 用途
Codec 4 个八位字节 指定编解码器类型
0x01 - SBC
0x02 - AAC
0x04 - APTX
0x08 - APTX HD
0x10 - LDAC
Max_Latency 2 个八位字节 允许的最长延迟时间(以毫秒为单位)。值为零会禁用刷新。
SCMS-T_Enable 2 个八位字节 八位字节 0:支持添加 SCMS-T 标头的标记。
  • 0x00 - 不包含 SCMS-T 标头。
  • 0x01 - 包含 SCMS-T 标头。

八位字节 1:SCMS-T 标头的值(启用 SCMS-T 标头时)。

Sampling_Frequency 4 个八位字节 0x01 - 44100 Hz
0x02 - 48000 Hz
0x04 - 88200 Hz
0x08 - 96000 Hz
Bits_Per_Sample 1 个八位字节 0x01 - 每个样本 16 位
0x02 - 每个样本 24 位
0x04 - 每个样本 32 位
Channel_Mode 1 个八位字节 0x01 - 单声道
0x02 - 立体声
Encoded_Audio_Bitrate 4 个八位字节 编码音频比特率,以每秒传输的位数表示。
0x00000000 - 未指定或未使用音频比特率。
0x00000001 - 0x00FFFFFF - 编码音频比特率,以每秒传输的位数表示。
0x01000000 - 0xFFFFFFFF - 预留。
Connection_Handle 2 个八位字节 正在配置的 A2DP 连接的连接句柄
L2CAP_Channel_ID 2 个八位字节 要用于此 A2DP 连接的 L2CAP 通道 ID
L2CAP_MTU_Size 2 个八位字节 包含编码音频数据包的 L2CAP MTU 的大小上限
Codec_Information 32 个八位字节 编解码器专属信息。

SBC 编解码器

请参阅 A2DP v1.3 中关于 SBC 编解码器专属信息元素的介绍。
八位字节 0:块长度|子带|分配方法
八位字节 1:最小位池值
八位字节 2:最大位池值
八位字节 3:采样频率|声道模式
八位字节 4-31:预留

AAC 编解码器

请参阅 A2DP v1.3 中关于 AAC 编解码器专属信息元素的介绍。
八位字节 0:对象类型
八位字节 1; b7:VBR
八位字节 2-31:预留

LDAC 编解码器

八位字节 0-3:供应商 ID
0x0000012D

八位字节 4-5:编解码器 ID
0x00AA - LDAC
其他所有值均预留

八位字节 6:比特率指数:
0x00 - 高
0x01 - 中
0x02 - 低
0x03 - 0x7E - 预留
0x7F - ABR(自适应比特率)
0x80 - 0xFF - 预留

八位字节 7:LDAC 声道模式
0x01 - 立体声
0x02 - 双声道
0x04 - 单声道
其他值预留

八位字节 8-31:预留

其他所有编解码器

八位字节 0-31:预留

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Sub_Opcode 1 个八位字节 0x0 - 启动 A2DP 分流

停止 A2DP 分流

子 OCF:0x02

此命令用于停止 A2DP 分流数据流。

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

没有为此命令指定任何参数。

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Sub_Opcode 1 个八位字节 0x02 - 停止 A2DP 分流

蓝牙质量报告命令

BT 质量报告命令功能会在蓝牙控制器中启动质量报告机制,向主机报告蓝牙质量事件。您可以启用四个选项:

  • 质量监控模式:控制器会定期向主机发送“链路质量”相关的 BQR 子事件。
  • 接近 LSTO:如果超过链路监管超时 (LSTO) 值的一半时间没有从连接的 BT 设备收到数据包,控制器就会向主机报告“接近 LSTO”事件。
  • A2DP 音频断断续续:如果控制器检测到导致音频断断续续的因素,就会向主机报告“A2DP 音频断断续续”事件。
  • (e)SCO 语音断断续续:如果控制器检测到导致语音断断续续的因素,就会向主机报告“(e)SCO 语音断断续续”事件。
  • 根缺陷:当 HAL 或控制器遇到致命错误并需要重启蓝牙时,控制器会向堆栈发送此事件。
  • LMP/LL 消息跟踪记录:控制器将与远程设备握手的 LMP/LL 消息发送至主机。
  • 蓝牙多配置文件/共存的调度跟踪记录:控制器会将其处理 2.4 Ghz 频段内多个蓝牙配置文件和无线共存的调度信息发送至主机。
  • 控制器调试信息机制:启用后,控制器可以通过控制器调试信息子事件自动向主机报告调试日志记录信息。

OCF:0x15E

命令参数 大小 用途
BQR_Report_Action 1 个八位字节 添加、删除或全部清除 BQR_Quality_Event_Mask 参数中设置的质量事件报告的操作。

0x00 - 添加
0x01 - 删除
0x02 - 清除

执行删除操作将清除特定质量事件报告。
执行清除操作将清除所有质量事件报告(可以忽略 BQR_Quality_Event_Mask 参数)。

BQR_Quality_Event_Mask 4 个八位字节 所选质量事件报告的位掩码。

位 0:设置为启用质量监控模式。
位 1:设置为启用“接近 LSTO”事件。
位 2:设置为启用“A2DP 音频断断续续”事件。
位 3:设置为启用“(e)SCO 语音断断续续”事件。
位 4:设置为启用“根缺陷”事件。
位 5 ~ 15:预留。
位 16:设置为启用“LMP/LL”消息跟踪记录。
位 17:设置为启用“蓝牙多链路/共存”调度跟踪记录。
位 18:设置为启用“控制器调试信息”机制。
位 19 ~ 31:预留。

BQR_Minimum_Report_Interval 2 个八位字节 指定报告所选质量事件的最小时间间隔。控制器固件在指定的时间间隔内不应报告下一个事件。该时间间隔应针对所添加的质量事件分别设置。

单位:毫秒
默认值:0(对于此间隔的设置没有限制。)
范围:0~65535 毫秒

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Current_Quality_Event_Mask 4 个八位字节 表示当前位掩码设置。
位 0:启用质量监控模式。
位 1:启用“接近 LSTO”事件报告。
位 2:启用“A2DP 音频断断续续”事件报告。
位 3:启用“(e)SCO 语音断断续续”事件报告。
位 4:启用“根缺陷”事件报告。
位 5 ~ 15:预留。
位 16:启用“LMP/LL”消息跟踪记录。
位 17:启用“蓝牙多链路/共存”调度跟踪记录。
位 18:启用“控制器调试信息”机制。
位 19 ~ 31:预留。

动态音频缓冲区命令

动态音频缓冲区会根据各种情况更改蓝牙控制器中的音频缓冲区空间,从而减少音频干扰。

OCF:0x15F

获取音频缓冲区时间功能

子 OCF:0x01

使用此命令从蓝牙控制器中获取音频缓冲区时间功能。

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

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Dynamic_Audio_Buffer_opcode 1 个八位字节 0x01 - 获取音频缓冲区时间
Audio_Codec_Type_Supported 4 个八位字节 支持的编解码器类型的位掩码
位 0 - SBC
位 1 - AAC
位 2 - APTX
位 3 - APTX HD
位 4 - LDAC
位 5-31 为预留位
Audio_Codec_Buffer_Default_Time_For_Bit_0 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 0 编解码器类型的默认缓冲区时间。
如果不支持位 0 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Maximum_Time_For_Bit_0 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 0 编解码器类型的最大缓冲区时间。
如果不支持位 0 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Minimum_Time_For_Bit_0 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 0 编解码器类型的最小缓冲区时间。
如果不支持位 0 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Default_Time_For_Bit_1 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 1 编解码器类型的默认缓冲区时间。
如果不支持位 1 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Maximum_Time_For_Bit_1 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 1 编解码器类型的最大缓冲区时间。
如果不支持位 1 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Minimum_Time_For_Bit_1 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 1 编解码器类型的最小缓冲区时间。
如果不支持位 1 编解码器类型,则此值应为 0。
单位:毫秒
...... ...... ......
Audio_Codec_Buffer_Default_Time_For_Bit_31 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 31 编解码器类型的默认缓冲区时间。
如果不支持位 31 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Maximum_Time_For_Bit_31 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 31 编解码器类型的最大缓冲区时间。
如果不支持位 31 编解码器类型,则此值应为 0。
单位:毫秒
Audio_Codec_Buffer_Minimum_Time_For_Bit_31 2 个八位字节 Audio_Codec_Type_Supported 中指定的位 31 编解码器类型的最小缓冲区时间。
如果不支持位 31 编解码器类型,则此值应为 0。
单位:毫秒

设置音频缓冲区时间

子 OCF:0x02

使用此命令设置蓝牙控制器的音频缓冲区时间。

命令参数 大小 用途
Audio_Codec_Buffer_Time 2 个八位字节 当前所用编解码器请求的音频缓冲区时间。
单位:毫秒

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

返回参数 大小 用途
Status 1 个八位字节 命令完成状态
Dynamic_Audio_Buffer_opcode 1 个八位字节 0x02 - 设置音频缓冲区时间
Audio_Codec_Buffer_Time 2 个八位字节 蓝牙控制器中的当前音频缓冲区时间。
单位:毫秒

HCI 事件(特定于供应商)

某些情况下需要特定于供应商的 HCI 事件。请参考蓝牙核心 5.2 规范第 1897 页的图 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 的调试数据

蓝牙质量报告子事件

此事件指示发生了以下其中一种情况:发生了蓝牙质量事件、控制器上传了 LMP/LL 消息跟踪记录和蓝牙多链路/共存调度跟踪记录,或控制器转储了调试信息数据。

子事件参数 大小 用途
Quality_Report_Id 1 个八位字节 0x01:监控模式下的质量报告。
0x02:接近 LSTO。
0x03:A2DP 音频断断续续。
0x04:(e)SCO 语音断断续续。
0x05 ~ 0xFF:预留。
Packet_Types 1 个八位字节 0x01:ID
0x02:NULL
0x03:POLL
0x04:FHS
0x05:HV1
0x06:HV2
0x07:HV3
0x08:DV
0x09:EV3
0x0A:EV4
0x0B:EV5
0x0C:2-EV3
0x0D:2-EV5
0x0E:3-EV3
0x0F:3-EV5
0x11:DH1
0x12:DM3
0x13:DH3
0x14:DM5
0x15:DH5
0x16:AUX1
0x17:2-DH1
0x18:2-DH3
0x19:2-DH5
0x1A:3-DH1
0x1B:3-DH3
0x1C:3-DH5
0x1D ~ 0xFF:预留。
Connection_Handle 2 个八位字节 连接句柄。
Connection_Role 1 个八位字节 连接的执行角色。
0x00:中心设备
0x01:外围设备
0x02 ~ 0xFF:预留。
TX_Power_Level 1 个八位字节 指定 Connection_Handle 的当前传输功率电平。

该值应与控制器对 HCI_Read_Transmit_Power_Level HCI 命令的响应相同。

RSSI 1 个八位字节 [以 dBm 为单位]

指定的 Connection_Handle 的接收信号强度指示 (RSSI) 值。
该值应为接收器绝对信号强度值。
范围:-127 到 +20

SNR 1 个八位字节 [以 dB 为单位]

指定的 Connection_Handle 的信噪比 (SNR) 值。
控制器应提供链路使用的所有频道的平均 SNR。

Unused_AFH_Channel_Count 1 个八位字节 表示 AFH_channel_map 中未使用的通道数。
0x4F ~ 0xFF:预留。
AFH_Select_Unideal_Channel_Count 1 个八位字节 表示受到干扰且质量不佳但仍为 AFH 选择的通道数。
蓝牙规范允许的最小通道数为 20,因此即使所有 79 个通道都受到干扰且质量不佳,控制器仍需要为 AFH 选择至少 20 个通道。
LSTO 2 个八位字节 当前的链路监管超时设置。
时间 = N * 0.625 毫秒
时间范围:0.625 毫秒至 40.9 秒
Connection_Piconet_Clock 4 个八位字节 指定的 Connection_Handle 的 Piconet 时钟。
该值应与控制器对 HCI_Read_Clock HCI 命令(将参数“Which_Clock”设为 0x01,即 Piconet 时钟)的响应相同。
单位:N * 0.3125 毫秒(1 个蓝牙时钟)
Retransmission_Count 4 个八位字节 自上次事件后的重新传输次数。
此计数应在向主机报告事件后清零。
No_RX_Count 4 个八位字节 自上次事件后没有 RX 计数。
如果在预定时段没有收到数据包或者收到的数据包被破坏,计数会增加。
此计数应在向主机报告事件后清零。
NAK_Count 4 个八位字节 自上次事件后的 NAK(否定应答)计数。
此计数应在向主机报告事件后清零。
Last_TX_ACK_Timestamp 4 个八位字节 上次 TX ACK 的时间戳,根据 Piconet Central 蓝牙时钟 (CLK) 确定。
单位:N * 0.3125 毫秒(1 个蓝牙时钟)
Flow_Off_Count 4 个八位字节 自上次事件后控制器接收流程关闭 (STOP) 的次数。
此计数应在向主机报告事件后清零。
Last_Flow_On_Timestamp 4 个八位字节 上次流程开启 (GO) 的时间戳,根据 Piconet Central 蓝牙时钟 (CLK) 确定。
单位:N * 0.3125 毫秒(1 个蓝牙时钟)
Buffer_Overflow_Bytes 4 个八位字节 [以字节为单位]

自上次事件后的缓冲区溢出计数。
控制器会计算丢弃的数据字节数。
此计数应在向主机报告事件后清零。

Buffer_Underflow_Bytes 4 个八位字节 [以字节为单位]

自上次事件后的缓冲区下溢计数。
此计数应在向主机报告事件后清零。

bdaddr 6 个八位字节 远程设备地址
cal_failed_item_count 1 个八位字节 校准失败的项数
供应商特定参数 (参数总长度 - 49)*八位字节数 便于控制器供应商获取更多供应商特定参数。

子事件代码 = 0x58 [Quality_Report_Id = 0x05,根缺陷事件]

此事件表示蓝牙 HAL 或控制器遇到严重错误,需要蓝牙堆栈记录这种情况并重启。在任何情况下,控制器都必须将 Root_Inflammation_Event 发送到蓝牙堆栈,然后再发送调试信息事件的第一个 fragment。

Error_Code 参数包含从 HAL/Controller 报告的错误代码;如果是芯片组供应商特定错误,则错误代码为 0。Vendor_Specific_Error_Code 包含来自 HAL/Controller 的芯片组供应商特定错误代码。如果参数 Error_Code 不为 0,则应设置为 0。参数 Error_Code 和 Vendor_Specific_Error_Code 的值不能同时为 0。

子事件参数 大小 用途
Quality_Report_Id 1 个八位字节 0x00 ~ 0x04:预留。
0x05:根缺陷。
0x06 ~ 0xFF:预留。
Error_Code 1 个八位字节 0x00:包含芯片组供应商特定错误代码。
0x01 ~ 0xFF:发生了控制器故障。请参阅蓝牙规范 [第 2 卷] D 部分“错误代码”,获取错误代码列表和说明。
Vendor_Specific_Error_Code 1 个八位字节 0x00:不包含芯片组供应商特定错误代码。
0x01 ~ 0xFF:芯片组供应商特定错误代码。
供应商特定参数 (参数总长度 - 4)*八位字节数 便于控制器供应商获取更多供应商特定参数。
子事件参数 大小 用途
Quality_Report_Id 1 个八位字节 0x00 ~ 0x10:预留。
0x11:LMP/LL 消息跟踪记录。
0x12:蓝牙多链路/共存调度跟踪记录。
0x13:控制器调试信息数据转储。
0x14 ~ 0xFF:预留。
Connection_Handle 2 个八位字节 连接句柄。
供应商特定参数 (参数总长度 - 4)*八位字节数 LMP 消息跟踪记录的供应商特定格式、蓝牙多链路/共存调度跟踪记录和控制器调试信息数据转储。

多通告者支持

多通告者支持的目标如下:

  • 能够支持多个通告 (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

基础参考:蓝牙核心 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

基础参考:蓝牙核心 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

基础参考:蓝牙核心 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

基础参考:蓝牙核心 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

基础参考:蓝牙核心 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 个八位字节 完成当前操作后可用的 IRL 列表条目 [max_irk_list_sz]

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 的当前已解析的可解析私有地址