Partition Tables & OTA
Relevant source files
The following files were used as context for generating this wiki page:
The Muse Gadget SDK uses a custom partition layout and an Over-the-Air (OTA) update system to manage firmware lifecycle and device recovery. The system ensures that devices can be updated remotely via Bluetooth Low Energy (BLE) or an encrypted Noise Control session while providing safety mechanisms to roll back failed updates.
Partition Table Architecture
The project utilizes a specific partition configuration to accommodate secure boot requirements and large application sizes. By default, the partition table is located at offset 0x10000, which differs from the standard ESP-IDF offset of 0x8000 to provide space for a larger Secure Boot bootloader.
Key Partition Layout Components
| Partition Name | Typical Size | Description |
|---|---|---|
nvs | Varies | Stores Wi-Fi credentials, pairing tokens, and device configuration. |
otadata | Varies | Stores OTA selection data to determine which app slot to boot. |
ota_0 | 2 MB / 4 MB | Primary application slot. |
ota_1 | 2 MB / 4 MB | Secondary application slot for OTA updates. |
prod_data | Fixed | Manufacturing data location. |
prod_bak | Fixed | Backup manufacturing data location. |
nvsfactory | Varies | Factory data specific to certain boards (e.g., SenseCAP Watcher). |
App slots are typically 2 MB, but Muse-enabled boards increase this to 4 MB to accommodate the UI and audio components.
Sources: board-port/esp32/AGENTS.md:329-335, board-port/esp32/AGENTS.md:275-277, workflows/build-release.yml:62-67
OTA Update System
OTA updates are handled through the ota.c module and can be triggered via two main channels: BLE provisioning or a WebSocket command through the Noise Control session.
OTA Configuration and Security
- Enablement: OTA is disabled by default (
CONFIG_HOMEHUB_OTA_ENABLED=n) unless using a full UI board profile. - Versioning: Versions are assigned via
PROJECT_VERor aversion.txtfile. Default developer builds use version999.0.0. - Signing: Application images are signed with a development key (
dev_signing_key.pem). Secure Boot and Flash Encryption are not enabled by default to allow frequent reflashing during development.
Sources: board-port/esp32/AGENTS.md:323-328, board-port/esp32/README.md:155-163
OTA Execution Flow
When a device.ota command is received with a valid HTTPS URL, the system initiates the following process:
The device verifies connectivity before beginning the download. Successful flashing puts the new partition in a "pending verify" state.
Sources: board-port/esp32/main/app.c:1347-1375, board-port/esp32/main/noise_control.cpp:575-613
Verification and Rollback Mechanism
The SDK implements a "Health Check" verification pattern to prevent bricking devices with unreachable firmware.
The Verification Task
Upon booting a new OTA image, the device enters the ESP_OTA_IMG_PENDING_VERIFY state. The ota_verify_task starts and waits for the device to successfully establish a control WebSocket (Noise session) with the Muse backend.
- Timeout: The image has 300 seconds (
OTA_VERIFY_TIMEOUT_US) to reach the authenticated control WebSocket. - Success: If the connection is established, the image is marked valid using
esp_ota_mark_app_valid_cancel_rollback(). - Failure: If the timeout expires without a successful connection, the bootloader reverts the device to the previous known-working firmware slot using
esp_ota_mark_app_invalid_rollback_and_reboot().
Sources: board-port/esp32/main/app.c:116-121, board-port/esp32/main/app.c:1356-1375
Firmware Release Packaging
Automated workflows (e.g., GitHub Actions) package the necessary binaries for manual flashing. A complete firmware package includes:
bootloader.binpartition-table.binota_data_initial.bin(initializes the OTA selection)phy_init_data.binmuse-gadget.bin(the application)
Sources: workflows/build-release.yml:62-72
Summary
The partition and OTA system provides a robust framework for firmware management. By utilizing dual app slots and a mandatory verification window that requires backend connectivity, the system minimizes the risk of firmware updates rendering devices unrecoverable. All updates are performed over HTTPS and integrated into the encrypted Noise Control session.