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.
Embedded Mode
Section titled “Embedded Mode”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 modeupdate: - platform: esp32_hosted type: embedded path: coprocessor-firmware.bin sha256: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdefYou 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_updateChoose 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.
HTTP Mode
Section titled “HTTP Mode”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 modehttp_request:
update: - platform: esp32_hosted type: http source: https://esphome.github.io/esp-hosted-firmware/manifest/esp32c6.json update_interval: 6hManifest Format
Section titled “Manifest Format”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).
Configuration variables
Section titled “Configuration variables”- type (Required, string): The update mode to use. Must be either
embeddedorhttp.
Embedded mode options
Section titled “Embedded mode options”-
path (Optional, string): Path to the co-processor firmware binary file (
.bin). The path is relative to your ESPHome configuration file. Required whenurlis 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 whenpathis 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.
HTTP mode options
Section titled “HTTP mode options”-
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.
Common options
Section titled “Common options”- All other options from Update.
Platform requirements
Section titled “Platform requirements”This update platform requires:
- Host device (running ESPHome):
ESP32-H2orESP32-P4 - Co-processor (being updated): Any ESP32 variant supported by ESP-Hosted (e.g.,
ESP32-C6as shown in the example)
For embedded mode, the host device must have sufficient flash space to store the co-processor firmware binary.
Co-processor firmware
Section titled “Co-processor firmware”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.