【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 Mask

Bluetooth HCI Command - LE Set Event Mask
    Command 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: 8
    LE 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 Repo
        0000 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）

2. Bit 60~63：保留位

5. aosp中使用流程示意

  static constexpr uint64_t kDefaultEventMask = 0x3dbfffffffffffff;
  static constexpr uint64_t kDefaultLeEventMask = 0x000000004d02fe7f;
  
// system/gd/hci/controller.cc

struct 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 位。
• 部分位在较早版本的蓝牙控制器中可能不支持。