Firmware Flashing
Relevant source files
The following files were used as context for generating this wiki page:
Firmware flashing installs the Muse Gadget software onto ESP32-compatible hardware via a serial connection. This process enables the device to connect to home Wi-Fi, pair with the Muse mobile application, and establish encrypted sessions with a Virtual Machine (VM). The project supports multiple board targets including ESP32-C5, ESP32-S3, and specialized community ports like the ESP32 CYD.
Sources: board-port/esp32/AGENTS.md:21-25, README.md:1-5
Build Prerequisites
You must install specific tools and configurations before attempting to flash the firmware.
- ESP-IDF v6.0.1: The project requires version 6.0.1 of the Espressif IoT Development Framework. Other versions are unsupported and cause header errors.
- SDK Token: Every build requires a unique token (
mgst_...) obtained from the Muse dashboard. You must set this viaCONFIG_GADGET_SDK_TOKENoridf.py menuconfig. - USB Data Cable: You need a cable capable of serial data transfer. Cables that only provide power will not detect the device port.
Sources: board-port/esp32/AGENTS.md:31-35, board-port/esp32/README.md:120-125, board-port/esp32/AGENTS.md:95-100
Flashing Procedure
The flashing process involves transferring the compiled binaries to the ESP32 flash memory.
Standard Flashing Process
For standard development boards, use the idf.py tool. This tool handles the baud rate, reset sequence, and partition mapping automatically.
idf.py -p PORT flash
Sources: board-port/esp32/AGENTS.md:195-200
Manual Partition Flashing
If you are flashing without idf.py, you must write individual binaries to specific memory offsets.
| Binary | Offset | Description |
|---|---|---|
bootloader.bin | 0x1000 | The primary bootloader for the ESP32 chip. |
partition-table.bin | 0x10000 | Defines memory layout (App, NVS, OTA data). |
ota_data_initial.bin | 0x17000 | Stores information for Over-the-Air updates. |
phy_init_data.bin | 0x19000 | Radio/Physical layer configuration. |
muse-gadget.bin | 0x20000 | The main application firmware. |
Sources: README.md:83-93, board-port/esp32/AGENTS.md:255-260
Flash Flow Control
The following diagram illustrates the sequence for establishing a connection and writing the firmware:
The diagram shows the logic for handling port detection and hardware synchronization during the flash process.
Sources: board-port/esp32/README.md:135-140, README.md:100-105
Specialized Board Handling
Certain boards require custom flashing parameters or pacing to prevent hardware errors.
SenseCAP Watcher
The SenseCAP Watcher uses a CH342 USB bridge which lacks flow control. Sending data at standard speeds causes checksum errors (0107) or invalid message formats (0105). You must use the paced_esptool.py wrapper to send 64 bytes at a time at 115200 baud.
Sources: board-port/esp32/AGENTS.md:220-235
M5Stack StickC Plus2
This board uses a CH9102 bridge that becomes unstable above 230400 baud. You must limit the flash speed to 230400 to ensure a successful write.
Sources: board-port/esp32/AGENTS.md:210-215
Post-Flashing Verification
After a successful flash, the device executes the startup sequence.
Status Indicators
The firmware uses LEDs or screen animations to communicate the system state:
- Orange (Breathing): The device is in a fresh state and waiting for BLE advertising/setup.
- Blue (Breathing): The device is waiting for a physical button press to confirm pairing.
- Green: The device has established a connection to the Muse VM.
- Red (Blinking): A system error or crash has occurred.
Sources: board-port/esp32/README.md:155-170, board-port/esp32/main/app.c:1150-1175
Startup Monitoring
You can monitor the boot process using the serial console. A healthy boot displays the log line: link.main: Muse Gadget starting.
idf.py -p PORT monitor
Sources: board-port/esp32/AGENTS.md:275-280
Security and Persistence
The flashing process is designed to preserve user configuration where possible.
- NVS Persistence: Standard flashing ignores the Non-Volatile Storage (NVS) partition. This ensures Wi-Fi credentials and pairing tokens survive firmware updates.
- Full Erase: To remove all credentials, you must explicitly run
idf.py erase-flash. - Secure Boot: Secure Boot is not enabled by default. The application is signed with a development key (
dev_signing_key.pem) to allow repeated flashing without burning hardware eFuses. - NVS Encryption: Enabling
CONFIG_HOMEHUB_NVS_ENCRYPTIONencrypts credentials on the first boot using a key derived from the eFuse block.
Sources: board-port/esp32/AGENTS.md:265-270, board-port/esp32/README.md:245-255, board-port/esp32/main/app.c:450-460
Summary
Firmware flashing is the entry point for turning ESP32 hardware into a functional Muse Gadget. By adhering to the ESP-IDF v6.0.1 requirements and utilizing specific board helpers (like tools/board.sh), you can reliably deploy the firmware. The system is designed to facilitate iterative development by preserving pairing data across flashes while maintaining options for security through NVS encryption.