Board Helper CLI Tools
Relevant source files
The following files were used as context for generating this wiki page:
Board Helper CLI Tools automate the building, flashing, and monitoring of firmware for specific ESP32 hardware configurations. These tools manage environment exports, target selection, and configuration overlays to ensure consistent builds across diverse board types.
The primary interface is tools/board.sh, which wraps the standard idf.py commands with hardware-specific presets. This system allows developers to target multiple devices, such as the ESP32-C5 DevKitC-1 or the ESP32 CYD (Cheap Yellow Display), without manually managing complex build arguments for each profile.
Sources: board-port/esp32/tools/board.sh:17-40, board-port/esp32/README.md:162-165
Core Utility: board.sh
The tools/board.sh script executes firmware lifecycle actions for a defined BOARD. It creates unique build directories (e.g., build-<board>) to prevent configuration clashes between different hardware targets.
Execution Flow
When you run the script, it performs the following steps:
- Validates the requested board profile and action.
- Locates and sources the ESP-IDF
export.shscript ifidf.pyis not in the systemPATH. - Auto-detects the serial port based on the board's known USB bridge descriptors if no port is provided.
- Executes the corresponding
idf.pycommand using specificSDKCONFIG_DEFAULTSoverlays.
Sources: board-port/esp32/tools/board.sh:42-132, board-port/esp32/AGENTS.md:73-81
The following diagram illustrates the internal logic of the board helper script:
The diagram shows how the script resolves environment dependencies and port detection before delegating to the ESP-IDF toolchain.
Sources: board-port/esp32/tools/board.sh:84-118
Supported Boards and Actions
The helper tools support a variety of boards by mapping a simple identifier to a specific chip target and configuration file.
Actions
The script supports four primary actions:
- build: Compiles the source code into a binary.
- flash: Writes the compiled binary to the device via serial.
- monitor: Opens the serial console to view device logs.
- flash-monitor: Performs both flashing and monitoring sequentially.
Sources: board-port/esp32/tools/board.sh:102-107
Board Profile Table
The following table describes the profiles managed by the CLI tools:
| Board Identifier | Target Chip | Configuration Overlays | Description |
|---|---|---|---|
devkit | esp32c5 | sdkconfig.defaults | ESP32-C5 DevKitC-1 (default) |
c6-nopsram | esp32c6 | devices/sdkconfig.c6-nopsram | C6 devkit lacking PSRAM |
ideaspark | esp32 | devices/sdkconfig.ideaspark | 1.9" ST7789 display board |
sensecap-indicator | esp32s3 | devices/sdkconfig.sensecap-indicator | S3 with 4" display |
cyd | esp32 | devices/sdkconfig.cyd | Cheap Yellow Display (ILI9341) |
home-assistant-voice | esp32s3 | devices/sdkconfig.home-assistant-voice | Voice PE with LED ring |
Sources: board-port/esp32/tools/board.sh:46-81, board-port/esp32/AGENTS.md:50-71
Port Detection Logic
For flashing and monitoring, the tools identify the device by its USB-to-UART bridge. The script checks for the existence of specific device paths based on the board's hardware.
- Native USB (C5, C6, S3): Searches for
/dev/cu.usbmodem*(macOS) or/dev/ttyACM*(Linux). - CH340/WCH Bridges (CYD, ideaspark): Searches for
/dev/cu.usbserial-*or/dev/cu.wchusbserial*.
If the script finds exactly one matching port, it selects it automatically. If multiple or zero ports match, the script prompts you to provide the port explicitly.
Sources: board-port/esp32/tools/board.sh:110-118, board-port/esp32/AGENTS.md:144-152
Auxiliary Tools
Beyond board.sh, the project includes specialized Python scripts and build wrappers for UI-enabled boards.
UI Board Helper
The tools/muse/board.sh script handles boards with the full Graphical User Interface (GUI). It clears managed_components/ before builds to prevent library version clashes and uses specific partition tables (e.g., partitions_muse.csv for 16MB boards or partitions_muse_8mb.csv for 8MB boards).
Sources: board-port/esp32/AGENTS.md:104-114
Paced Flash Wrapper
For the Seeed SenseCAP Watcher, which uses a CH342 bridge without flow control, the tools/muse/paced_esptool.py utility is used. This tool wraps esptool.py and limits data transmission to 64 bytes at a time to prevent checksum errors during flashing.
Sources: board-port/esp32/AGENTS.md:162-171
Avatar Tooling
The tools/muse/avatar.py script manages device personalization. It communicates with the Muse VM to fetch a personalized pixel avatar, saves it to components/muse/avatar/muse_pixel.c, and then builds and flashes the device.
Sources: board-port/esp32/AGENTS.md:189-204
Configuration Management
The CLI tools prioritize modularity using SDKCONFIG defaults. When you initiate a build, the helper combines the base sdkconfig.defaults with hardware-specific overlays.
Note: Once build/sdkconfig exists, it overrides subsequent changes to defaults or overlays. To apply changes made to an overlay file, you must delete the build directory or the sdkconfig file within it.
Sources: board-port/esp32/AGENTS.md:237-242, board-port/esp32/tools/board.sh:127-132
Summary
Board Helper CLI Tools simplify firmware development by abstracting the complexities of ESP-IDF for multiple board targets. By automating environment setup, port detection, and configuration merging, these tools allow for rapid iteration and deployment across different hardware profiles in the Muse Gadget ecosystem.