ESP-Hosted-MCU Solution

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

Basic Features

Overview

ESP-Hosted-MCU is an open-source solution that allows Espressif chipsets and modules to be used as communication slaves. This solution provides wireless connectivity (Wi-Fi and Bluetooth) for the host microprocessor or microcontroller, enabling it to communicate with other devices.

For the framework of ESP-Hosted host and slave functions, please refer to Introduction

Slave Selection Guide

For a comparison of communication interfaces and throughput, please refer to Decide the communication bus in between host and slave
Comparison of SDIO interface slave chip parameters

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

For more instructions, please refer to ESP-Hosted-MCU. The dependencies and related configurations of the host and slave can be viewed according to the communication interface used.

ESP-Hosted Loading Process

Component initialization: esp_hosted_init()

Add wifi remote channel: add_esp_wifi_remote_channels()

Initialize SDIO driver and create related tasks: bus_init_internal()

Initialize RPC related interfaces: rpc_core_init()

Call esp_wifi_init() in the main application

Execute remote initialization: esp_wifi_remote_init()

Execute RPC related initialization: rpc_wifi_init()

Typical example: The host completes network configuration through the slave

Host sending process

Wi-Fi default configuration: WIFI_INIT_CONFIG_DEFAULT
Wi-Fi initialization: rpc_wifi_init()
RPC task handling: rpc_tx_thread()
Get response return value: rpc_rsp_callback()
Register and receive Slave events (such as WIFI_EVENT_STA_START event): rpc_event_callback()

Slave processing process

Receive and execute RPC commands: esp_rpc_command_dispatcher()
Configure Wi-Fi according to the incoming parameters: req_wifi_init()
Handle Wi-Fi events and send them to the message return queue: event_handler_wifi()
Task processing and triggering event callbacks: pserial_task()
Send events to the host: rpc_evt_handler()

Slave Firmware Upgrade

The host upgrades the slave firmware by calling esp_hosted_slave_ota(): esp_hosted_slave_ota
It is recommended to reserve a UART download interface in the slave for debugging and upgrading during initial development, and consider upgrading via Wi-Fi in the future.
For related examples, refer to: host_performs_slave_ota

Others

Hosted system call interface: g_hosted_osi_funcs
Hosted task creation: hosted_thread_create
SDIO driver initialization: hosted_sdio_init

Network Splitting Function

Overview

The Network-Split feature allows the host MCU and ESP32 slave to share an IP address and distribute traffic between them. When the host is in sleep mode, the slave can continue to handle selected network activities (such as MQTT, DNS).

Port-based data forwarding
Shared IP address
Support for specific port packet filtering
Support for specific packet wake-up, such as “wakeup-host” included in MQTT messages
Support for the host and slave to simultaneously call related interfaces such as esp_wifi_xx() to complete network connection

For more information, please refer to Network Split Feature for ESP-Hosted MCU

Host deep sleep while slave maintains MQTT keep-alive function

Overview

This feature allows the host MCU to enter a low-power state while maintaining the slave’s network connection, thereby improving the energy efficiency of battery-powered devices.

When the host enters deep sleep or power off, the slave still maintains the network connection
The slave can wake up the host through specific packets or execute specific commands
Seamless switching of network packets during sleep wake-up
Need to be used in conjunction with the network split function

For more information, please refer to Host Power Save (ESP-Hosted MCU)

FAQ

Q: Why is the communication between the host and slave failing?

A: You can troubleshoot according to the following steps:

Check whether the versions of the ESP-Hosted component on the host and slave are consistent

Check whether the configurations of the host and slave are consistent, such as communication interfaces (SDIO or SPI), communication rates, etc.

Check whether the hardware connection is normal, such as IO pins, power supply, etc. You can further refer to Hardware Guide

Q: Why can’t the configured CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM take effect?

A: Starting from the esp_wifi_remote 0.8.0 version, the configuration item name has been changed to CONFIG_WIFI_RMT_STATIC_RX_BUFFER_NUM. Please configure it in (Top) > Component config > Wi-Fi Remote > Wi-Fi configuration. The old CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM configuration item is no longer supported.

Q: Why is there a compilation failure?

A: Some structure definitions in ESP-IDF have changed, and the component definitions updated to adapt to the new version are not compatible with the old version of ESP-IDF. It is recommended to upgrade ESP-IDF to a compatible version or use a matching component version.

Q: What does the following log mean: === ESP-Hosted Version Warning ===?

A: This warning indicates that the versions of the ESP-Hosted component used by the host (such as ESP32-P4) and the slave (such as ESP32-C6) are inconsistent. It is strongly recommended that the host and slave use the same version to avoid communication abnormalities caused by version differences.

Q: What does the following log mean: Identified slave [esp32c6] != Expected [esp32]?

A: This error indicates that the actual detected slave chip model (esp32-c6) does not match the model specified in the configuration (esp32). Please reselect the correct slave chip model in (Top) > Component config > Wi-Fi Remote > choose slave target.

Q: Why does ESP32-P4 + ESP32-C5 report insufficient memory after turning on Wi-Fi and BLE?

A: The internal memory of ESP32-C5 is only 384 KB, the memory resources are relatively tight, and memory allocation failure is likely to occur. You can further optimize memory usage in the slave through the following configuration:

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: How to speed up IP acquisition?

A: Both Host and Slave can use the following configuration:

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
Use bootloader_hooks or bootloader_override to reset the slave in advance to reduce the host waiting time.

By default, hosted is initialized during the bootloader stage. For quick startup, you can shield esp_hosted_init(), and call esp_hosted_init() before the application program esp_wifi_init().

Q: Relationship between ESP-IDF version and hosted/remote version

A: - ESP32-C6: It is recommended to use esp_hosted ≥ 2.4.2, esp_wifi_remote ≥ 1.0.0, ESP-IDF ≥ v5.3.2 - ESP32-C5: It is recommended to use esp_hosted ≥ 2.4.2, esp_wifi_remote ≥ 1.0.0, ESP-IDF ≥ v5.5

You can pull the components in the following way, or directly use the latest components. If the host updates the component version and the version difference is large, it is recommended to update the slave at the same time.

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

Q: Bluetooth Usage Notes

A: Different from chips with Bluetooth capabilities (such as ESP32C6), when communicating through the esp_hosted component, the following modifications are needed to support Bluetooth functionality.

Related Configuration

#
# 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

Code Modification

#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: Precautions for using ESP32S3 as a host

A: When the chip itself supports Wi-Fi and Bluetooth functions, you need to refer to Troubleshooting to complete the communication.