Automated Builds & Releases
Relevant source files
The following files were used as context for generating this wiki page:
The Automated Builds & Releases system manages the compilation, packaging, and distribution of Muse Gadget firmware for ESP32-based devices. It uses GitHub Actions to automate the integration of the Muse Gadget SDK with specific board ports, such as the ESP32 Cheap Yellow Display (CYD), ensuring consistent binary generation and public availability via GitHub Releases.
This system centralizes the build logic within the workflows/build-release.yml file, utilizing Docker containers with the Espressif IoT Development Framework (ESP-IDF) to maintain environment parity across builds. It handles the injection of sensitive SDK tokens and packages necessary flash binaries into a single distributable archive for end-users.
Continuous Integration Workflow Architecture
The build process operates in two primary stages: a build job that compiles the code and a release job that publishes the artifacts. The workflow triggers on manual dispatch or when a new version tag (e.g., v*) is pushed to the repository.
The diagram shows the sequential flow from source acquisition to the final release of the firmware package.
Sources: workflows/build-release.yml:1-85, README.md:27-38
Build Environment and Dependencies
The system uses a standardized environment to prevent version mismatches. It specifically requires ESP-IDF v6.0.1, as other versions are unsupported by the firmware logic.
Dependency Management
- Base SDK: Clones the
facebookincubator/muse-gadget-sdkat a pinned commit (b139b45064b4dcecf7bfe97e75bc7f99c10c28b6). - Board Port: Overlays the
board-port/directory from the local repository onto the SDK structure. - Toolchain: Uses the
espressif/idf:v6.0.1Docker image for all compilation tasks. - Secrets: Injects
GADGET_SDK_TOKENfrom repository secrets into thesdkconfigduring the build process.
Sources: workflows/build-release.yml:11-49, board-port/esp32/README.md:85-98, board-port/esp32/AGENTS.md:32-35
Firmware Compilation and Packaging
The compilation step targets the esp32 chip family and applies specific board configuration defaults. For the CYD board, it uses devices/sdkconfig.cyd.
Build Commands
The workflow executes the following primary build command:
idf.py -B build-cyd -DIDF_TARGET=esp32 -DSDKCONFIG="$PWD/build-cyd/sdkconfig" \
-DSDKCONFIG_DEFAULTS="sdkconfig.defaults;devices/sdkconfig.cyd;/tmp/sdkconfig.token" build
Sources: workflows/build-release.yml:58-61, README.md:52-60
Package Structure
The resulting muse-gadget-cyd-firmware.zip contains all components required for a complete device flash:
| File | Description | Source Path |
|---|---|---|
bootloader.bin | The secondary bootloader | sdk/esp32/build-cyd/bootloader/ |
partition-table.bin | Defines flash layout | sdk/esp32/build-cyd/partition_table/ |
ota_data_initial.bin | OTA state information | sdk/esp32/build-cyd/ |
phy_init_data.bin | PHY calibration data | sdk/esp32/build-cyd/ |
muse-gadget.bin | Main application firmware | sdk/esp32/build-cyd/ |
flash.sh / flash.bat | Automation scripts for flashing | Repository root |
Sources: workflows/build-release.yml:64-74, README.md:73-77
Release Management and Distribution
Once the build job completes successfully, the release job downloads the zipped artifact and creates a GitHub Release. This release includes instructions for pairing and flashing, targeting the Cheap Yellow Display hardware specifically.
The sequence diagram illustrates how the build artifact is transferred from internal job storage to a public release.
Sources: workflows/build-release.yml:78-106
Security and Versioning Policies
The project maintains a structured security policy and versioning scheme to support ongoing updates.
- Supported Versions: Security updates are provided for version 5.1.x and 4.0.x. Older versions like 5.0.x and < 4.0 are not supported.
- Version Identification: Default development builds are tagged as version
999.0.0unless overridden during the build command using-DPROJECT_VER. - Over-the-Air (OTA) Updates: OTA functionality is disabled by default for most boards (
CONFIG_HOMEHUB_OTA_ENABLED=n) but is enabled for boards running the full on-screen UI.
Sources: SECURITY.md:1-12, board-port/esp32/README.md:275-280, board-port/esp32/AGENTS.md:231-233
Conclusion
The automated build and release system ensures that the Muse Gadget firmware is compiled in a reproducible environment and delivered to users with all necessary flashing tools. By integrating the SDK with board-specific ports automatically, the project simplifies the process of bringing Muse connectivity to community hardware like the Cheap Yellow Display.