ESP32 OTA Updates
Relevant source files
The following files were used as context for generating this wiki page:
ESP32 Over-the-Air (OTA) updates allow the Muse Gadget to download and install new firmware images via HTTPS. This system validates the incoming firmware version against the currently running version before proceeding with the download, verification, and installation. Updates are disabled by default in standard builds but are enabled for boards that utilize the full on-screen UI.
Sources: esp32/main/ota.c:31-37, esp32/README.md:179-183
Architecture and Components
The OTA system operates as a background process on a dedicated FreeRTOS task. This design ensures that the main application threads, such as Bluetooth LE or WebSocket handlers, do not block during long-lasting network operations.
Key Components
| Component | Description |
|---|---|
| OTA Task | A dedicated task with a 16 KB stack that manages the HTTPS connection and flash writes. |
| Native HTTPS OTA | Uses the esp_https_ota component to handle secure downloads and image validation. |
| Version Gate | Logic that compares semantic versions (MAJOR.MINOR.PATCH) to prevent accidental downgrades. |
| OTA Context | A structure (ota_ctx_t) carrying the URL, force flags, and status callbacks to the worker task. |
Sources: esp32/main/ota.c:45-50, esp32/main/ota.c:116-118, esp32/main/ota.c:217-219
Technical Workflow
The following diagram illustrates the sequence of events from initiation to system reboot.
The diagram shows how the OTA worker task manages version validation and flashing independently of the calling application.
Sources: esp32/main/ota.c:118-185, esp32/tests/link_ota_harness.c:83-100
Version Validation Logic
The system parses version strings in the format [v]MAJOR.MINOR.PATCH. Non-numeric suffixes, such as those generated by git-describe, are ignored during the numeric comparison but are used as a fallback for equality checks.
- Numeric Comparison: The system checks Major, then Minor, then Patch components.
- String Fallback: If numeric components are identical, any difference in the full version string is treated as a newer version.
- Force Flag: Setting
forcetotruebypasses the version gate, allowing for downgrades or re-installations of the same version.
Sources: esp32/main/ota.c:54-81
Triggering Updates via Noise Control
Updates are typically triggered remotely through the device.ota command sent over a Noise-encrypted control session. The noise_control.cpp module receives the command and initializes the OTA process.
Command Payload
The device.ota command requires an HTTPS URL and accepts an optional boolean force parameter.
{
"method": "link.invoke",
"command": "device.ota",
"params": {
"url": "https://example.com/firmware.bin",
"force": false
}
}
Sources: esp32/main/noise_control.cpp:669-693
Implementation Details
Stack and Resource Requirements
The OTA task requires an 16,384 byte (16 KB) stack to safely handle TLS handshakes and flash write operations. It also utilizes the ESP-IDF CRT bundle to attach root certificates for HTTPS validation.
Sources: esp32/main/ota.c:127-133, esp32/main/ota.c:218
Function Reference
| Function | Purpose |
|---|---|
ota_is_enabled() | Returns true if CONFIG_HOMEHUB_OTA_ENABLED is set. |
ota_start(...) | Validates the URL and spawns the ota_task to handle the update. |
version_is_newer(...) | Compares two version strings using semantic versioning rules. |
ota_task(...) | The main worker function that manages the HTTPS client and partition switching. |
Sources: esp32/main/ota.c:23-28, esp32/main/ota.c:70-81, esp32/main/ota.c:118-120, esp32/main/ota.c:203-205
Configuration
OTA features are controlled via Kconfig options. Standard development builds often use version 999.0.0 as a placeholder.
- Enable OTA:
CONFIG_HOMEHUB_OTA_ENABLEDmust be set toy. - Project Version: Defined via
idf.py -DPROJECT_VER=X.X.X build. - Partition Table: OTA requires a partition table that includes multiple app slots (e.g.,
partitions_muse.csvorpartitions_muse_8mb.csv).
Sources: esp32/README.md:179-183, esp32/devices/AGENTS.md:105-108, esp32/main/CMakeLists.txt:46-51
Conclusion
The ESP32 OTA update system provides a secure, background-processed method for firmware maintenance. By integrating with the Noise control protocol and semantic versioning, it ensures gadget stability while allowing remote updates to the latest software versions.