ESP-IDF 射频共存RF Coexistence完全指南Wi-Fi、BLE 与 802.15.4 共享 2.4 GHz 频段的机制、策略与配置实践【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfESP 系列 SoC 在同一块 2.4 GHz ISM 频段上集成了 Wi-Fi、蓝牙BT/BLE与 IEEE 802.15.4Thread / Zigbee最多三种无线模块但物理上只有一条射频通路。本文基于 ESP-IDF 官方 API 指南docs/en/api-guides/coexist.rst与esp_coex组件源码系统讲解共存支持矩阵、时分复用仲裁机制与动态优先级策略并给出esp_coex_status_bit_set/esp_coex_status_bit_clear等共存 API 的用法、menuconfig 编译期选项如CONFIG_ESP_COEX_SW_COEXIST_ENABLE、任务绑核、BLE MESH 状态位以及外部 GPIO 共存调试能力帮助你完成 Wi-Fi 蓝牙 802.15.4 多模共存产品的工程落地。一、为什么需要 RF 共存一条射频通路的争用问题ESP 主板上最多支持三个 2.4 GHz 无线模块BluetoothBT BLE、IEEE 802.15.4Thread / Zigbee与 Wi-Fi。每块板只有一个 2.4 GHz ISM 频段的 RF 模块由两到三个协议栈共享。因此当一个模块正在收发数据时其他模块无法同时收发——此时 ESP-IDF 采用**时分复用time-division multiplexing, TDM**方式管理各模块的收发时序。从源码结构看这一仲裁逻辑由独立组件 components/esp_coex 承载components/esp_coex/src/coexist.c对外 API 的薄封装与外部 GPIO 共存实现公共符号esp_coex_status_bit_set、esp_enable_extern_coex_gpio_pin等最终转发到 ROM/库内的coex_*内部接口见 private 头文件components/esp_coex/include/esp_coexist.h公共 API 头文件定义了共存状态位、外部共存 GPIO 结构等components/esp_coex/esp32/、esp32c2/、esp32c5/ 等目录每颗芯片一份esp_coex_adapter.c适配层通过esp_coex_adapter_register(g_coex_adapter_funcs)在启动阶段注册见 coexist.c 中的ESP_SYSTEM_INIT_FN(init_coexist, SECONDARY, BIT(0), 204)钩子这解释了为什么不同芯片的共存行为可以差异化实现。二、各芯片支持的共存场景矩阵官方文档按芯片能力SOC_WIFI_SUPPORTED、SOC_BLE_SUPPORTED、SOC_BT_CLASSIC_SUPPORTED、SOC_IEEE802154_SUPPORTED区分展示多张支持矩阵。符号含义统一为Y支持且性能稳定C1支持但性能不稳定X不支持S仅 Wi-Fi 芯片仅 Wi-Fi 处于 STA 模式时支持且稳定其他模式下不支持。Wi-Fi 与 BLE 共存Wi-Fi状态BLE 扫描BLE 广播BLE 已连接STAScan / Connecting / ConnectedYYYSOFTAPTX BeaconYYYSOFTAPConnecting / ConnectedC1C1C1SnifferRXC1C1C1ESP-NOWRXSSSESP-NOWTXYYYWi-Fi 与经典蓝牙BR/EDR共存Wi-Fi状态InquiryInquiry scanPagePage scanConnectedSTAScan / Connecting / ConnectedYYYYYSOFTAPTX BeaconYYYYYSOFTAPConnecting / ConnectedC1C1C1C1C1SnifferRXC1C1C1C1C1ESP-NOWRXSSSSSESP-NOWTXYYYYYWi-Fi 与 IEEE 802.15.4Thread / Zigbee共存Wi-Fi状态802.15.4 Scan802.15.4 Router802.15.4 End DeviceSTAScan / Connecting / ConnectedC1C1YSOFTAPTX BeaconYXYSOFTAPConnecting / ConnectedC1XC1SnifferRXC1XC1IEEE 802.15.4 与 BLE 共存Thread / Zigbee状态BLE 扫描BLE 广播BLE 已连接Thread / ZigbeeScanXYYThread / ZigbeeRouterXYYThread / ZigbeeEnd DeviceC1YY关于 Router 角色的重要提示Thread 和 Zigbee 网络中的 Router 需要与邻居维持未同步的链路要求持续接收信号。由于只有一条 RF 通路Wi-Fi 或 BLE 流量增大时会抬高 Thread/Zigbee 的丢包率。官方建议构建基于 Wi-Fi 的 Thread Border Router 或 Zigbee 网关产品时采用双 SoC 方案例如 ESP32-S3 ESP32-H2并配备独立天线使 Wi-Fi 与 802.15.4 信号可以同时接收以获得最佳性能。三、共存机制基于优先级的射频资源仲裁射频资源分配机制基于优先级。Wi-Fi、蓝牙与 802.15.4 模块向共存模块申请 RF 资源共存模块根据优先级决定谁能使用 RFWi-Fi ─────┐ ├── Coexistence module ── RF module Bluetooth ─┤ │ 802.15.4 ──┘对应到实现各协议栈并不直接触碰 RF 寄存器而是通过适配层components/esp_coex/include/private/esp_coexist_adapter.h把请求交给 ROM 内的仲裁逻辑esp_coex组件负责在启动时完成适配函数注册与coex_pre_init()预初始化保证应用代码运行前共存模块已就绪。3.1 共存周期与时间片Wi-Fi BT BLEWi-Fi、BT、BLE 各自拥有固定时间片来使用 RF。一个**共存周期coexistence period**按 Wi-Fi、BT、BLE 的顺序划分为 3 个时间片。在 Wi-Fi 时间片内Wi-Fi 对共存仲裁模块的请求具有更高优先级同理BT/BLE 在各自的时间片内享受更高优先级。共存周期时长与各时间片占比按 Wi-Fi 状态分为四类IDLE 状态BT/BLE 共存由蓝牙模块接管无 Wi-Fi 芯片上则由蓝牙模块直接控制 RFCONNECTED 状态共存周期从 Wi-Fi 的目标信标传输时间TBTT, Target Beacon Transmission Time开始周期长度大于 100 msSCAN 状态Wi-Fi 时间片与共存周期都比 CONNECTED 状态更长为保证蓝牙性能蓝牙时间片会相应调整CONNECTING 状态Wi-Fi 时间片比 CONNECTED 状态更长蓝牙时间片同样相应调整。按该逻辑不同使用场景会选用不同的周期与时间片策略对应某一场景的策略组合称为一个coexistence scheme共存方案。例如 Wi-Fi CONNECTED BLE CONNECTED 场景中Wi-Fi 与 BLE 的时间片各占共存周期的 50%时间分配如下3.2 802.15.4 的优先级分配IEEE 802.15.4 模块按预分配优先级申请 RF 资源普通接收优先级最低——Wi-Fi 与 BLE 在任何时候需要 RF 都会抢占802.15.4 只能在剩余时间接收发送、收发 ACK、定时收发等操作优先级较高但其能否真正拿到 RF最终仍取决于那一刻 Wi-Fi 与 BLE 操作的优先级。这与esp_coex中esp_coex_wifi_i154_enable()coexist.c 第 290 行附近的实现对应该 API 仅在同时开启软件共存与 802.15.4 支持时编译内部调用coex_enable()与esp_coex_ieee802154_status_enable()来开启 Wi-Fi 与 15.4 的状态机。3.3 动态优先级共存模块为各模块的不同状态分配动态优先级。典型例子每 N 次 BLE 广播事件中总会有 1 次被赋予高优先级。若这次高优先级广播事件恰好落在 Wi-Fi 时间片内BLE 可以抢占RF 使用权。3.4 无连接 Wi-Fi 模块的共存注意点无连接connectionless省电模式下Window与Interval参数的某些组合会导致在 Wi-Fi 时间片之外产生额外的 Wi-Fi 高优先级请求——这是为定制参数争取 RF 资源而设计的行为但会冲击蓝牙性能。若将无连接省电参数配置为默认值共存模块将工作在稳定模式不会出现上述抢占行为。因此官方建议除非针对定制参数做过充分的共存性能测试否则请将 Wi-Fi 无连接省电参数保持默认。参数详情参见 无连接模块省电。四、如何使用共存功能4.1 自动切换为主API 为辅在大多数共存场景中ESP-IDF 会在不调用任何 API 的情况下自动切换共存状态。只有BLE MESH 与 Wi-Fi 共存这类场景需要应用主动上报当 BLE MESH 状态变化时先调用esp_coex_status_bit_clear清除旧状态再调用esp_coex_status_bit_set设置当前状态。之所以需要应用层介入是因为 Wi-Fi 与蓝牙固件无法感知上层应用的当前场景某些共存方案必须依赖应用代码上报才能生效。BLE MESH 的三个状态位定义在 esp_coexist.h 中#define ESP_COEX_BLE_ST_MESH_CONFIG 0x08 /* 网络正在配网provisioning */ #define ESP_COEX_BLE_ST_MESH_TRAFFIC 0x10 /* 数据正在传输 */ #define ESP_COEX_BLE_ST_MESH_STANDBY 0x20 /* 空闲无显著数据交互 */典型调用模式#include esp_coexist.h /* BLE MESH 状态变化时先清旧状态位再置新状态位 */ esp_err_t mesh_status_update(uint32_t old_status, uint32_t new_status) { esp_err_t ret esp_coex_status_bit_clear(ESP_COEX_ST_TYPE_BLE, old_status); if (ret ! ESP_OK) { return ret; } return esp_coex_status_bit_set(ESP_COEX_ST_TYPE_BLE, new_status); }两个 API 的函数原型esp_coexist.hesp_err_t esp_coex_status_bit_set(esp_coex_status_type_t type, uint32_t status); esp_err_t esp_coex_status_bit_clear(esp_coex_status_type_t type, uint32_t status);其中type取值为ESP_COEX_ST_TYPE_WIFI/ESP_COEX_ST_TYPE_BLE/ESP_COEX_ST_TYPE_BT。状态位是按位设置的注意MESH_TRAFFIC0x10 与A2DP_STREAMING0x10 数值相同因为二者分属 BLE 与 BT 两个不同的type命名空间。除 MESH 三个状态外头文件还定义了经典蓝牙的ESP_COEX_BT_ST_A2DP_STREAMING (0x10)与ESP_COEX_BT_ST_A2DP_PAUSED (0x20)可用于 A2DP 流媒体场景的共存调优。另外头文件中标注了esp_coex_preference_set()ESP_COEX_PREFER_WIFI/ESP_COEX_PREFER_BT/ESP_COEX_PREFER_BALANCE已被废弃deprecated官方推荐统一改用esp_coex_status_bit_set()/esp_coex_status_bit_clear()表达偏好。4.2 共存 API 错误码所有共存 API 均有自定义返回值错误码可分为两类无错误如返回ESP_OK表示 API 调用成功可恢复错误如ESP_ERR_INVALID_ARG表示 API 参数错误修正参数后重试即可。五、编译期共存配置menuconfig5.1 必选项软件共存开关编写共存程序后必须通过 menuconfig 勾选CONFIG_ESP_COEX_SW_COEXIST_ENABLE开启软件控制的 Wi-Fi/蓝牙共存否则前述共存功能不可用。从 components/esp_coex/Kconfig 可以看到该选项的定义细节config ESP_COEX_SW_COEXIST_ENABLE bool Software controls WiFi/Bluetooth coexistence depends on (ESP_WIFI_ENABLED BT_ENABLED) || \ (ESP_WIFI_ENABLED IEEE802154_ENABLED) || \ (IEEE802154_ENABLED BT_ENABLED) default y select ESP_WIFI_STA_DISCONNECTED_PM_ENABLE if (ESP_WIFI_ENABLED)即依赖条件正是任意两个模块同时使能这也对应文档末尾的注意事项必须先确认两个模块都已开启再配置共存功能仅使用蓝牙时建议关闭此选项以减小固件体积。勾选后会自动 selectESP_WIFI_STA_DISCONNECTED_PM_ENABLEWi-Fi STA 断开后的省电这是共存状态机管理射频释放的前提之一。Kconfig 中还提供的相关选项选项默认作用ESP_COEX_SW_COEXIST_ENABLEy软件控制 Wi-Fi/蓝牙共存推荐重流量场景两个共存选项由系统自动管理无需用户干预ESP_COEX_EXTERNAL_COEXIST_ENABLEn外部共存仲裁由 GPIO 引脚管理支持 1/2/3 线制GPIO 在应用代码中通过配置接口选择ESP_COEX_POWER_MANAGEMENTn使能共存下的电源管理依赖软件共存开关ESP_COEX_GPIO_DEBUGn共存 GPIO 调试输出可配置调试图类型General/Wi-Fi、最多 12 个调试 IO 及其实际引脚映射5.2 任务绑核把 Wi-Fi 与蓝牙任务放到不同 CPU双核芯片ESP32 / ESP32-S3 等上为保证共存通信性能建议将 Wi-Fi 协议栈任务与蓝牙 Controller Host 协议栈任务放到不同 CPU上ESP32用CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE与CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE或CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE把蓝牙 Controller 和 Host 协议栈任务放到同一 CPU再用CONFIG_ESP_WIFI_TASK_CORE_ID将 Wi-Fi 协议栈任务放到另一个 CPUESP32-S3同理使用CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE与 Bluedroid/Nimble 的绑核选项。5.3 芯片特有的调优项ESP32共存时 BLE SCAN 可能被 Wi-Fi 打断、且 Wi-Fi 会在当前 BLE 扫描窗口结束前释放 RF。若希望 BLE 在当前扫描窗口内重新获取 RF可勾选CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED的 FULL SCAN 配置项ESP32-C3 / ESP32-S3BLE 连接中使用 LE Coded PHY 时为避免蓝牙包时长过长影响 Wi-Fi可在CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM的子选项中选BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN限制收发最大时长ESP32-C2 / ESP32-C6同样场景下在CONFIG_BT_LE_COEX_PHY_CODED_TX_RX_TLIM子选项中选BT_LE_COEX_PHY_CODED_TX_RX_TLIM_EN。5.4 共存场景的内存削减清单共存意味着同时背负多个协议栈的缓冲区官方给出一组 menuconfig 减内存选项蓝牙侧SOC_BT_SUPPORTEDCONFIG_BT_BLE_DYNAMIC_ENV_MEMORY启用蓝牙协议栈动态内存配置。Wi-Fi 侧SOC_WIFI_SUPPORTEDCONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM减少 Wi-Fi 静态 RX 缓冲区数量CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM减少 Wi-Fi 动态 RX 缓冲区数量CONFIG_ESP_WIFI_TX_BUFFER启用 TX 缓冲区动态分配CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM减少动态 TX 缓冲区数量CONFIG_ESP_WIFI_TX_BA_WIN/CONFIG_ESP_WIFI_RX_BA_WIN减少 Block Ack 发送/接收窗口数量CONFIG_ESP_WIFI_MGMT_SBUF_NUM减少管理短缓冲区数量CONFIG_ESP_WIFI_RX_IRAM_OPT关闭此项可节省约17 KB IRAMCONFIG_LWIP_TCP_SND_BUF_DEFAULT减小 TCP socket 默认发送缓冲区CONFIG_LWIP_TCP_WND_DEFAULT减小 TCP socket 默认接收窗口CONFIG_LWIP_TCP_RECVMBOX_SIZE减小 TCP 接收邮箱缓存活动连接内数据、处理连接期间数据流CONFIG_LWIP_TCP_ACCEPTMBOX_SIZE减小 TCP 接受邮箱排队入站连接请求、管理新连接发起CONFIG_LWIP_UDP_RECVMBOX_SIZE减小 UDP 接收邮箱CONFIG_LWIP_TCPIP_RECVMBOX_SIZE减小 TCPIP 任务接收邮箱。六、进阶能力外部 GPIO 共存与调试除单芯片内部仲裁外esp_coex还实现了多芯片间的外部共存CONFIG_EXTERNAL_COEX_ENABLE由ESP_COEX_EXTERNAL_COEXIST_ENABLE对应Leader/Follower 两颗 SoC 通过 1/2/3部分芯片 4根 GPIO 线互相传递 request/priority/grant/tx_line 信号实现跨芯片的 RF 仲裁。从 coexist.c 实现看esp_external_coex_set_work_mode()先设定 Leader默认或 Follower 角色Follower 角色仅对支持SOC_EXTERNAL_COEX_ADVANCE的芯片开放否则直接返回ESP_ERR_INVALID_ARGesp_enable_extern_coex_gpio_pin()先经is_legal_external_coex_gpio()校验各线 GPIO 合法且互不冲突冲突返回ESP_ERR_INVALID_ARG再按角色把 GPIO 连接到 ROM 内部信号如GPIO_BT_ACTIVE_IDX、GPIO_WLAN_ACTIVE_IDX、BB_DIAG9_IDX最后调用coex_module_enable()与esp_coex_external_set(PTI_MID, PTI_MID, PTI_HIGH)启动仲裁输入信号线默认下拉、grant 输入默认上拉并绕过 GPIO 同步器GPIO_PIN1_SYNC1/2_BYPASS以降低仲裁延迟——这些细节保证了硬件仲裁路径的实时性。头文件中另有esp_external_coex_set_grant_delay()Leader 侧 grant 输出延迟单位 μs与esp_external_coex_set_validate_high()grant 有效电平极性两个进阶配置均需在使能 GPIO 之前调用。完整用法可参考测试工程 external_coex_function。调试方面ESP_COEX_GPIO_DEBUG选项配合 coexist_debug.c 可将最多 12 路共存事件如各模块的 RF 请求/授予映射到实际 GPIO 上用逻辑分析仪观察仲裁时序启用后建议确认相关 ROM 函数已出 ROMesp_coexist_debug_init()的文档注释亦要求rom_funcs中的函数移出 ROM。七、工程落地检查清单先确认支持矩阵对照本文第二节的场景表确认自己的芯片与业务组合是 Y / C1 / S / XThread/Zigbee Router Wi-Fi 网关类产品优先考虑双 SoC如 ESP32-S3 ESP32-H2 双天线确认双模块已使能后再开CONFIG_ESP_COEX_SW_COEXIST_ENABLE依赖任意两模块同时 enabled双核芯片做任务绑核蓝牙 ControllerHost 一核、Wi-Fi 协议栈另一核BLE MESH 应用在状态迁移时成对调用esp_coex_status_bit_clearesp_coex_status_bit_set状态位使用 0x08/0x10/0x20 三枚 MESH 位LE Coded PHY连接按芯片开启对应 TX/RX 时长限制TLIM子选项保护 Wi-Fi 吞吐无连接 Wi-Fi 省电参数保持默认除非已做定制参数的共存压测内存紧张时按 5.4 清单逐项裁剪 Wi-Fi/lwIP 缓冲并评估关闭CONFIG_ESP_WIFI_RX_IRAM_OPT省 IRAM多芯片互连场景启用外部共存 GPIO并用 GPIO 调试选项验证仲裁时序。以上所有结论均可在当前仓库中进一步核对文档主体见 coexist.rstAPI 定义见 esp_coexist.h配置项见 Kconfig实现入口见 coexist.c。需要说明的是本文中的芯片适配行为如 FULL SCAN、Coded PHY 限制均以当前仓库 Kconfig 与组件代码为准实际启用前请确认目标芯片支持对应的 SOC 能力宏。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESP-IDF 射频共存（RF Coexistence）完全指南：Wi-Fi、BLE 与 802.15.4 共享 2.4 GHz 频段的机制、策略与配置实践
ESP-IDF 射频共存RF Coexistence完全指南Wi-Fi、BLE 与 802.15.4 共享 2.4 GHz 频段的机制、策略与配置实践【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfESP 系列 SoC 在同一块 2.4 GHz ISM 频段上集成了 Wi-Fi、蓝牙BT/BLE与 IEEE 802.15.4Thread / Zigbee最多三种无线模块但物理上只有一条射频通路。本文基于 ESP-IDF 官方 API 指南docs/en/api-guides/coexist.rst与esp_coex组件源码系统讲解共存支持矩阵、时分复用仲裁机制与动态优先级策略并给出esp_coex_status_bit_set/esp_coex_status_bit_clear等共存 API 的用法、menuconfig 编译期选项如CONFIG_ESP_COEX_SW_COEXIST_ENABLE、任务绑核、BLE MESH 状态位以及外部 GPIO 共存调试能力帮助你完成 Wi-Fi 蓝牙 802.15.4 多模共存产品的工程落地。一、为什么需要 RF 共存一条射频通路的争用问题ESP 主板上最多支持三个 2.4 GHz 无线模块BluetoothBT BLE、IEEE 802.15.4Thread / Zigbee与 Wi-Fi。每块板只有一个 2.4 GHz ISM 频段的 RF 模块由两到三个协议栈共享。因此当一个模块正在收发数据时其他模块无法同时收发——此时 ESP-IDF 采用**时分复用time-division multiplexing, TDM**方式管理各模块的收发时序。从源码结构看这一仲裁逻辑由独立组件 components/esp_coex 承载components/esp_coex/src/coexist.c对外 API 的薄封装与外部 GPIO 共存实现公共符号esp_coex_status_bit_set、esp_enable_extern_coex_gpio_pin等最终转发到 ROM/库内的coex_*内部接口见 private 头文件components/esp_coex/include/esp_coexist.h公共 API 头文件定义了共存状态位、外部共存 GPIO 结构等components/esp_coex/esp32/、esp32c2/、esp32c5/ 等目录每颗芯片一份esp_coex_adapter.c适配层通过esp_coex_adapter_register(g_coex_adapter_funcs)在启动阶段注册见 coexist.c 中的ESP_SYSTEM_INIT_FN(init_coexist, SECONDARY, BIT(0), 204)钩子这解释了为什么不同芯片的共存行为可以差异化实现。二、各芯片支持的共存场景矩阵官方文档按芯片能力SOC_WIFI_SUPPORTED、SOC_BLE_SUPPORTED、SOC_BT_CLASSIC_SUPPORTED、SOC_IEEE802154_SUPPORTED区分展示多张支持矩阵。符号含义统一为Y支持且性能稳定C1支持但性能不稳定X不支持S仅 Wi-Fi 芯片仅 Wi-Fi 处于 STA 模式时支持且稳定其他模式下不支持。Wi-Fi 与 BLE 共存Wi-Fi状态BLE 扫描BLE 广播BLE 已连接STAScan / Connecting / ConnectedYYYSOFTAPTX BeaconYYYSOFTAPConnecting / ConnectedC1C1C1SnifferRXC1C1C1ESP-NOWRXSSSESP-NOWTXYYYWi-Fi 与经典蓝牙BR/EDR共存Wi-Fi状态InquiryInquiry scanPagePage scanConnectedSTAScan / Connecting / ConnectedYYYYYSOFTAPTX BeaconYYYYYSOFTAPConnecting / ConnectedC1C1C1C1C1SnifferRXC1C1C1C1C1ESP-NOWRXSSSSSESP-NOWTXYYYYYWi-Fi 与 IEEE 802.15.4Thread / Zigbee共存Wi-Fi状态802.15.4 Scan802.15.4 Router802.15.4 End DeviceSTAScan / Connecting / ConnectedC1C1YSOFTAPTX BeaconYXYSOFTAPConnecting / ConnectedC1XC1SnifferRXC1XC1IEEE 802.15.4 与 BLE 共存Thread / Zigbee状态BLE 扫描BLE 广播BLE 已连接Thread / ZigbeeScanXYYThread / ZigbeeRouterXYYThread / ZigbeeEnd DeviceC1YY关于 Router 角色的重要提示Thread 和 Zigbee 网络中的 Router 需要与邻居维持未同步的链路要求持续接收信号。由于只有一条 RF 通路Wi-Fi 或 BLE 流量增大时会抬高 Thread/Zigbee 的丢包率。官方建议构建基于 Wi-Fi 的 Thread Border Router 或 Zigbee 网关产品时采用双 SoC 方案例如 ESP32-S3 ESP32-H2并配备独立天线使 Wi-Fi 与 802.15.4 信号可以同时接收以获得最佳性能。三、共存机制基于优先级的射频资源仲裁射频资源分配机制基于优先级。Wi-Fi、蓝牙与 802.15.4 模块向共存模块申请 RF 资源共存模块根据优先级决定谁能使用 RFWi-Fi ─────┐ ├── Coexistence module ── RF module Bluetooth ─┤ │ 802.15.4 ──┘对应到实现各协议栈并不直接触碰 RF 寄存器而是通过适配层components/esp_coex/include/private/esp_coexist_adapter.h把请求交给 ROM 内的仲裁逻辑esp_coex组件负责在启动时完成适配函数注册与coex_pre_init()预初始化保证应用代码运行前共存模块已就绪。3.1 共存周期与时间片Wi-Fi BT BLEWi-Fi、BT、BLE 各自拥有固定时间片来使用 RF。一个**共存周期coexistence period**按 Wi-Fi、BT、BLE 的顺序划分为 3 个时间片。在 Wi-Fi 时间片内Wi-Fi 对共存仲裁模块的请求具有更高优先级同理BT/BLE 在各自的时间片内享受更高优先级。共存周期时长与各时间片占比按 Wi-Fi 状态分为四类IDLE 状态BT/BLE 共存由蓝牙模块接管无 Wi-Fi 芯片上则由蓝牙模块直接控制 RFCONNECTED 状态共存周期从 Wi-Fi 的目标信标传输时间TBTT, Target Beacon Transmission Time开始周期长度大于 100 msSCAN 状态Wi-Fi 时间片与共存周期都比 CONNECTED 状态更长为保证蓝牙性能蓝牙时间片会相应调整CONNECTING 状态Wi-Fi 时间片比 CONNECTED 状态更长蓝牙时间片同样相应调整。按该逻辑不同使用场景会选用不同的周期与时间片策略对应某一场景的策略组合称为一个coexistence scheme共存方案。例如 Wi-Fi CONNECTED BLE CONNECTED 场景中Wi-Fi 与 BLE 的时间片各占共存周期的 50%时间分配如下3.2 802.15.4 的优先级分配IEEE 802.15.4 模块按预分配优先级申请 RF 资源普通接收优先级最低——Wi-Fi 与 BLE 在任何时候需要 RF 都会抢占802.15.4 只能在剩余时间接收发送、收发 ACK、定时收发等操作优先级较高但其能否真正拿到 RF最终仍取决于那一刻 Wi-Fi 与 BLE 操作的优先级。这与esp_coex中esp_coex_wifi_i154_enable()coexist.c 第 290 行附近的实现对应该 API 仅在同时开启软件共存与 802.15.4 支持时编译内部调用coex_enable()与esp_coex_ieee802154_status_enable()来开启 Wi-Fi 与 15.4 的状态机。3.3 动态优先级共存模块为各模块的不同状态分配动态优先级。典型例子每 N 次 BLE 广播事件中总会有 1 次被赋予高优先级。若这次高优先级广播事件恰好落在 Wi-Fi 时间片内BLE 可以抢占RF 使用权。3.4 无连接 Wi-Fi 模块的共存注意点无连接connectionless省电模式下Window与Interval参数的某些组合会导致在 Wi-Fi 时间片之外产生额外的 Wi-Fi 高优先级请求——这是为定制参数争取 RF 资源而设计的行为但会冲击蓝牙性能。若将无连接省电参数配置为默认值共存模块将工作在稳定模式不会出现上述抢占行为。因此官方建议除非针对定制参数做过充分的共存性能测试否则请将 Wi-Fi 无连接省电参数保持默认。参数详情参见 无连接模块省电。四、如何使用共存功能4.1 自动切换为主API 为辅在大多数共存场景中ESP-IDF 会在不调用任何 API 的情况下自动切换共存状态。只有BLE MESH 与 Wi-Fi 共存这类场景需要应用主动上报当 BLE MESH 状态变化时先调用esp_coex_status_bit_clear清除旧状态再调用esp_coex_status_bit_set设置当前状态。之所以需要应用层介入是因为 Wi-Fi 与蓝牙固件无法感知上层应用的当前场景某些共存方案必须依赖应用代码上报才能生效。BLE MESH 的三个状态位定义在 esp_coexist.h 中#define ESP_COEX_BLE_ST_MESH_CONFIG 0x08 /* 网络正在配网provisioning */ #define ESP_COEX_BLE_ST_MESH_TRAFFIC 0x10 /* 数据正在传输 */ #define ESP_COEX_BLE_ST_MESH_STANDBY 0x20 /* 空闲无显著数据交互 */典型调用模式#include esp_coexist.h /* BLE MESH 状态变化时先清旧状态位再置新状态位 */ esp_err_t mesh_status_update(uint32_t old_status, uint32_t new_status) { esp_err_t ret esp_coex_status_bit_clear(ESP_COEX_ST_TYPE_BLE, old_status); if (ret ! ESP_OK) { return ret; } return esp_coex_status_bit_set(ESP_COEX_ST_TYPE_BLE, new_status); }两个 API 的函数原型esp_coexist.hesp_err_t esp_coex_status_bit_set(esp_coex_status_type_t type, uint32_t status); esp_err_t esp_coex_status_bit_clear(esp_coex_status_type_t type, uint32_t status);其中type取值为ESP_COEX_ST_TYPE_WIFI/ESP_COEX_ST_TYPE_BLE/ESP_COEX_ST_TYPE_BT。状态位是按位设置的注意MESH_TRAFFIC0x10 与A2DP_STREAMING0x10 数值相同因为二者分属 BLE 与 BT 两个不同的type命名空间。除 MESH 三个状态外头文件还定义了经典蓝牙的ESP_COEX_BT_ST_A2DP_STREAMING (0x10)与ESP_COEX_BT_ST_A2DP_PAUSED (0x20)可用于 A2DP 流媒体场景的共存调优。另外头文件中标注了esp_coex_preference_set()ESP_COEX_PREFER_WIFI/ESP_COEX_PREFER_BT/ESP_COEX_PREFER_BALANCE已被废弃deprecated官方推荐统一改用esp_coex_status_bit_set()/esp_coex_status_bit_clear()表达偏好。4.2 共存 API 错误码所有共存 API 均有自定义返回值错误码可分为两类无错误如返回ESP_OK表示 API 调用成功可恢复错误如ESP_ERR_INVALID_ARG表示 API 参数错误修正参数后重试即可。五、编译期共存配置menuconfig5.1 必选项软件共存开关编写共存程序后必须通过 menuconfig 勾选CONFIG_ESP_COEX_SW_COEXIST_ENABLE开启软件控制的 Wi-Fi/蓝牙共存否则前述共存功能不可用。从 components/esp_coex/Kconfig 可以看到该选项的定义细节config ESP_COEX_SW_COEXIST_ENABLE bool Software controls WiFi/Bluetooth coexistence depends on (ESP_WIFI_ENABLED BT_ENABLED) || \ (ESP_WIFI_ENABLED IEEE802154_ENABLED) || \ (IEEE802154_ENABLED BT_ENABLED) default y select ESP_WIFI_STA_DISCONNECTED_PM_ENABLE if (ESP_WIFI_ENABLED)即依赖条件正是任意两个模块同时使能这也对应文档末尾的注意事项必须先确认两个模块都已开启再配置共存功能仅使用蓝牙时建议关闭此选项以减小固件体积。勾选后会自动 selectESP_WIFI_STA_DISCONNECTED_PM_ENABLEWi-Fi STA 断开后的省电这是共存状态机管理射频释放的前提之一。Kconfig 中还提供的相关选项选项默认作用ESP_COEX_SW_COEXIST_ENABLEy软件控制 Wi-Fi/蓝牙共存推荐重流量场景两个共存选项由系统自动管理无需用户干预ESP_COEX_EXTERNAL_COEXIST_ENABLEn外部共存仲裁由 GPIO 引脚管理支持 1/2/3 线制GPIO 在应用代码中通过配置接口选择ESP_COEX_POWER_MANAGEMENTn使能共存下的电源管理依赖软件共存开关ESP_COEX_GPIO_DEBUGn共存 GPIO 调试输出可配置调试图类型General/Wi-Fi、最多 12 个调试 IO 及其实际引脚映射5.2 任务绑核把 Wi-Fi 与蓝牙任务放到不同 CPU双核芯片ESP32 / ESP32-S3 等上为保证共存通信性能建议将 Wi-Fi 协议栈任务与蓝牙 Controller Host 协议栈任务放到不同 CPU上ESP32用CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE与CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE或CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE把蓝牙 Controller 和 Host 协议栈任务放到同一 CPU再用CONFIG_ESP_WIFI_TASK_CORE_ID将 Wi-Fi 协议栈任务放到另一个 CPUESP32-S3同理使用CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE与 Bluedroid/Nimble 的绑核选项。5.3 芯片特有的调优项ESP32共存时 BLE SCAN 可能被 Wi-Fi 打断、且 Wi-Fi 会在当前 BLE 扫描窗口结束前释放 RF。若希望 BLE 在当前扫描窗口内重新获取 RF可勾选CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED的 FULL SCAN 配置项ESP32-C3 / ESP32-S3BLE 连接中使用 LE Coded PHY 时为避免蓝牙包时长过长影响 Wi-Fi可在CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM的子选项中选BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN限制收发最大时长ESP32-C2 / ESP32-C6同样场景下在CONFIG_BT_LE_COEX_PHY_CODED_TX_RX_TLIM子选项中选BT_LE_COEX_PHY_CODED_TX_RX_TLIM_EN。5.4 共存场景的内存削减清单共存意味着同时背负多个协议栈的缓冲区官方给出一组 menuconfig 减内存选项蓝牙侧SOC_BT_SUPPORTEDCONFIG_BT_BLE_DYNAMIC_ENV_MEMORY启用蓝牙协议栈动态内存配置。Wi-Fi 侧SOC_WIFI_SUPPORTEDCONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM减少 Wi-Fi 静态 RX 缓冲区数量CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM减少 Wi-Fi 动态 RX 缓冲区数量CONFIG_ESP_WIFI_TX_BUFFER启用 TX 缓冲区动态分配CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM减少动态 TX 缓冲区数量CONFIG_ESP_WIFI_TX_BA_WIN/CONFIG_ESP_WIFI_RX_BA_WIN减少 Block Ack 发送/接收窗口数量CONFIG_ESP_WIFI_MGMT_SBUF_NUM减少管理短缓冲区数量CONFIG_ESP_WIFI_RX_IRAM_OPT关闭此项可节省约17 KB IRAMCONFIG_LWIP_TCP_SND_BUF_DEFAULT减小 TCP socket 默认发送缓冲区CONFIG_LWIP_TCP_WND_DEFAULT减小 TCP socket 默认接收窗口CONFIG_LWIP_TCP_RECVMBOX_SIZE减小 TCP 接收邮箱缓存活动连接内数据、处理连接期间数据流CONFIG_LWIP_TCP_ACCEPTMBOX_SIZE减小 TCP 接受邮箱排队入站连接请求、管理新连接发起CONFIG_LWIP_UDP_RECVMBOX_SIZE减小 UDP 接收邮箱CONFIG_LWIP_TCPIP_RECVMBOX_SIZE减小 TCPIP 任务接收邮箱。六、进阶能力外部 GPIO 共存与调试除单芯片内部仲裁外esp_coex还实现了多芯片间的外部共存CONFIG_EXTERNAL_COEX_ENABLE由ESP_COEX_EXTERNAL_COEXIST_ENABLE对应Leader/Follower 两颗 SoC 通过 1/2/3部分芯片 4根 GPIO 线互相传递 request/priority/grant/tx_line 信号实现跨芯片的 RF 仲裁。从 coexist.c 实现看esp_external_coex_set_work_mode()先设定 Leader默认或 Follower 角色Follower 角色仅对支持SOC_EXTERNAL_COEX_ADVANCE的芯片开放否则直接返回ESP_ERR_INVALID_ARGesp_enable_extern_coex_gpio_pin()先经is_legal_external_coex_gpio()校验各线 GPIO 合法且互不冲突冲突返回ESP_ERR_INVALID_ARG再按角色把 GPIO 连接到 ROM 内部信号如GPIO_BT_ACTIVE_IDX、GPIO_WLAN_ACTIVE_IDX、BB_DIAG9_IDX最后调用coex_module_enable()与esp_coex_external_set(PTI_MID, PTI_MID, PTI_HIGH)启动仲裁输入信号线默认下拉、grant 输入默认上拉并绕过 GPIO 同步器GPIO_PIN1_SYNC1/2_BYPASS以降低仲裁延迟——这些细节保证了硬件仲裁路径的实时性。头文件中另有esp_external_coex_set_grant_delay()Leader 侧 grant 输出延迟单位 μs与esp_external_coex_set_validate_high()grant 有效电平极性两个进阶配置均需在使能 GPIO 之前调用。完整用法可参考测试工程 external_coex_function。调试方面ESP_COEX_GPIO_DEBUG选项配合 coexist_debug.c 可将最多 12 路共存事件如各模块的 RF 请求/授予映射到实际 GPIO 上用逻辑分析仪观察仲裁时序启用后建议确认相关 ROM 函数已出 ROMesp_coexist_debug_init()的文档注释亦要求rom_funcs中的函数移出 ROM。七、工程落地检查清单先确认支持矩阵对照本文第二节的场景表确认自己的芯片与业务组合是 Y / C1 / S / XThread/Zigbee Router Wi-Fi 网关类产品优先考虑双 SoC如 ESP32-S3 ESP32-H2 双天线确认双模块已使能后再开CONFIG_ESP_COEX_SW_COEXIST_ENABLE依赖任意两模块同时 enabled双核芯片做任务绑核蓝牙 ControllerHost 一核、Wi-Fi 协议栈另一核BLE MESH 应用在状态迁移时成对调用esp_coex_status_bit_clearesp_coex_status_bit_set状态位使用 0x08/0x10/0x20 三枚 MESH 位LE Coded PHY连接按芯片开启对应 TX/RX 时长限制TLIM子选项保护 Wi-Fi 吞吐无连接 Wi-Fi 省电参数保持默认除非已做定制参数的共存压测内存紧张时按 5.4 清单逐项裁剪 Wi-Fi/lwIP 缓冲并评估关闭CONFIG_ESP_WIFI_RX_IRAM_OPT省 IRAM多芯片互连场景启用外部共存 GPIO并用 GPIO 调试选项验证仲裁时序。以上所有结论均可在当前仓库中进一步核对文档主体见 coexist.rstAPI 定义见 esp_coexist.h配置项见 Kconfig实现入口见 coexist.c。需要说明的是本文中的芯片适配行为如 FULL SCAN、Coded PHY 限制均以当前仓库 Kconfig 与组件代码为准实际启用前请确认目标芯片支持对应的 SOC 能力宏。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
