【android bluetooth 协议分析 01】【HCI 层介绍 4】【LeSetEventMask命令介绍】

在蓝牙协议栈中，HCI_LE_Set_Event_Mask 是一个主机控制接口（HCI）层的命令，属于 LE（Low Energy）控制指令集。该命令用于 配置控制器向主机报告哪些 LE 事件，以便主机能够根据需求控制被中断的事件种类。

---

1. 命令简介

• 名称：HCI_LE_Set_Event_Mask

• Opcode：0x2001 （OGF=0x08, OCF=0x0001）

• 参数：

  • LE_Event_Mask（8 字节）：每一位代表一个特定的 LE 事件，设置为 1 表示启用，设置为 0 表示禁用。

• 目的：告知控制器哪些 LE Meta Events 的子事件 需要上报给主机。

3	2025-04-24 15:55:53.349645	host	controller	HCI_CMD	12	Sent LE Set Event MaskBluetooth HCI Command - LE Set Event MaskCommand Opcode: LE Set Event Mask (0x2001)0010 00.. .... .... = Opcode Group Field: LE Controller Commands (0x08).... ..00 0000 0001 = Opcode Command Field: LE Set Event Mask (0x001)Parameter Total Length: 8LE Event Mask: 0x000000004d02fe7f, LE Request Peer SCA Complete, LE Terminate BIG Complete, LE Create BIG Complete, LE CIS Established, LE Extended Advertising Set Terminated, LE Periodic Advertising Sync Lost, LE Periodic Advertising Repo0000 0000 0000 0000 0000 0000 0000 0... .... .... .... .... .... .... .... .... = Reserved: 0x00000000.... .... .... .... .... .... .... .0.. .... .... .... .... .... .... .... .... = LE Subrate Changed: False.... .... .... .... .... .... .... ..0. .... .... .... .... .... .... .... .... = LE BIGInfo Advertising Report: False.... .... .... .... .... .... .... ...0 .... .... .... .... .... .... .... .... = LE Transmit Power Reporting: False.... .... .... .... .... .... .... .... 0... .... .... .... .... .... .... .... = LE Path Loss Threshold: False.... .... .... .... .... .... .... .... .1.. .... .... .... .... .... .... .... = LE Request Peer SCA Complete: True.... .... .... .... .... .... .... .... ..0. .... .... .... .... .... .... .... = LE BIG Sync Lost: False.... .... .... .... .... .... .... .... ...0 .... .... .... .... .... .... .... = LE BIG Sync Established: False.... .... .... .... .... .... .... .... .... 1... .... .... .... .... .... .... = LE Terminate BIG Complete: True.... .... .... .... .... .... .... .... .... .1.. .... .... .... .... .... .... = LE Create BIG Complete: True.... .... .... .... .... .... .... .... .... ..0. .... .... .... .... .... .... = LE CIS Request: False.... .... .... .... .... .... .... .... .... ...1 .... .... .... .... .... .... = LE CIS Established: True.... .... .... .... .... .... .... .... .... .... 0... .... .... .... .... .... = LE Periodic Advertising Sync Transfer Received: False.... .... .... .... .... .... .... .... .... .... .0.. .... .... .... .... .... = LE CTE Request Failed: False.... .... .... .... .... .... .... .... .... .... ..0. .... .... .... .... .... = LE Connection IQ Report: False.... .... .... .... .... .... .... .... .... .... ...0 .... .... .... .... .... = LE Connectionless IQ Report: False.... .... .... .... .... .... .... .... .... .... .... 0... .... .... .... .... = LE Channel Selection Algorithm: False.... .... .... .... .... .... .... .... .... .... .... .0.. .... .... .... .... = LE Scan Request Received: False.... .... .... .... .... .... .... .... .... .... .... ..1. .... .... .... .... = LE Extended Advertising Set Terminated: True.... .... .... .... .... .... .... .... .... .... .... ...0 .... .... .... .... = LE Extended Scan Timeout: False.... .... .... .... .... .... .... .... .... .... .... .... 1... .... .... .... = LE Periodic Advertising Sync Lost: True.... .... .... .... .... .... .... .... .... .... .... .... .1.. .... .... .... = LE Periodic Advertising Report: True.... .... .... .... .... .... .... .... .... .... .... .... ..1. .... .... .... = LE Periodic Advertising Sync Established: True.... .... .... .... .... .... .... .... .... .... .... .... ...1 .... .... .... = LE Extended Advertising Report: True.... .... .... .... .... .... .... .... .... .... .... .... .... 1... .... .... = LE PHY Update Complete: True.... .... .... .... .... .... .... .... .... .... .... .... .... .1.. .... .... = LE Direct Advertising Report: True.... .... .... .... .... .... .... .... .... .... .... .... .... ..1. .... .... = LE Enhanced Connection Complete: True.... .... .... .... .... .... .... .... .... .... .... .... .... ...0 .... .... = LE Generate DHKey Complete: False.... .... .... .... .... .... .... .... .... .... .... .... .... .... 0... .... = LE Read Local P-256 Public Key Complete: False.... .... .... .... .... .... .... .... .... .... .... .... .... .... .1.. .... = LE Data Length Change: True.... .... .... .... .... .... .... .... .... .... .... .... .... .... ..1. .... = LE Remote Connection Parameter Request: True.... .... .... .... .... .... .... .... .... .... .... .... .... .... ...1 .... = LE Long Term Key Request: True.... .... .... .... .... .... .... .... .... .... .... .... .... .... .... 1... = LE Read Remote Features Complete: True.... .... .... .... .... .... .... .... .... .... .... .... .... .... .... .1.. = LE Connection Update Complete: True.... .... .... .... .... .... .... .... .... .... .... .... .... .... .... ..1. = LE Advertising Report: True.... .... .... .... .... .... .... .... .... .... .... .... .... .... .... ...1 = LE Connection Complete: True[Response in frame: 4][Command-Response Delta: 0.601ms]

