ESP-Hosted-MCU 方案

基础功能

概述

ESP-Hosted-MCU 是一种开源解决方案，允许将乐鑫芯片组和模块用作通信从机。该解决方案为主机微处理器或微控制器提供无线连接（Wi-Fi 和蓝牙），使其能够与其他设备进行通信。

ESP-Hosted 主机和从机功能框架请参考 Introduction

从机选型指南

通信接口与吞吐量对比请参考 Decide the communication bus in between host and slave
SDIO 接口从机芯片参数对比

Model	SRAM	GPIO	Feature
ESP32	520 KB	34	2.4 GHz Wi-Fi-and-Bluetooth
ESP32-C5	384 KB	22	2.4 and 5 GHz dual-band Wi-Fi 6, Bluetooth LE 5, Zigbee 3.0 and Thread 1.3
ESP32-C6	512 KB	30	2.4 GHz Wi-Fi 4/Wi-Fi 6 and Bluetooth LE

更多说明请参考 ESP-Hosted-MCU，主从机依赖组件和相关配置可根据使用的通信接口查看对应说明文件。

ESP-Hosted 加载流程

组件初始化：esp_hosted_init()

添加 wifi remote 通道：add_esp_wifi_remote_channels()

初始化 SDIO 驱动并创建相关任务：bus_init_internal()

初始化 RPC 相关接口：rpc_core_init()

主应用程序中调用 esp_wifi_init()

执行远程初始化：esp_wifi_remote_init()

执行 RPC 相关初始化：rpc_wifi_init()

典型示例：主机通过从机完成网络配置

主机发送流程

Wi-Fi 默认配置：WIFI_INIT_CONFIG_DEFAULT
Wi-Fi 初始化：rpc_wifi_init()
RPC 任务处理：rpc_tx_thread()
获取响应返回值：rpc_rsp_callback()
注册并接收 Slave 事件（如 WIFI_EVENT_STA_START 事件）：rpc_event_callback()

从机处理流程

接收并执行 RPC 命令：esp_rpc_command_dispatcher()
根据传入参数配置 Wi-Fi：req_wifi_init()
处理 Wi-Fi 事件并发送至消息返回队列：event_handler_wifi()
任务处理并触发事件回调：pserial_task()
发送事件到主机：rpc_evt_handler()

从机固件升级

主机通过调用 esp_hosted_slave_ota() 实现从机固件升级：esp_hosted_slave_ota
初期开发时建议在从机中预留 UART 下载接口，便于调试与升级，后续可考虑通过 Wi-Fi 进行升级
相关示例参考： host_performs_slave_ota

其他

Hosted 系统调用接口：g_hosted_osi_funcs
Hosted 任务创建：hosted_thread_create
SDIO 驱动初始化：hosted_sdio_init

网络拆分功能

概述

网络拆分（Network-Split）功能允许主机 MCU 和 ESP32 从机共享一个 IP 地址，并在它们之间分配流量。当主机休眠时，从机可以继续处理选定的网络活动（例如 MQTT、DNS）。

基于端口的数据转发
共享 IP 地址
支持特定端口数据包过滤
支持特定数据包唤醒，如 MQTT 消息中包含 “wakeup-host”
可支持主从机同时调用 esp_wifi_xx() 等相关接口完成网络连接

更多说明请参考 Network Split Feature for ESP-Hosted MCU

主机深度休眠从机维持 MQTT 保活功能

概述

该功能允许主机 MCU 进入低功耗状态，同时保持从机的网络连接，从而提高电池供电设备的能效。

主机进入深度睡眠或者掉电时，从机仍保持网络连接
从机可通过特定数据包唤醒主机，或者执行特定命令
睡眠唤醒期间网络数据包无缝切换
需要与网络拆分功能配合使用

更多说明请参考 Host Power Save (ESP-Hosted MCU)

FAQ

Q: 为什么主从机通信失败？

A: 可按以下步骤排查：

检查主从机 ESP-Hosted 组件版本是否一致

检查主从机配置是否一致，如通信接口（SDIO 或 SPI），通信速率等

检查硬件连接是否正常，如 IO 引脚、电源等，可进一步参考硬件指南

Q: 为什么配置的 CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM 无法生效？

A: 从 esp_wifi_remote 0.8.0 版本开始，配置项名称已更改为 CONFIG_WIFI_RMT_STATIC_RX_BUFFER_NUM。请在 (Top) > Component config > Wi-Fi Remote > Wi-Fi configuration 中进行配置。旧的 CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM 配置项已不再支持。

Q: 为什么出现编译失败？

A: ESP-IDF 中的某些结构体定义发生了变化，为适配新版本而更新的组件定义与旧版本 ESP-IDF 不兼容。建议将 ESP-IDF 升级到兼容版本，或使用匹配的组件版本。

Q: 如下 log： === ESP-Hosted Version Warning === 表示什么意思？

A: 该警告表示主机（如 ESP32-P4）和从机（如 ESP32-C6）使用的 ESP-Hosted 组件版本不一致。强烈建议主从机使用相同版本，避免因版本差异导致的通信异常。

Q: 如下 log： Identified slave [esp32c6] != Expected [esp32] 表示什么意思？

A: 该错误表示实际检测到的从机芯片型号（esp32-c6）与配置中指定的型号（esp32）不符。请在 (Top) > Component config > Wi-Fi Remote > choose slave target 中重新选择正确的从机芯片型号。

Q: 为什么 ESP32-P4 + ESP32-C5 开启 Wi-Fi 和 BLE 后，报内存不足？

