企业官网建设流程全解析

ESP-IDF 蓝牙 HCI 厂商特定（VS）命令与事件全解析：从 OCF 定义到控制器实现

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

本文以乐鑫 ESP-IDF 开源仓库中的官方文档 docs/zh_CN/api-reference/bluetooth/bt_vhci.rst 为核心骨架，系统梳理乐鑫蓝牙控制器对外暴露的厂商特定（Vendor-specific）HCI 命令与事件——包括蓝牙主机专用自定义命令/事件、以及仅供乐鑫内部使用的调试命令/事件。读完本文，你将掌握这些 VS 命令/事件的宏定义与取值、各芯片平台的差异、对应的初始化函数（如esp_ble_internalTestFeaturesEnable(true)），并了解它们在 components/bt 源码中的底层实现，从而能够在阅读蓝牙日志、排查控制器行为或进行射频/协议调试时准确识别这些厂商扩展指令。

HCI VS 命令的背景：为什么需要厂商特定扩展

蓝牙 HCI（Host Controller Interface）是蓝牙主机（Host）与控制器（Controller）之间的标准通信协议。除了蓝牙核心规范定义的命令外，控制器厂商可以在 OGF（Opcode Group Field）的厂商特定区间（0x3F）内自定义命令，这类命令统称为HCI VS（Vendor-specific）命令。它们通过OCF（Opcode Command Field）区分具体命令，而 VS 事件则通过EVTCODE + SUBCODE组合识别。

在 ESP-IDF 中，这些宏统一以ESP_BT_VS_前缀定义，按芯片型号分散存放于 components/bt/include/esp32/include/esp_bt_vs.h、components/bt/include/esp32c6/include/esp_bt_vs.h、components/bt/include/esp32c2/include/esp_bt_vs.h 等头文件中。文档中通过.. doxygendefine::指令直接引用这些头文件中的宏定义，因此本文给出的 OCF/SUBCODE 数值均与对应头文件中的#define一一对应。

适用范围与启用前提（务必先读）

根据官方文档的明确说明，所有乐鑫蓝牙主机专用的自定义 HCI 命令与事件具有以下共性约束：

• 仅适用于乐鑫的蓝牙主机，即 ESP-Bluedroid 主机或 ESP-NimBLE 主机；
• 如果使用非 ESP 主机或通过HCI UART连接外部主机，这些命令/事件将默认禁用，除非应用程序显式调用了对应的初始化函数；
• 这些初始化函数及附加的自定义 HCI 命令/事件仅供乐鑫蓝牙主机内部使用；
• 应用程序开发者不应在自己的应用程序中调用这些初始化函数——这是文档反复强调的红线。

从源码看，初始化函数由控制器侧导出。例如在 components/bt/controller/esp32/bt.c 中声明了extern void scan_stack_enableAdvFlowCtrlVsCmd(bool en);，并在第 1764 行与 1815 行分别以true/false调用；components/bt/controller/esp32c6/ble.c 中同样声明并在第 123 行调用该函数。这些调用点通常位于控制器初始化路径，由蓝牙协议栈在内部完成开关，而非留给应用层。

乐鑫蓝牙主机专用自定义 HCI 命令

各芯片平台支持矩阵

官方文档按芯片平台划分了不同的命令集合，完整继承如下：

ESP32（经典蓝牙 + BLE 双模）支持：

ESP32-C3 / ESP32-S3 支持：上表中除ESP_BT_VS_SET_COEX_STATUS_OCF与ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF外的全部命令，另加ESP_BT_VS_ENABLE_CSA2_OCF（OCF0x0112，初始化函数chanSel_stack_enableSetCsaVsCmd(true)）。

ESP32-C2 支持：ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF、ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF、ESP_BT_VS_CLR_LEGACY_ADV_OCF、ESP_BT_VS_ENABLE_CSA2_OCF、ESP_BT_VS_SET_LE_VENDOR_EVTS_MASK_OCF（OCF0x0116，初始化函数hci_stack_enableSetVsEvtMaskVsCmd(true)）。

ESP32-C5 / ESP32-C6 / ESP32-H2 / ESP32-H21 / ESP32-C61 / ESP32-H4 / ESP32-S31 支持：命令集最全，除基础命令外还包括多连接调度、功率控制、日志等进阶扩展：

注：部分芯片（如 ESP32-S31）头文件中还包含ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF（0x0182）等经典蓝牙相关命令，具体以 components/bt/include/esp32s31/include/esp_bt_vs.h 为准。

