Host Tests & Automation
Relevant source files
The following files were used as context for generating this wiki page:
Host tests and automation provide a framework for verifying firmware logic and automating the build-to-release pipeline without requiring physical ESP32 hardware for every iteration. This system consists of Python-based unit tests that link firmware C/C++ code against fakes, specialized scripts for device interaction, and GitHub Actions workflows for continuous integration and delivery.
Sources: board-port/esp32/AGENTS.md:465-468, board-port/esp32/README.md:213-215
Host Test Framework
The project uses Python's unittest module to perform host-side verification of C and C++ components. These tests compile firmware logic against mock environments, allowing developers to validate command registration, parser logic, and cryptographic handshakes on a standard PC.
Test Execution & Requirements
You run tests using the unittest discover command. A successful idf.py build must occur at least once before testing to ensure managed_components (like cJSON) are available in the workspace.
| Test Category | Requirements | Description |
|---|---|---|
| Discovery/Link | cJSON | Verifies command advertising and dispatching logic. |
| Noise Core | libmbedtls-dev, pkg-config | Tests against the host's PSA Crypto library. |
| Pairing Handshake | IDF_PATH or MBEDTLS_SOURCE_DIR | Builds Mbed TLS from source for real-crypto validation. |
Sources: board-port/esp32/AGENTS.md:465-480, board-port/esp32/README.md:213-222
Component Verification Logic
Tests like LinkCydExtrasTest inspect the source code files directly to ensure specific features are correctly implemented and advertised in the firmware.
Automated Build & Release Pipeline
The project utilizes GitHub Actions to automate the creation of firmware binaries and deployment packages. The Build CYD firmware workflow centralizes the environment setup, compilation, and artifact packaging.
Build Workflow Architecture
The workflow operates within a Docker container (espressif/idf:v6.0.1) to ensure toolchain consistency. It performs the following sequence:
- Cloning: Retrieves the
muse-gadget-sdkat a specific pinned commit. - Overlaying: Copies the
board-port/directory into the SDK structure to apply board-specific configurations. - Compilation: Injects the
GADGET_SDK_TOKENsecret and runsidf.py buildfor the target board (e.g.,esp32for CYD). - Packaging: Aggregates the
bootloader.bin,partition-table.bin, and application binary into a zip file with flashing scripts. - Release: Publishes the package as a GitHub Release when a version tag is pushed.
Sources: workflows/build-release.yml:15-80
Device SDK Automation Tools
Automation extends to developer tools that facilitate interaction with the hardware over serial ports. These tools assist in identifying connected boards and managing setup without manual configuration.
Board Identification Logic
Automated scripts like tools/muse/ports.py and tools/muse/chat.py identify boards based on USB descriptors and firmware responses.
| Identification Method | Source Data | Target Boards |
|---|---|---|
| Firmware Status | tools/muse/chat.py --status | Running Muse firmware |
| USB Vendor ID | 303a:1001 (Espressif) | C5, C6, S3 Native USB |
| USB Bridge Type | 1a86:7523 (CH340) | Ideaspark, SenseCAP, reTerminal |
| Chip ID | esptool chip-id | All ESP32 targets |
Sources: board-port/esp32/AGENTS.md:167-210
Paced Flashing Automation
For boards with sensitive USB-to-Serial bridges, such as the SenseCAP Watcher (CH342), the system uses tools/muse/paced_esptool.py. This wrapper automates data pacing by sending 64 bytes at a time to prevent buffer overflows and checksum errors during the flashing process.
Sources: board-port/esp32/AGENTS.md:246-265
Summary
Host Tests & Automation ensures the integrity of the Muse Gadget ecosystem by validating code logic in simulated environments and standardizing the build process. The integration of Python-based unit tests and GitHub Actions allows for rapid development cycles while maintaining compatibility across a diverse range of ESP32-based hardware.