A: ESP32-C5 内部内存仅有 384 KB，内存资源相对紧张，容易出现内存分配失败。可在 slave 中通过以下配置进一步优化内存使用：

CONFIG_ESP_SDIO_RX_Q_SIZE=10
CONFIG_ESP_WIFI_IRAM_OPT=n
CONFIG_ESP_WIFI_EXTRA_IRAM_OPT=n
CONFIG_ESP_WIFI_RX_IRAM_OPT=n
CONFIG_ESP_WIFI_SLP_IRAM_OPT=n
CONFIG_LWIP_IRAM_OPTIMIZATION=n
CONFIG_LWIP_EXTRA_IRAM_OPTIMIZATION=n
CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH=y

Q: 如何加速获取 IP？

A: Host 和 Slave 均可以采用如下配置：

CONFIG_COMPILER_OPTIMIZATION_PERF=y
CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y
CONFIG_LOG_DEFAULT_LEVEL_ERROR=y
CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS=y
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
CONFIG_LWIP_DHCP_RESTORE_LAST_IP=y
CONFIG_SPIRAM_MEMTEST=n
使用 bootloader_hooks 或 bootloader_override 提前复位从机，以便减少主机等待时间。

默认在 bootloader 阶段初始化 hosted。如需快速启动，可屏蔽 esp_hosted_init()，并在应用程序 esp_wifi_init() 之前调用 esp_hosted_init()。

Q: ESP-IDF 版本与 hosted/remote 版本对应关系

A: - ESP32-C6：推荐使用 esp_hosted ≥ 2.4.2，esp_wifi_remote ≥ 1.0.0，ESP-IDF ≥ v5.3.2 - ESP32-C5：推荐使用 esp_hosted ≥ 2.4.2，esp_wifi_remote ≥ 1.0.0，ESP-IDF ≥ v5.5

可以使用如下方式拉取组件，或者直接使用最新组件。 如果主机更新了组件版本，且版本差异较大，建议从机也一并更新。

espressif/esp_hosted:
  version: ^2.4
  rules:
  - if: target in [esp32p4]
espressif/esp_wifi_remote:
  version: ^1.0
  rules:
  - if: target in [esp32p4]

Q: 蓝牙使用注意事项

A：与具备蓝牙功能的芯片（如 ESP32C6）使用有所不同，通过 esp_hosted 组件进行通信时，需要通过如下修改来支持蓝牙功能。

相关配置

#
# BT config
# - ESP32 co-processor only supports BLE 4.2
#
CONFIG_BT_ENABLED=y
CONFIG_BT_CONTROLLER_DISABLED=y
CONFIG_BT_BLUEDROID_ENABLED=y
CONFIG_BT_BLE_50_FEATURES_SUPPORTED=y
CONFIG_BT_BLE_42_FEATURES_SUPPORTED=y

#
# ESP-Hosted and Wi-Fi Remote config
#
CONFIG_ESP_HOSTED_SDIO_HOST_INTERFACE=y
CONFIG_ESP_WIFI_REMOTE_ENABLED=y
CONFIG_SLAVE_IDF_TARGET_ESP32C6=y

#
# Bluetooth Support
#
CONFIG_ESP_HOSTED_ENABLE_BT_BLUEDROID=y
CONFIG_ESP_HOSTED_BLUEDROID_HCI_VHCI=y

代码修改

#if CONFIG_IDF_TARGET_ESP32P4
#include "esp_hosted.h"
#include "esp_hosted_bluedroid.h"
#else
  #if CONFIG_BT_CONTROLLER_ENABLED || !CONFIG_BT_NIMBLE_ENABLED
  #include "esp_bt.h"
  #endif
#endif

esp_err_t esp_blufi_controller_init() {
#if CONFIG_IDF_TARGET_ESP32P4
  // init bt controller
  esp_err_t ret = esp_hosted_bt_controller_init();
  if (ESP_OK != ret) {
    ESP_LOGW("INFO", "failed to init bt controller, %s", esp_err_to_name(ret));
    return ret;
  }

    // enable bt controller
  ret = esp_hosted_bt_controller_enable();
  if (ESP_OK != ret) {
    ESP_LOGW("INFO", "failed to enable bt controller, ret: %s", esp_err_to_name(ret));
    return ret;
  }

  hosted_hci_bluedroid_open();

  /* get HCI driver operations */
  esp_bluedroid_hci_driver_operations_t operations = {
      .send = hosted_hci_bluedroid_send,
      .check_send_available = hosted_hci_bluedroid_check_send_available,
      .register_host_callback = hosted_hci_bluedroid_register_host_callback,
  };
  ret = esp_bluedroid_attach_hci_driver(&operations);
  if (ESP_OK != ret) {
    ESP_LOGW("INFO", "failed to attach hci driver, ret: %s", esp_err_to_name(ret));
  }
  return ret;
#endif
}

esp_err_t esp_blufi_controller_deinit() {
  esp_err_t ret = ESP_OK;
#if CONFIG_IDF_TARGET_ESP32P4
  ret = esp_hosted_bt_controller_disable();
  if (ret) {
      ESP_LOGW("INFO", "failed to disable bt controller, ret: %s", esp_err_to_name(ret));
      return ret;
  }

  ret = esp_hosted_bt_controller_deinit(true);
  if (ret) {
      ESP_LOGW("INFO", "failed to deinit bt controller, ret: %s", esp_err_to_name(ret));
      return ret;
  }
#endif
  return ret;
}

Q: ESP32S3 作为主机使用注意事项

A: 芯片本身支持 Wi-Fi 和蓝牙功能时，需要参考 Troubleshooting 完成通信。