Skip to content

Commit 2cf7f66

Browse files
swoboda1337bdraco
swoboda1337
and
bdraco
authored
[esp32_hosted] Add update docs (#5532)
* Add update docs * Fix lint * Update docs * Update content/components/update/esp32_hosted.md Co-authored-by: J. Nick Koston <nick+github@koston.org> * Update content/components/update/esp32_hosted.md Co-authored-by: J. Nick Koston <nick+github@koston.org> * Update content/components/update/esp32_hosted.md Co-authored-by: J. Nick Koston <nick+github@koston.org> * Add hash instructions --------- Co-authored-by: J. Nick Koston <nick+github@koston.org>
1 parent b4acdf2 commit 2cf7f66

File tree

3 files changed

+114
-0
lines changed

3 files changed

+114
-0
lines changed

‎content/components/esp32_hosted.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,15 @@ wifi:
4848
- **active_high** (*Required*, boolean): If enabled, the co-processor is active when reset is
4949
high. If disabled, the co-processor is active when reset is low.
5050

51+
## Updating co-processor firmware
52+
53+
You can update the firmware on your ESP32 co-processor using the {{< docref "update/esp32_hosted/" >}}
54+
platform. This allows you to deploy firmware updates to the co-processor without manually reflashing it.
55+
5156
## See Also
5257

5358
- {{< docref "wifi/" >}}
5459
- {{< docref "network/" >}}
5560
- {{< docref "ethernet/" >}}
61+
- {{< docref "update/esp32_hosted/" >}}
5662
- [ESP-Hosted-MCU](https://github.com/espressif/esp-hosted-mcu) by [Espressif Systems](https://www.espressif.com/)

‎content/components/update/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,4 +65,9 @@ Configuration variables:
6565

6666
- **id** (**Required**, [ID](#config-id)): The ID of the update entity.
6767

68+
## Update Platforms
69+
70+
- {{< docref "update/http_request/" >}}
71+
- {{< docref "update/esp32_hosted/" >}}
72+
6873
## See Also

‎content/components/update/esp32_hosted.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
description: "Instructions for using the ESP32 Hosted update platform to manage co-processor firmware updates."
3+
title: "ESP32 Hosted Co-processor Update"
4+
params:
5+
seo:
6+
description: Instructions for using the ESP32 Hosted update platform to manage co-processor firmware updates.
7+
image: system-update.svg
8+
---
9+
10+
This platform allows you to update the firmware of an ESP32 co-processor connected via the
11+
{{< docref "/components/esp32_hosted" >}} component. The firmware binary is embedded into
12+
your device's flash at compile time and can be deployed to the co-processor on demand.
13+
14+
The component automatically detects the current co-processor firmware version and compares it to the
15+
version embedded in your device. If the versions differ, an update becomes available in Home Assistant
16+
or through the ESPHome API.
17+
18+
```yaml
19+
# Example configuration entry
20+
# Note: Host device must be ESP32-H2 or ESP32-P4
21+
esp32_hosted:
22+
variant: ESP32C6 # Co-processor variant
23+
reset_pin: GPIOXX
24+
cmd_pin: GPIOXX
25+
clk_pin: GPIOXX
26+
d0_pin: GPIOXX
27+
d1_pin: GPIOXX
28+
d2_pin: GPIOXX
29+
d3_pin: GPIOXX
30+
active_high: true
31+
32+
update:
33+
- platform: esp32_hosted
34+
path: coprocessor-firmware.bin
35+
sha256: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
36+
```
37+
38+
{{< anchor "update_esp32_hosted-configuration_variables" >}}
39+
40+
## Configuration variables
41+
42+
- **path** (**Required**, string): Path to the co-processor firmware binary file (`.bin`).
43+
The path is relative to your ESPHome configuration file.
44+
45+
- **sha256** (**Required**, string): SHA256 hash of the firmware binary file. This is used to verify
46+
the integrity of the firmware both at compile time and at runtime before flashing to the co-processor.
47+
48+
- All other options from [Update](#config-update).
49+
50+
## Platform requirements
51+
52+
This update platform requires:
53+
54+
- **Host device** (running ESPHome): `ESP32-H2` or `ESP32-P4`
55+
- **Co-processor** (being updated): Any ESP32 variant supported by ESP-Hosted (e.g., `ESP32-C6` as shown in the example)
56+
57+
The host device must have sufficient flash space to store the co-processor firmware binary.
58+
59+
## Obtaining co-processor firmware
60+
61+
To build firmware for your ESP32 co-processor, refer to the
62+
[ESP IDF Get Started](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html). The
63+
firmware should be built using the ESP-IDF framework and the resulting `.bin` file should be placed in your ESPHome
64+
configuration directory.
65+
66+
```sh
67+
# Build instructions for IDF 5.5.1 and ESP Hosted 2.6.1
68+
git clone -b v5.5.1 --recursive https://github.com/espressif/esp-idf.git
69+
cd esp-idf
70+
./install.sh esp32c6
71+
source export.sh # for Linux/macOS
72+
export.bat # for Windows
73+
cd ..
74+
idf.py create-project-from-example "espressif/esp_hosted^2.6.1:slave"
75+
cd slave/
76+
idf.py set-target esp32c6
77+
idf.py build
78+
```
79+
80+
After building the firmware, copy it to your ESPHome configuration directory and generate its SHA256 hash:
81+
82+
```sh
83+
# Copy the firmware to your ESPHome config directory
84+
cp build/network_adapter.bin /path/to/your/esphome/config/coprocessor-firmware.bin
85+
86+
# Generate SHA256 hash (Linux/macOS)
87+
sha256sum /path/to/your/esphome/config/coprocessor-firmware.bin
88+
89+
# Generate SHA256 hash (Windows PowerShell)
90+
Get-FileHash -Algorithm SHA256 coprocessor-firmware.bin
91+
92+
# Generate SHA256 hash (Windows Command Prompt with certutil)
93+
certutil -hashfile coprocessor-firmware.bin SHA256
94+
```
95+
96+
Use the generated hash in your `sha256` configuration parameter.
97+
98+
## See Also
99+
100+
- {{< docref "/components/esp32_hosted" >}}
101+
- {{< docref "/components/update" >}}
102+
- [ESP-Hosted-MCU](https://github.com/espressif/esp-hosted-mcu) by [Espressif Systems](https://www.espressif.com/)
103+
- {{< apiref "esp32_hosted/update/esp32_hosted_update.h" "esp32_hosted/update/esp32_hosted_update.h" >}}

0 commit comments

Comments
 (0)