关键命令的参数结构（源码级）

以 components/bt/include/esp32/include/esp_bt_vs.h 为基准，这些命令对应的参数结构体定义如下，可直接用于解析命令载荷：

/* 0x0081：echo 测试命令参数 */ struct bt_hci_vs_common_echo { uint8_t echo; /*!< echo data */ }; /* 0x0082：设置/清除共存状态 */ struct bt_hci_vs_set_coex_status { uint8_t type; /*!< WIFI、BLE 或 BT */ uint8_t op; /*!< clear 或 set status */ uint8_t status; /*!< WIFI、BLE 或 BT status */ }; /* 0x0108：配置扫描去重例外列表 */ struct bt_hci_vs_update_exc_list { uint8_t subcode; /*!< Add、remove 或 clear exception list */ uint32_t type; /*!< device type */ uint8_t device_info[6]; /*!< device information */ }; /* 0x0109：初始化广播报告流控 */ struct bt_hci_vs_init_adv_flow_ctrl { uint8_t enable; /*!< 使能 ADV flow control */ uint16_t num; /*!< ADV buffer 最大值 */ uint16_t adv_lost_threshold;/*!< 触发 ADV lost 事件的阈值 */ }; /* 0x010A：更新广播报告流控数量 */ struct bt_hci_vs_update_adv_flow_ctrl { uint16_t num; /*!< 已处理的 ADV report 数量 */ }; /* 0x0182：设置经典蓝牙最小加密密钥长度 */ struct bt_hci_vs_set_min_enc_key_size { uint8_t size; /*!< 最小加密密钥长度 */ };

新平台（ESP32-C5/C6/H2/H21/C61/H4/S31）在 components/bt/include/esp32c6/include/esp_bt_vs.h 中进一步定义了去重列表参数、多连接调度、自动功率控制等结构体，例如：

/* 0x010D：设置去重列表参数 */ struct bt_hci_vs_ble_set_dup_params { uint8_t dup_mode; /*!< Duplicate mode */ uint8_t dup_ad_type; /*!< Duplicate data type */ uint16_t ring_list_max_num; /*!< Duplicate list size */ }; /* 0x010F：多连接优化（连接间隔的最大公约数） */ struct bt_hci_vs_ble_enable_arrangement { uint32_t common_factor; /*!< 连接间隔的最大公约数 */ uint8_t enable; /*!< 使能或禁用 */ }; /* 0x0111：自动功率控制 RSSI 阈值（区分 1M/2M/s2 coded/s8 coded 四种 PHY） */ struct bt_hci_vs_ble_set_pcl_rssi_thresh { uint16_t conn_handle; uint8_t rssi_thresh_min_1M; uint8_t rssi_thresh_max_1M; uint8_t rssi_thresh_min_2M; uint8_t rssi_thresh_max_2M; uint8_t rssi_thresh_min_s2coded; uint8_t rssi_thresh_max_s2coded; uint8_t rssi_thresh_min_s8coded; uint8_t rssi_thresh_max_s8coded; }; /* 0x0112：选择信道选择算法 #2（CSA2） */ struct bt_hci_vs_ble_csa_enable { uint8_t csa2_select; /*!< 选择 CSA2 */ }; /* 0x0116：设置 BLE 厂商事件掩码 */ struct bt_hci_vs_ble_set_vs_evts_mask { uint32_t evt_masks; /*!< BLE vendor events Mask */ };

这些结构体揭示了命令的实战用途：0x0109/0x010A用于控制高密度扫描场景下的广播报告流控，0x010D/0x010E用于管理扫描去重与例外列表，0x010F/0x0110用于多从机连接场景下的调度优化，0x0111用于按 PHY 细分 RSSI 门限的自动功率控制。

乐鑫蓝牙主机专用自定义 HCI 事件

对应地，控制器会通过 VS 事件向主机上报状态。官方文档按芯片列出的事件如下：

芯片支持情况（与文档一致）：

• ESP32：ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE、ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODE；
• ESP32-C3 / ESP32-S3：ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE；
• ESP32-C2：ESP_BT_VS_LE_CONN_SCAN_REQ_RXED_EVT_SUBCODE、ESP_BT_VS_LE_CHAN_UPDATE_COMP_EVT_SUBCODE、ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE、ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE；
• ESP32-C5 / C6 / H2 / H21 / C61 / H4：同上四个事件；
• ESP32-S31：上述四个事件外加ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODE。