---

2. 事件屏蔽机制的意义

蓝牙控制器可能产生大量不同类型的事件，而主机并不一定需要全部处理。为了节省功耗和提高效率，主机通过设置 Event Mask 告诉控制器只报告感兴趣的事件

• 如果事件掩码中某个事件的对应 bit 为 1，则该事件将被允许生成；
• 如果为 0，则即使发生了该事件，控制器也不会通知主机。

---

3. LE Event Mask 和 Event Mask 的关系

为了使 LE 事件能被真正上报，必须满足两个条件：

1. LE Meta Event 的 主事件掩码 在 HCI_Set_Event_Mask 中被启用（即第 61 位，bit 61 = 1）；
2. 具体的 LE_Event_Mask 对应事件的位也必须为 1。

✅ 两层控制机制，双重确认：

• 一层是普通事件掩码 Event_Mask，控制是否允许 LE Meta Event 事件类型；

• 一层是 LE_Event_Mask，控制具体哪一类 LE 事件被允许。

---

4. LE_Event_Mask 各位含义（以 Bluetooth 5.3 为例）

下面是关于 HCI_LE_Set_Event_Mask 命令中 LE_Event_Mask（8字节，共64位） 每一位的详细说明表格。每一位对应一个具体的 LE Subevent（子事件） 类型，用于控制是否启用该事件的上报。此表基于 Bluetooth Core Specification v5.3，并结合其功能和典型应用场景进行了扩展说明。

---

1. LE_Event_Mask 每一位说明（Bit 0 ~ 34）

