Skip to content
Get started

ESP32 Hosted Co-processor Update

This platform allows you to update the firmware of an ESP32 co-processor connected via the ESP32 Hosted component. Two update modes are supported:

  • Embedded mode: The firmware binary is embedded into your device’s flash at compile time
  • HTTP mode: The firmware is fetched from a remote URL at runtime

The component automatically detects the current co-processor firmware version and compares it to the available version. If the versions differ, an update becomes available in Home Assistant or through the ESPHome API.

In embedded mode, the firmware binary is compiled into your device’s flash. This is useful when you want to bundle a specific firmware version with your device.

# Example configuration entry for embedded mode
update:
- platform: esp32_hosted
type: embedded
path: coprocessor-firmware.bin
sha256: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

You can also use an HTTP or HTTPS url instead of path. ESPHome downloads the binary on the computer building your firmware and verifies its SHA256 before embedding it. The device does not need access to the firmware server.

update:
- platform: esp32_hosted
type: embedded
url: https://example.com/firmware/esp32c6.bin
sha256: "<SHA256_OF_FIRMWARE>"

Replace the URL and SHA256 placeholder with the firmware binary’s URL and its 64-character hexadecimal SHA256 hash. Configure exactly one of path or url. Both require sha256.

Downloaded images are cached under esp32_hosted/firmware in ESPHome’s data directory, normally .esphome next to your configuration. Each cached image is verified before use. A matching cached image is reused without contacting the server, so later builds do not need a network connection. A missing or damaged cache entry requires a new download; download failures and SHA256 mismatches stop configuration validation.

Ordinary Clean Build Files keeps these images. Reset Build Environment (esphome clean-all) removes them, so the next build requires access to the server again.

Embedding an image makes it available for installation. To install it automatically when an update is available, use on_update_available with the update.perform action:

update:
- platform: esp32_hosted
id: coprocessor_update
type: embedded
url: https://example.com/firmware/esp32c6.bin
sha256: "<SHA256_OF_FIRMWARE>"
on_update_available:
then:
- update.perform: coprocessor_update

Choose firmware compatible with your co-processor and the ESP-Hosted library version used by ESPHome. The binary must also fit the co-processor’s OTA partition. Embedded mode does not select a version from a manifest.

In HTTP mode, the firmware is fetched from a remote manifest URL. This allows automatic updates without recompiling your ESPHome configuration. The component will periodically check for updates and select the best compatible version based on the host library version.

# Example configuration entry for HTTP mode
http_request:
update:
- platform: esp32_hosted
type: http
source: https://esphome.github.io/esp-hosted-firmware/manifest/esp32c6.json
update_interval: 6h

The HTTP mode requires a JSON manifest file with the following format:

{
"versions": [
{
"version": "2.7.0",
"url": "https://example.com/firmware/esp32c6-2.7.0.bin",
"sha256": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
},
{
"version": "2.6.0",
"url": "https://example.com/firmware/esp32c6-2.6.0.bin",
"sha256": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321"
}
]
}

The component will automatically select the highest version that is compatible with the host library (i.e., the firmware version must be less than or equal to the ESP-Hosted library version compiled into ESPHome).

  • type (Required, string): The update mode to use. Must be either embedded or http.
  • path (Optional, string): Path to the co-processor firmware binary file (.bin). The path is relative to your ESPHome configuration file. Required when url is not set.

  • url (Optional, url): HTTP or HTTPS URL of the co-processor firmware binary (.bin), downloaded by ESPHome during configuration validation and embedded at compile time. Required when path is not set.

  • sha256 (Required, string): SHA256 hash of the firmware binary file. This is used to verify the integrity of the firmware both at compile time and at runtime before flashing to the co-processor.

  • source (Required, url): URL to the JSON manifest file containing available firmware versions.

  • update_interval (Optional, Time): How often to check for updates. Defaults to 6h.

  • All other options from Update.

This update platform requires:

  • Host device (running ESPHome): ESP32-H2 or ESP32-P4
  • Co-processor (being updated): Any ESP32 variant supported by ESP-Hosted (e.g., ESP32-C6 as shown in the example)

For embedded mode, the host device must have sufficient flash space to store the co-processor firmware binary.

Pre-built firmware binaries and manifests for supported co-processor variants are available at esphome.github.io/esp-hosted-firmware. These can be used directly with HTTP mode, or downloaded for use with embedded mode.

For instructions on building custom firmware, see the esp-hosted-firmware repository.