对应的事件载荷结构体（见 components/bt/include/esp32c6/include/esp_bt_vs.h）：

/* ADV lost 事件：流控丢弃的广播报告数量 */ struct bt_hci_vs_le_adv_lost_evt { uint32_t nb_lost; /*!< 被丢弃的 ADV report 数量 */ }; /* SCAN_REQ / CONN_IND 接收事件 */ struct bt_hci_vs_le_conn_scan_req_rxed_evt { uint8_t evt_type; /*!< 0: SCAN_REQ; 1: CONN_IND */ uint8_t handle; /*!< Advertisement handle */ uint8_t peer_addr_type; /*!< Peer address type */ uint8_t peer_addr[6]; /*!< Peer address */ }; /* 信道映射更新完成事件 */ struct bt_hci_vs_le_chan_update_comp_evt { uint8_t status; /*!< Controller error code */ uint16_t handle; /*!< Connection handle */ uint8_t ch_map[5]; /*!< 更新后的 channel map */ };

其中ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE（0xC3）无参数。值得注意的是，在较新平台（如 ESP32-C6/H2）上0xC3同时被用于ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE（内部调试事件，见下文），解析时需结合 EVTCODE 与上下文区分。

乐鑫内部调试 HCI 命令与事件

文档明确警告：以下调试命令/事件已包含在乐鑫低功耗蓝牙（BLE）控制器的预编译库中，但不会被链接进应用程序二进制文件，除非应用调用esp_ble_internalTestFeaturesEnable(true)。该开关仅限乐鑫内部使用，应用程序开发者不应调用。

BLE 内部测试命令（OCF0x0113）

ESP_BT_VS_CFG_TEST_RELATED_OCF的值为0x0113，其下通过子码（SUBCODE）区分具体测试动作。以 ESP32 为例的基础子码：

在 ESP32-C3/S3 上额外增加SET_PREF_CODED_SUBCMD（0x02）、SET_DEFAULT_PRIV_MODE_SUBCMD（0x03）、SET_TXPWR_LVL_ENH_SUBCMD（0x0A）、GET_TXPWR_LVL_ENH_SUBCMD（0x0B）、ENABLE_CCA_SUBCMD（0x0E）、SET_AUX_ADV_OFFSET_SUBCMD（0x25）等；ESP32-C2 及更新的 C5/C6/H2/H21/C61/H4/S31 平台子码体系进一步扩充，涵盖SET_CCA_WIN_SUBCMD、READ_CCA_DATA_SUBCM、SKIP_LIGHT_SLEEP_CHECK_SUBCMD、SET_WAKEUP_OVERHEAD_SUBCMD、GET_ADV_MIN_ITVL_SUBCMD、SET_CONN_PHY_TXPWR_SUBCMD、RESTART_SUBCMD、ENABLE_RECODE_RX_STATE_SUBCMD、GET_RECODE_CNT_SUBCMD、CLR_RECODE_CNT_SUBCMD、INIT_FLEXIBLE_MODE_SUBCMD、ENABLE_FLEXIBLE_MODE_SUBCMD、SET_FLEXIBLE_CONN/ADV/SCAN_ERR_SUBCMD、GET_TXED_CRCERR_SUBCMD、SET_SCH_RAND_MODE_SUBCMD、CHECK_MSYS_BUF_SUBCMD、UPDATE_BLE_TIMER/RTC_SUBCMD、SET_DIAG_IO_SUBCMD、SET_AGC_MAX_GAIN_SUBCMD、ENABLE_CHAN_ASSESS_SUBCMD等（完整列表见 components/bt/include/esp32c6/include/esp_bt_vs.h 与 components/bt/include/esp32c2/include/esp_bt_vs.h）。这些子码覆盖了射频测试（功率、CCA、访问地址、信道）、调度器诊断（backoff 上限、随机模式、接收 ADI）、内存/定时器调试（锁定内存、允许分配、BLE 定时器/RTC）等内部用途。

经典蓝牙（BR/EDR）调试命令

文档同时列出预编译库中包含的经典蓝牙调试命令（仅 ESP32 与 ESP32-S31 平台），这些命令需调用相应的初始化函数才会链接进二进制：