Bit	LE Subevent Type	功能描述	应用场景示例
0	LE Connection Complete	当 LE 连接成功建立时上报	建立连接时获取连接句柄和角色等信息
1	LE Advertising Report	接收到广告包时上报	主动扫描周边设备广告，如蓝牙广播扫描器
2	LE Connection Update Complete	LE连接参数更新完成时触发	动态调整连接参数以优化功耗/延迟
3	LE Read Remote Features Complete	读取远程设备的 LE 支持特性完成	检测远程是否支持特定功能（如延迟、2M PHY）
4	LE Long Term Key Request	请求主机提供 LTK（用于加密连接）	加密连接建立过程中，配对时使用
5	LE Remote Connection Parameter Request	远程设备请求更新连接参数	远程要求降低功耗，主机需回应
6	LE Data Length Change	数据长度更新完成时通知主机	动态调整数据包最大长度和时间（DLE）
7	LE Read Local P-256 Public Key Complete	生成本地 P-256 公钥完成	用于 LE Secure Connections（安全连接）
8	LE Generate DHKey Complete	DH 密钥生成完成（Diffie-Hellman）	安全连接中生成共享密钥
9	LE Enhanced Connection Complete	扩展连接建立完成（带扩展广告）	使用扩展广告进行连接（如蓝牙5+）
10	LE Directed Advertising Report	接收定向广告包时触发	精准设备识别，定向唤醒/广播
11	LE PHY Update Complete	PHY层速率（1M/2M/Coded）更新完成时触发	动态调整连接速率以提高速率或稳定性
12	LE Extended Advertising Report	接收到扩展广告包时触发	支持更大广告内容、低占空比广播
13	LE Periodic Advertising Sync Established	周期广播同步建立完成	接收周期广播（如蓝牙 AoA 或同步数据传输）
14	LE Periodic Advertising Report	接收周期广播内容时触发	设备周期性发送状态、传感器数据等
15	LE Periodic Advertising Sync Lost	周期广播同步丢失时触发	蓝牙广播信号丢失告警等
16	LE Scan Timeout	扫描超时时触发	用于控制扫描持续时间
17	LE Advertising Set Terminated	广播任务完成或被中止时触发	广播任务结束反馈，如定时广播场景
18	LE Scan Request Received	被动广告设备收到扫描请求时触发	主动响应扫描请求的设备，如身份认证
19	LE Channel Selection Algorithm	当前连接使用的信道选择算法通知	用于调试或优化蓝牙干扰问题
20	LE Connectionless IQ Report	AoA/AoD 中 IQ 采样报告（无连接）	蓝牙方向定位系统（RTLS）
21	LE Connection IQ Report	在连接中收集 IQ 数据	精准位置定位、轨迹追踪
22	LE CTE Request Failed	方向信息请求失败时触发	AoA/AoD 请求失败时诊断用
23	LE Periodic Advertising Sync Transfer Received	周期广播同步信息被成功接收	广播同步共享场景，如蓝牙中继转发
24	LE CIS Established	LE 音频连接（CIS）建立完成	用于 BLE Audio 音频流传输
25	LE CIS Request	请求建立 CIS 时触发	BLE Audio 的 stream 建立请求
26	LE Create BIG Complete	建立 Broadcast Isochronous Group 完成	广播音频流同步完成
27	LE Terminate BIG Complete	BIG 广播组终止时触发	结束广播音频任务
28	LE BIG Sync Established	BIG 同步完成	同步接收 BLE 音频广播
29	LE BIG Sync Lost	BIG 同步丢失	BLE 广播音频信号中断
30	LE Request Peer SCA Complete	获取远端 SCA（时钟精度）完成	用于判断远端时钟精度，影响同步通信
31	LE Path Loss Threshold	接收信号路径损耗越过阈值时触发	用于测距、离线检测等
32	LE Transmit Power Reporting	上报当前发射功率	动态功率控制场景
33	LE BIGInfo Advertising Report	接收 BIG 广播信息包	BIG 广播预览识别
34	LE Subrate Change	Subrate（低占空比）更新完成	提升 BLE Audio 低功耗传输性能

---

2. Bit 60~63：保留位

Bit	类型	描述
60~63	Reserved	为将来版本保留使用。设置为 1 时控制器应视为 0。

---

5. aosp中使用流程示意

  static constexpr uint64_t kDefaultEventMask = 0x3dbfffffffffffff;static constexpr uint64_t kDefaultLeEventMask = 0x000000004d02fe7f;// system/gd/hci/controller.ccstruct Controller::impl {void Start(hci::HciLayer* hci) {
...le_set_event_mask(kDefaultLeEventMask);set_event_mask(kDefaultEventMask);write_le_host_support(Enable::ENABLED, Enable::DISABLED);...
}void le_set_event_mask(uint64_t le_event_mask) {std::unique_ptr<LeSetEventMaskBuilder> packet = LeSetEventMaskBuilder::Create(le_event_mask);hci_->EnqueueCommand(std::move(packet), module_.GetHandler()->BindOnceOn(this, &Controller::impl::check_status<LeSetEventMaskCompleteView>));}

• 在初始化 Controller 模块时， 在 Controller::impl::Start 函数中就会调用 le_set_event_mask 函数去设置

---

6. 实际应用场景

在典型的 BLE 应用中：

• 如果设备只关心 接收广告包，可以仅启用 LE Advertising Report Event；
• 如果设备需要建立连接并更新参数，可启用 Connection Complete 和 Connection Update Complete；
• 若配对需要安全密钥协商，则还需启用密钥生成相关事件。

这样主机只处理需要的事件，减少功耗和不必要的中断。

---

7. 注意事项

• 控制器会忽略不支持的事件位，即使主机设置为 1。
• LE_Event_Mask 设置不生效的常见原因是 Event_Mask 中未启用 LE Meta Event 位。
• 部分位在较早版本的蓝牙控制器中可能不支持。