ESP32 Hosted

ESP32 Hosted (ESP-Hosted-MCU) is a solution that allows you to use ESP32 modules as communication co-processors. This solution provides wireless connectivity (Wi-Fi and Bluetooth) to the host module, enabling it to communicate with other devices.

Two transport modes are supported: SDIO (default) and SPI.

SDIO Transport

# Example SDIO configuration (4-bit, default)
esp32_hosted:
  type: sdio
  variant: ESP32C6
  reset_pin: GPIOXX
  cmd_pin: GPIOXX
  clk_pin: GPIOXX
  d0_pin: GPIOXX
  d1_pin: GPIOXX
  d2_pin: GPIOXX
  d3_pin: GPIOXX
  active_high: true
  sdio_frequency: 10MHz

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

# Example SDIO configuration (1-bit)
esp32_hosted:
  type: sdio
  variant: ESP32C6
  bus_width: 1
  reset_pin: GPIOXX
  cmd_pin: GPIOXX
  clk_pin: GPIOXX
  d0_pin: GPIOXX
  active_high: true

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

SDIO Configuration variables

type (Optional, string): The transport mode. Set to sdio for SDIO transport. Defaults to sdio.
variant (Required, string): The variant of the ESP32 co-processor that is used by the host. One of ESP32, ESP32S2, ESP32S3, ESP32C2, ESP32C3 and ESP32C6.
reset_pin (Required, Pin): The reset pin of the co-processor.
active_high (Required, boolean): If enabled, the co-processor is active when reset is high. If disabled, the co-processor is active when reset is low.
clk_pin (Required, Pin): The SDIO clock pin.
cmd_pin (Required, Pin): The SDIO command pin.
d0_pin (Required, Pin): The SDIO D0 pin.
d1_pin (Optional, Pin): The SDIO D1 pin. Required when bus_width is 4.
d2_pin (Optional, Pin): The SDIO D2 pin. Required when bus_width is 4.
d3_pin (Optional, Pin): The SDIO D3 pin. Required when bus_width is 4.
bus_width (Optional, int): The SDIO bus width. Either 1 or 4. Defaults to 4.
slot (Optional, int): The SDIO slot number. Defaults to 1.
sdio_frequency (Optional, frequency): Set the speed of communication between the host and the co-processor. If you experience loss of communication, or reboots, then try reducing this value. The value can be between 400kHz and 50MHz, with a default of 40MHz.
use_psram (Optional, boolean): Place the SDIO transport buffer pool in PSRAM instead of internal RAM. Requires the host MCU to have DMA-capable PSRAM enabled (ESP32-P4, ESP32-S3). Recommended when the host firmware uses most of internal RAM (for example, a large LVGL UI); without it, boot can fail with an sdio_mempool_create assert. Defaults to false.

SPI Transport

# Example SPI configuration
esp32_hosted:
  type: spi
  variant: ESP32C6
  reset_pin: GPIOXX
  clk_pin: GPIOXX
  mosi_pin: GPIOXX
  miso_pin: GPIOXX
  cs_pin: GPIOXX
  handshake_pin: GPIOXX
  data_ready_pin: GPIOXX
  active_high: true

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

SPI Configuration variables

type (Required, string): The transport mode. Set to spi for SPI transport.
variant (Required, string): The variant of the ESP32 co-processor that is used by the host. One of ESP32, ESP32S2, ESP32S3, ESP32C2, ESP32C3 and ESP32C6.
reset_pin (Required, Pin): The reset pin of the co-processor.
active_high (Required, boolean): If enabled, the co-processor is active when reset is high. If disabled, the co-processor is active when reset is low.
clk_pin (Required, Pin): The SPI clock pin.
mosi_pin (Required, Pin): The SPI MOSI pin.
miso_pin (Required, Pin): The SPI MISO pin.
cs_pin (Required, Pin): The SPI chip select pin.
handshake_pin (Required, Pin): The handshake pin used by the co-processor to signal readiness.
data_ready_pin (Required, Pin): The data ready pin used by the co-processor to signal available data.
spi_mode (Optional, int): The SPI mode (0-3). Defaults depend on the variant: mode 2 for ESP32, mode 3 for all others.
frequency (Optional, frequency): The SPI clock frequency. Maximum depends on variant: 10MHz for ESP32, 40MHz for all other variants. Defaults to the maximum for each variant.
handshake_active_high (Optional, boolean): Polarity of the handshake signal. Defaults to true.
data_ready_active_high (Optional, boolean): Polarity of the data ready signal. Defaults to true.
use_psram (Optional, boolean): Place the SPI transport buffer pool in PSRAM instead of internal RAM. Requires the host MCU to have DMA-capable PSRAM enabled (ESP32-P4, ESP32-S3). Recommended when the host firmware uses most of internal RAM (for example, a large LVGL UI); without it, boot can fail with an spi_mempool_create assert. Defaults to false.

Updating co-processor firmware

You can update the firmware on your ESP32 co-processor using the Esp32 Hosted platform. This allows you to deploy firmware updates to the co-processor without manually reflashing it.

ESP-NOW on ESP32-P4

The ESP32-P4 has no radio of its own. When esp32_hosted is configured on an ESP32-P4 host, it also provides an ESP-NOW path by forwarding the ESP-NOW calls to the co-processor, so the ESP-NOW component works unchanged. Nothing extra is required beyond adding espnow: to your configuration; there is no separate component to add. On other ESP32 variants this behaviour is not needed and nothing changes.

Your co-processor firmware must support ESP-NOW. The prebuilt esp-hosted firmware provided by ESPHome includes ESP-NOW support, and you can flash it to the co-processor with the ESP32 Hosted update platform.

ESP-NOW works with or without Wi-Fi on the ESP32-P4: you can use ESP-NOW on its own, or run Wi-Fi in station mode and ESP-NOW at the same time.

NOTE

The ESP-NOW source MAC address is the co-processor’s radio MAC (for example, starting with E4:B3:23), not the ESP32-P4’s own MAC. Use the co-processor’s MAC when adding this device to a remote peer list.

WARNING

On the ESP32-P4, do not run espnow while Wi-Fi is in access point mode. ESP-NOW requires the station interface to be up.

# ESP32-P4 host with an ESP32-C6 co-processor
esp32_hosted:
  type: sdio
  variant: ESP32C6
  reset_pin: GPIOXX
  cmd_pin: GPIOXX
  clk_pin: GPIOXX
  d0_pin: GPIOXX
  d1_pin: GPIOXX
  d2_pin: GPIOXX
  d3_pin: GPIOXX
  active_high: true

espnow:
  on_broadcast:
    - lambda: |-
        ESP_LOGD("espnow", "Broadcast of %u bytes received, RSSI %ddBm", size, info.rx_ctrl->rssi);

interval:
  - interval: 10s
    then:
      - espnow.broadcast:
          data: "Hello from the ESP32-P4"