可见经典蓝牙调试命令主要围绕三类能力：AFH 自适应跳频（SET_AFH、SET_AFH_REPORTING_MODE、MASK_RMT_CHANNEL_CLASSIFICATION）、各状态发射功率读写（Page/Page Scan/Inquiry/新连接/ACL 实际 RSSI）、以及DM1 包与速率控制（WR_DM1_ENABLE、WR_AUTO_RATE_INIT）。ESP32-S31 平台在文档中额外列出ESP_BT_VS_DTM_TX_TEST_START_OCF、ESP_BT_VS_DTM_RX_TEST_START_OCF、ESP_BT_VS_DTM_TX_TEST_END_OCF、ESP_BT_VS_DTM_RX_TEST_END_OCF（直接测试模式）、ESP_BT_VS_PCA_OCF、ESP_BT_VS_DISCARD_PING_OCF、ESP_BT_VS_LMP_DBG_ENABLE_OCF、ESP_BT_VS_SEND_LMP_OCF、ESP_BT_VS_LMP_DBG_SAVE_OCF（LMP 层调试）等命令，具体取值以 components/bt/include/esp32s31/include/esp_bt_vs.h 为准。

内部调试 HCI 事件

内部调试事件同样存在于预编译库中，且仅在调用相应初始化函数后才可用：

• ESP32：ESP_BT_VS_AFH_CHG_EVT_SUBCODE（0x05）、ESP_BT_VS_CH_CLASSIFICATION_EVT_SUBCODE（0x06）、ESP_BT_VS_CH_CLASSIFICATION_REPORTING_MODE_EVT_SUBCODE（0x07），三者初始化函数均为bt_stack_enableAfhVsCmd(true)（定义见 components/bt/include/esp32/include/esp_bt_vs.h），用于上报 AFH 信道变化与信道分类结果；
• ESP32-C5 / C6 / C61 / H2 / H21 / H4：ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE（0xC3），用于上报 LE 控制器运行状态；
• ESP32-S31：同时具备上述两类事件，并额外包含ESP_BT_VS_LMP_RECEIVED_EVT_SUBCODE、ESP_BT_VS_LMP_TX_CFM_EVT_SUBCODE、ESP_BT_VS_LMP_DBG_ENTERED_EVT_SUBCODE三个 LMP 层调试事件。

开发者注意事项与调试建议

综合官方文档与源码，使用这些 VS 命令/事件时有几点实践建议：

1. 不要在产品代码中调用初始化函数。无论是esp_ble_internalTestFeaturesEnable(true)还是bt_stack_enableEchoVsCmd(true)等函数，均被明确标记为"乐鑫内部使用"。这些功能面向乐鑫工程师在 RF 测试、协议一致性调试与故障分析场景使用，普通应用调用可能导致控制器行为异常。
2. 区分命令归属：主机专用命令（OCF0x0081~0x0182区间、LE 主机事件）服务于 BLE 主机与控制器之间的功能协商（流控、去重、调度、功率控制）；内部调试命令（OCF0x0113及其子码、BR/EDR 的0x0181~0x0199）则服务于控制器自身的测试与诊断。
3. 按芯片查表：不同芯片的 VS 命令/事件集合差异显著，例如 ESP32 独有SET_COEX_STATUS与SET_MIN_ENC_KEY_SIZE，ESP32-C3/S3 独有COMMON_ECHO，而 C5/C6/H2/H21/C61/H4/S31 拥有最完整的去重、调度、功率控制命令集。调试时务必以目标芯片对应的components/bt/include/ /include/esp_bt_vs.h头文件为准。
4. 结合 HCI 日志分析：当使用idf.py monitor或蓝牙 Sniffer 抓取 HCI 包时，凡 OGF 为0x3F的命令、EVTCODE 为0x3E/0xFF的事件，均属于厂商特定扩展。对照本文表格中的 OCF/SUBCODE 即可快速识别其含义，进而推断控制器当前处于何种测试或调试模式。

总而言之，ESP-IDF 通过一套按芯片差异化裁剪的ESP_BT_VS_*宏体系，为蓝牙主机与控制器之间提供了丰富的厂商扩展通道：既有面向生产场景的广播流控、去重例外列表、CSA2 信道选择、多连接调度与自动功率控制等实用能力，也保留了仅供内部使用的射频与协议调试接口。理解这套宏定义与初始化开关的对应关系，是深入分析乐鑫蓝牙栈行为、定位扫描/连接/功耗类问题的第一步。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf