Local Compilation Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Local Compilation Guide describes the environment setup, configuration, and build procedures for the Muse Gadget firmware. This firmware powers Muse Home Link devices, enabling pairing over BLE, Wi-Fi connectivity, and encrypted Noise sessions to virtual machines.
Developers use this guide to compile the open-source firmware for various ESP32-compatible boards. The build system relies on the Espressif IoT Development Framework (ESP-IDF) and specialized scripts to manage board-specific overlays and SDK tokens.
Sources: board-port/esp32/AGENTS.md:21-25, board-port/esp32/README.md:17-21
Development Environment Setup
Local compilation requires specific hardware and software prerequisites. You must use a computer running macOS or Linux.
Hardware Requirements
- ESP32 Board: Supported chips include ESP32-C5, ESP32-C6, ESP32-S3, and classic ESP32.
- USB Data Cable: The cable must support data transfer for flashing and monitoring.
Sources: board-port/esp32/README.md:28-31, board-port/esp32/AGENTS.md:28-30
Software Requirements
- ESP-IDF v6.0.1: This is the only supported version. Other versions cause header errors (e.g.,
gcm.h). - Python 3: Required for build scripts and host-side tests.
- Build Tools:
cmake,ninja,dfu-util, and a C/C++ compiler (cc,c++).
Sources: board-port/esp32/README.md:73-77, board-port/esp32/AGENTS.md:28-29
Installation Procedure (macOS/Linux)
- Install host prerequisites via
brew(macOS) orapt(Linux). - Clone the ESP-IDF repository at the specific tag:
git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6 - Run the install script for target chips:
~/esp/esp-idf-v6/install.sh esp32c5,esp32s3,esp32c6,esp32 - Activate the environment (required for every new terminal):
. ~/esp/esp-idf-v6/export.sh
Sources: board-port/esp32/README.md:78-83, board-port/esp32/AGENTS.md:28-29
Build Configuration
The project uses a tiered configuration system. Base settings reside in sdkconfig.defaults, while board-specific hardware maps reside in devices/sdkconfig.<board> overlays.
SDK Token Configuration
Every build requires a Muse Gadget SDK token (mgst_...) obtained from gadgets.muse.ai. You must set this token before compiling, as it is baked into the firmware.
Sources: board-port/esp32/README.md:88-89, board-port/esp32/AGENTS.md:83-85
Build Commands
The following table summarizes the build methods for different targets:
| Target Method | Command | Directory Output |
|---|---|---|
| Default (C5 DevKit) | idf.py build | build/ |
| Board Helper | tools/board.sh <board> build | build-<board>/ |
| Full UI Boards | tools/muse/board.sh build <profile> | build-muse-<profile>/ |
| Manual Override | idf.py -DSDKCONFIG_DEFAULTS="defaults;overlay" build | User defined |
Sources: board-port/esp32/README.md:91-92, board-port/esp32/AGENTS.md:95-103, board-port/esp32/AGENTS.md:120-123
Build Process Flow
This diagram illustrates the sequence from environment setup to a flashable binary.
The build process incorporates board overlays and the SDK token into the final binary.
Sources: board-port/esp32/README.md:88-92, board-port/esp32/AGENTS.md:286-289
Firmware Components and Source Structure
The CMakeLists.txt file defines the source files and component requirements. The build links the muse-gadget app with various system and custom components.
Core Source Files
main/main.c: The firmware entry point.main/app.c: Primary application logic and command handling.main/noise_control.cpp: Manages encrypted Noise sessions and WebSocket transport.main/led_status.c: Drives the status LED and display bars.
Sources: board-port/esp32/main/CMakeLists.txt:18-45, board-port/esp32/AGENTS.md:23-25
Critical Dependencies
The firmware requires standard ESP-IDF components (esp_wifi, nvs_flash) and custom project components:
noise_core: Cryptographic session management.muse: UI, avatar, and voice chat modules (used on boards with PSRAM).led_strip: Required for addressable status lights.
Sources: board-port/esp32/main/CMakeLists.txt:47-75
Flashing and Monitoring
Flashing transfers the compiled binaries to the ESP32 chip. The process involves identifying the correct serial port and using esptool or idf.py.
Flashing Procedure
- Connect the board via USB.
- Identify the port (e.g.,
/dev/cu.usbmodem*for native USB or/dev/cu.usbserial-*for bridges). - Run the flash command:
idf.py -p PORT flash monitor - If the connection fails, manually enter bootloader mode: Hold BOOT, tap RESET, release BOOT.
Sources: board-port/esp32/README.md:98-103, board-port/esp32/AGENTS.md:200-205
Partition Table and Addresses
Flashing writes multiple components to specific offsets:
| Component | Offset | Description |
|---|---|---|
| Bootloader | 0x1000 | Initial startup code |
| Partition Table | 0x10000 | Layout of flash memory |
| App Slot | 0x20000 | The primary muse-gadget.bin |
| NVS | Varies | Pairing and Wi-Fi credentials |
Sources: board-port/esp32/AGENTS.md:225-228, README.md:58-65
Monitoring Sequence
This diagram shows the interaction between the host computer and the device during a flash-monitor session.
The monitor resets the board to capture logs from the initial boot sequence.
Sources: board-port/esp32/AGENTS.md:238-245, board-port/esp32/README.md:100-101
Testing and Verification
Before deploying firmware, developers run host-side tests and perform on-device verification.
Host-Side Tests
Host tests compile C/C++ logic against fakes on the local computer. They do not require a board.
python3 -m unittest discover -s tests -p 'test_*.py'
Sources: board-port/esp32/README.md:154-156, board-port/esp32/AGENTS.md:330-333
Verification Checklist
- Boot Log: Ensure the log reaches
link.main: Muse Gadget starting. - Status Light: Verify the light breathes orange (ready for setup).
- App Slot: Confirm the binary fits within the 2 MB (or 4 MB) partition limit.
Sources: board-port/esp32/AGENTS.md:344-348, board-port/esp32/AGENTS.md:286-289
The Local Compilation Guide ensures that developers can produce consistent, functional firmware. By following the ESP-IDF v6.0.1 toolchain requirements and using the provided board overlays, users can extend the Muse Gadget SDK to new hardware while maintaining security and connectivity standards.