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-specificHCI 命令与事件——包括蓝牙主机专用自定义命令/事件、以及仅供乐鑫内部使用的调试命令/事件。读完本文你将掌握这些 VS 命令/事件的宏定义与取值、各芯片平台的差异、对应的初始化函数如esp_ble_internalTestFeaturesEnable(true)并了解它们在 components/bt 源码中的底层实现从而能够在阅读蓝牙日志、排查控制器行为或进行射频/协议调试时准确识别这些厂商扩展指令。HCI VS 命令的背景为什么需要厂商特定扩展蓝牙 HCIHost Controller Interface是蓝牙主机Host与控制器Controller之间的标准通信协议。除了蓝牙核心规范定义的命令外控制器厂商可以在 OGFOpcode Group Field的厂商特定区间0x3F内自定义命令这类命令统称为HCI VSVendor-specific命令。它们通过OCFOpcode 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 双模支持宏定义OCF初始化函数ESP_BT_VS_COMMON_ECHO_OCF0x0081bt_stack_enableEchoVsCmd(true)ESP_BT_VS_SET_COEX_STATUS_OCF0x0082bt_stack_enableCoexVsCmd(true)ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF0x0108advFilter_stack_enableDupExcListCmd(true)ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF0x0109scan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF0x010Ascan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_CLR_LEGACY_ADV_OCF0x010Cadv_stack_enableClearLegacyAdvVsCmd(true)ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF0x0182bt_stack_enableSecCtrlVsCmd(true)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_OCFOCF0x0112初始化函数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_OCFOCF0x0116初始化函数hci_stack_enableSetVsEvtMaskVsCmd(true)。ESP32-C5 / ESP32-C6 / ESP32-H2 / ESP32-H21 / ESP32-C61 / ESP32-H4 / ESP32-S31 支持命令集最全除基础命令外还包括多连接调度、功率控制、日志等进阶扩展宏定义OCF初始化函数ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF0x0108advFilter_stack_eanbleDupExcListCmd(true)ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF0x0109scan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF0x010Ascan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_CLR_LEGACY_ADV_OCF0x010Cadv_stack_enableClearLegacyAdvVsCmd(true)ESP_BT_VS_SET_DUP_LIST_PARAMS_OCF0x010DadvFilter_stack_eanbleDupExcListCmd(true)ESP_BT_VS_ENABLE_DUP_EXC_LIST_OCF0x010EadvFilter_stack_eanbleDupExcListCmd(true)ESP_BT_VS_ENABLE_ARRANGEMENT_OCF0x010Farr_stack_enableMultiConnVsCmd(true)ESP_BT_VS_SET_SCHED_ROLE_LEN_OCF0x0110arr_stack_enableMultiConnVsCmd(true)ESP_BT_VS_SET_PCL_RSSI_THRESH_OCF0x0111pcl_stack_enableSetRssiThreshVsCmd(true)ESP_BT_VS_ENABLE_CSA2_OCF0x0112chanSel_stack_enableSetCsaVsCmd(true)ESP_BT_VS_SET_LOG_PARAMS_OCF0x0114log_stack_enableLogsRelatedVsCmd(true)ESP_BT_VS_SET_LE_VENDOR_EVTS_MASK_OCF0x0116hci_stack_enableSetVsEvtMaskVsCmd(true)ESP_BT_VS_SET_CONST_PEER_SCA_OCF0x0118winWiden_stack_enableSetConstPeerScaVsCmd(true)注部分芯片如 ESP32-S31头文件中还包含ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF0x0182等经典蓝牙相关命令具体以 components/bt/include/esp32s31/include/esp_bt_vs.h 为准。关键命令的参数结构源码级以 components/bt/include/esp32/include/esp_bt_vs.h 为基准这些命令对应的参数结构体定义如下可直接用于解析命令载荷/* 0x0081echo 测试命令参数 */ 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选择信道选择算法 #2CSA2 */ 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 事件向主机上报状态。官方文档按芯片列出的事件如下宏定义EVTCODESUBCODE初始化函数ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE0x3E0xF0scan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODE0xFF0x03bt_stack_enableSecCtrlVsCmd(true)ESP_BT_VS_LE_CONN_SCAN_REQ_RXED_EVT_SUBCODE0xFF0xC0adv_stack_enableScanReqRxdVsEvent(true)ESP_BT_VS_LE_CHAN_UPDATE_COMP_EVT_SUBCODE0xFF0xC1conn_stack_enableChanMapUpdCompVsEvent(true)ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE0xFF0xC3sleep_stack_enableWakeupVsEvent(true)芯片支持情况与文档一致ESP32ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE、ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODEESP32-C3 / ESP32-S3ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODEESP32-C2ESP_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_SUBCODEESP32-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_SUBCODE0xC3无参数。值得注意的是在较新平台如 ESP32-C6/H2上0xC3同时被用于ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE内部调试事件见下文解析时需结合 EVTCODE 与上下文区分。乐鑫内部调试 HCI 命令与事件文档明确警告以下调试命令/事件已包含在乐鑫低功耗蓝牙BLE控制器的预编译库中但不会被链接进应用程序二进制文件除非应用调用esp_ble_internalTestFeaturesEnable(true)。该开关仅限乐鑫内部使用应用程序开发者不应调用。BLE 内部测试命令OCF0x0113ESP_BT_VS_CFG_TEST_RELATED_OCF的值为0x0113其下通过子码SUBCODE区分具体测试动作。以 ESP32 为例的基础子码子码宏取值用途由名称推断ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD0x00使能内部测试模式ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD0x01使能广播延迟ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD0x04设置持续扫描ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD0x05设置期望对端ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD0x06读取广播发送计数ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD0x07读取扫描接收计数ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD0x08设置发射功率ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD0x09读取发射功率ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD0x11清除随机地址ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD0x12读取最大发射功率ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD0x13读取发射功率范围ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD0x14设置扫描访问地址ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD0x15设置广播访问地址ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD0x16设置扫描信道ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD0x1A读取控制器状态ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD0x24读取控制器编译版本ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX0xFF子码上界在 ESP32-C3/S3 上额外增加SET_PREF_CODED_SUBCMD0x02、SET_DEFAULT_PRIV_MODE_SUBCMD0x03、SET_TXPWR_LVL_ENH_SUBCMD0x0A、GET_TXPWR_LVL_ENH_SUBCMD0x0B、ENABLE_CCA_SUBCMD0x0E、SET_AUX_ADV_OFFSET_SUBCMD0x25等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 平台这些命令需调用相应的初始化函数才会链接进二进制宏定义OCFESP32初始化函数ESP32 头文件ESP_BT_VS_WR_DM1_ENABLE_OCF0x0181bt_stack_enablePktCtrlVsCmd(true)ESP_BT_VS_CLK_UPDATE_OCF0x0183bt_stack_enableClkCtrlVsCmd(true)ESP_BT_VS_SET_AFH_OCF0x0187bt_stack_enableAfhVsCmd(true)ESP_BT_VS_SET_EVT_MASK_OCF0x0188bt_stack_enableBasicVsCmd(true)ESP_BT_VS_SET_AFH_REPORTING_MODE_OCF0x0189bt_stack_enableAfhVsCmd(true)ESP_BT_VS_MASK_RMT_CHANNEL_CLASSIFICATION_OCF0x018Abt_stack_enableAfhVsCmd(true)ESP_BT_VS_WR_AUTO_RATE_INIT_OCF0x018Bbt_stack_enableRateCtrlVsCmd(true)ESP_BT_VS_RD_ACL_REAL_RSSI_OCF0x0191bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_NEW_CONN_TX_PWR_LVL_OCF0x0192bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_NEW_CONN_TX_PWR_LVL_OCF0x0193bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_PAGE_TX_PWR_LVL_OCF0x0194bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_PAGE_TX_PWR_LVL_OCF0x0195bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_PSCAN_TX_PWR_LVL_OCF0x0196bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_PSCAN_TX_PWR_LVL_OCF0x0197bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_INQ_TX_PWR_LVL_OCF0x0198bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_ISCAN_TX_PWR_LVL_OCF0x0199bt_stack_enablePwrCtrlVsCmd(true)可见经典蓝牙调试命令主要围绕三类能力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_OCFLMP 层调试等命令具体取值以 components/bt/include/esp32s31/include/esp_bt_vs.h 为准。内部调试 HCI 事件内部调试事件同样存在于预编译库中且仅在调用相应初始化函数后才可用ESP32ESP_BT_VS_AFH_CHG_EVT_SUBCODE0x05、ESP_BT_VS_CH_CLASSIFICATION_EVT_SUBCODE0x06、ESP_BT_VS_CH_CLASSIFICATION_REPORTING_MODE_EVT_SUBCODE0x07三者初始化函数均为bt_stack_enableAfhVsCmd(true)定义见 components/bt/include/esp32/include/esp_bt_vs.h用于上报 AFH 信道变化与信道分类结果ESP32-C5 / C6 / C61 / H2 / H21 / H4ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE0xC3用于上报 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 命令/事件时有几点实践建议不要在产品代码中调用初始化函数。无论是esp_ble_internalTestFeaturesEnable(true)还是bt_stack_enableEchoVsCmd(true)等函数均被明确标记为乐鑫内部使用。这些功能面向乐鑫工程师在 RF 测试、协议一致性调试与故障分析场景使用普通应用调用可能导致控制器行为异常。区分命令归属主机专用命令OCF0x0081~0x0182区间、LE 主机事件服务于 BLE 主机与控制器之间的功能协商流控、去重、调度、功率控制内部调试命令OCF0x0113及其子码、BR/EDR 的0x0181~0x0199则服务于控制器自身的测试与诊断。按芯片查表不同芯片的 VS 命令/事件集合差异显著例如 ESP32 独有SET_COEX_STATUS与SET_MIN_ENC_KEY_SIZEESP32-C3/S3 独有COMMON_ECHO而 C5/C6/H2/H21/C61/H4/S31 拥有最完整的去重、调度、功率控制命令集。调试时务必以目标芯片对应的components/bt/include/ /include/esp_bt_vs.h头文件为准。结合 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESP-IDF 蓝牙 HCI 厂商特定（VS）命令与事件全解析：从 OCF 定义到控制器实现
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-specificHCI 命令与事件——包括蓝牙主机专用自定义命令/事件、以及仅供乐鑫内部使用的调试命令/事件。读完本文你将掌握这些 VS 命令/事件的宏定义与取值、各芯片平台的差异、对应的初始化函数如esp_ble_internalTestFeaturesEnable(true)并了解它们在 components/bt 源码中的底层实现从而能够在阅读蓝牙日志、排查控制器行为或进行射频/协议调试时准确识别这些厂商扩展指令。HCI VS 命令的背景为什么需要厂商特定扩展蓝牙 HCIHost Controller Interface是蓝牙主机Host与控制器Controller之间的标准通信协议。除了蓝牙核心规范定义的命令外控制器厂商可以在 OGFOpcode Group Field的厂商特定区间0x3F内自定义命令这类命令统称为HCI VSVendor-specific命令。它们通过OCFOpcode 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 双模支持宏定义OCF初始化函数ESP_BT_VS_COMMON_ECHO_OCF0x0081bt_stack_enableEchoVsCmd(true)ESP_BT_VS_SET_COEX_STATUS_OCF0x0082bt_stack_enableCoexVsCmd(true)ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF0x0108advFilter_stack_enableDupExcListCmd(true)ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF0x0109scan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF0x010Ascan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_CLR_LEGACY_ADV_OCF0x010Cadv_stack_enableClearLegacyAdvVsCmd(true)ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF0x0182bt_stack_enableSecCtrlVsCmd(true)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_OCFOCF0x0112初始化函数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_OCFOCF0x0116初始化函数hci_stack_enableSetVsEvtMaskVsCmd(true)。ESP32-C5 / ESP32-C6 / ESP32-H2 / ESP32-H21 / ESP32-C61 / ESP32-H4 / ESP32-S31 支持命令集最全除基础命令外还包括多连接调度、功率控制、日志等进阶扩展宏定义OCF初始化函数ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF0x0108advFilter_stack_eanbleDupExcListCmd(true)ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF0x0109scan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF0x010Ascan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_CLR_LEGACY_ADV_OCF0x010Cadv_stack_enableClearLegacyAdvVsCmd(true)ESP_BT_VS_SET_DUP_LIST_PARAMS_OCF0x010DadvFilter_stack_eanbleDupExcListCmd(true)ESP_BT_VS_ENABLE_DUP_EXC_LIST_OCF0x010EadvFilter_stack_eanbleDupExcListCmd(true)ESP_BT_VS_ENABLE_ARRANGEMENT_OCF0x010Farr_stack_enableMultiConnVsCmd(true)ESP_BT_VS_SET_SCHED_ROLE_LEN_OCF0x0110arr_stack_enableMultiConnVsCmd(true)ESP_BT_VS_SET_PCL_RSSI_THRESH_OCF0x0111pcl_stack_enableSetRssiThreshVsCmd(true)ESP_BT_VS_ENABLE_CSA2_OCF0x0112chanSel_stack_enableSetCsaVsCmd(true)ESP_BT_VS_SET_LOG_PARAMS_OCF0x0114log_stack_enableLogsRelatedVsCmd(true)ESP_BT_VS_SET_LE_VENDOR_EVTS_MASK_OCF0x0116hci_stack_enableSetVsEvtMaskVsCmd(true)ESP_BT_VS_SET_CONST_PEER_SCA_OCF0x0118winWiden_stack_enableSetConstPeerScaVsCmd(true)注部分芯片如 ESP32-S31头文件中还包含ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF0x0182等经典蓝牙相关命令具体以 components/bt/include/esp32s31/include/esp_bt_vs.h 为准。关键命令的参数结构源码级以 components/bt/include/esp32/include/esp_bt_vs.h 为基准这些命令对应的参数结构体定义如下可直接用于解析命令载荷/* 0x0081echo 测试命令参数 */ 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选择信道选择算法 #2CSA2 */ 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 事件向主机上报状态。官方文档按芯片列出的事件如下宏定义EVTCODESUBCODE初始化函数ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE0x3E0xF0scan_stack_enableAdvFlowCtrlVsCmd(true)ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODE0xFF0x03bt_stack_enableSecCtrlVsCmd(true)ESP_BT_VS_LE_CONN_SCAN_REQ_RXED_EVT_SUBCODE0xFF0xC0adv_stack_enableScanReqRxdVsEvent(true)ESP_BT_VS_LE_CHAN_UPDATE_COMP_EVT_SUBCODE0xFF0xC1conn_stack_enableChanMapUpdCompVsEvent(true)ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE0xFF0xC3sleep_stack_enableWakeupVsEvent(true)芯片支持情况与文档一致ESP32ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE、ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODEESP32-C3 / ESP32-S3ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODEESP32-C2ESP_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_SUBCODEESP32-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_SUBCODE0xC3无参数。值得注意的是在较新平台如 ESP32-C6/H2上0xC3同时被用于ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE内部调试事件见下文解析时需结合 EVTCODE 与上下文区分。乐鑫内部调试 HCI 命令与事件文档明确警告以下调试命令/事件已包含在乐鑫低功耗蓝牙BLE控制器的预编译库中但不会被链接进应用程序二进制文件除非应用调用esp_ble_internalTestFeaturesEnable(true)。该开关仅限乐鑫内部使用应用程序开发者不应调用。BLE 内部测试命令OCF0x0113ESP_BT_VS_CFG_TEST_RELATED_OCF的值为0x0113其下通过子码SUBCODE区分具体测试动作。以 ESP32 为例的基础子码子码宏取值用途由名称推断ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD0x00使能内部测试模式ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD0x01使能广播延迟ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD0x04设置持续扫描ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD0x05设置期望对端ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD0x06读取广播发送计数ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD0x07读取扫描接收计数ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD0x08设置发射功率ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD0x09读取发射功率ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD0x11清除随机地址ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD0x12读取最大发射功率ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD0x13读取发射功率范围ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD0x14设置扫描访问地址ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD0x15设置广播访问地址ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD0x16设置扫描信道ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD0x1A读取控制器状态ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD0x24读取控制器编译版本ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX0xFF子码上界在 ESP32-C3/S3 上额外增加SET_PREF_CODED_SUBCMD0x02、SET_DEFAULT_PRIV_MODE_SUBCMD0x03、SET_TXPWR_LVL_ENH_SUBCMD0x0A、GET_TXPWR_LVL_ENH_SUBCMD0x0B、ENABLE_CCA_SUBCMD0x0E、SET_AUX_ADV_OFFSET_SUBCMD0x25等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 平台这些命令需调用相应的初始化函数才会链接进二进制宏定义OCFESP32初始化函数ESP32 头文件ESP_BT_VS_WR_DM1_ENABLE_OCF0x0181bt_stack_enablePktCtrlVsCmd(true)ESP_BT_VS_CLK_UPDATE_OCF0x0183bt_stack_enableClkCtrlVsCmd(true)ESP_BT_VS_SET_AFH_OCF0x0187bt_stack_enableAfhVsCmd(true)ESP_BT_VS_SET_EVT_MASK_OCF0x0188bt_stack_enableBasicVsCmd(true)ESP_BT_VS_SET_AFH_REPORTING_MODE_OCF0x0189bt_stack_enableAfhVsCmd(true)ESP_BT_VS_MASK_RMT_CHANNEL_CLASSIFICATION_OCF0x018Abt_stack_enableAfhVsCmd(true)ESP_BT_VS_WR_AUTO_RATE_INIT_OCF0x018Bbt_stack_enableRateCtrlVsCmd(true)ESP_BT_VS_RD_ACL_REAL_RSSI_OCF0x0191bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_NEW_CONN_TX_PWR_LVL_OCF0x0192bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_NEW_CONN_TX_PWR_LVL_OCF0x0193bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_PAGE_TX_PWR_LVL_OCF0x0194bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_PAGE_TX_PWR_LVL_OCF0x0195bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_PSCAN_TX_PWR_LVL_OCF0x0196bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_PSCAN_TX_PWR_LVL_OCF0x0197bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_RD_INQ_TX_PWR_LVL_OCF0x0198bt_stack_enablePwrCtrlVsCmd(true)ESP_BT_VS_WR_ISCAN_TX_PWR_LVL_OCF0x0199bt_stack_enablePwrCtrlVsCmd(true)可见经典蓝牙调试命令主要围绕三类能力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_OCFLMP 层调试等命令具体取值以 components/bt/include/esp32s31/include/esp_bt_vs.h 为准。内部调试 HCI 事件内部调试事件同样存在于预编译库中且仅在调用相应初始化函数后才可用ESP32ESP_BT_VS_AFH_CHG_EVT_SUBCODE0x05、ESP_BT_VS_CH_CLASSIFICATION_EVT_SUBCODE0x06、ESP_BT_VS_CH_CLASSIFICATION_REPORTING_MODE_EVT_SUBCODE0x07三者初始化函数均为bt_stack_enableAfhVsCmd(true)定义见 components/bt/include/esp32/include/esp_bt_vs.h用于上报 AFH 信道变化与信道分类结果ESP32-C5 / C6 / C61 / H2 / H21 / H4ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE0xC3用于上报 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 命令/事件时有几点实践建议不要在产品代码中调用初始化函数。无论是esp_ble_internalTestFeaturesEnable(true)还是bt_stack_enableEchoVsCmd(true)等函数均被明确标记为乐鑫内部使用。这些功能面向乐鑫工程师在 RF 测试、协议一致性调试与故障分析场景使用普通应用调用可能导致控制器行为异常。区分命令归属主机专用命令OCF0x0081~0x0182区间、LE 主机事件服务于 BLE 主机与控制器之间的功能协商流控、去重、调度、功率控制内部调试命令OCF0x0113及其子码、BR/EDR 的0x0181~0x0199则服务于控制器自身的测试与诊断。按芯片查表不同芯片的 VS 命令/事件集合差异显著例如 ESP32 独有SET_COEX_STATUS与SET_MIN_ENC_KEY_SIZEESP32-C3/S3 独有COMMON_ECHO而 C5/C6/H2/H21/C61/H4/S31 拥有最完整的去重、调度、功率控制命令集。调试时务必以目标芯片对应的components/bt/include/ /include/esp_bt_vs.h头文件为准。结合 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
——手撕GPT（零基础保姆级教学）)
