Adding New Board Profiles

Relevant source files

The following files were used as context for generating this wiki page:

• board-port/esp32/AGENTS.md
• board-port/esp32/README.md
• board-port/esp32/tools/board.sh
• board-port/esp32/main/CMakeLists.txt
• board-port/esp32/main/app.c
• README.md

New board profiles define the hardware configuration and build environment for ESP32-compatible devices. A profile manages chip targets, pin mappings for buttons and LEDs, display drivers, and memory settings. By creating a profile, you enable the Muse Gadget firmware to operate on diverse hardware while maintaining consistent pairing and connection logic.

Sources: board-port/esp32/README.md:154-159, board-port/esp32/AGENTS.md:160-167

Architecture of a Board Profile

The project uses a layered configuration system. A base sdkconfig.defaults provides standard settings. Each board profile adds a specific overlay file in the devices/ directory, named sdkconfig.<board_name>. These overlays override the defaults to match the specific hardware capabilities of the board.

The diagram shows how configuration files merge during the build process to create a board-specific firmware binary.
Sources: board-port/esp32/AGENTS.md:37-70, board-port/esp32/AGENTS.md:213-219

Core Configuration Requirements

Every new board profile must define a set of mandatory Kconfig options. These options ensure the firmware can interact with the physical interface of the device and allocate resources correctly.

Option	Purpose	Example Value
CONFIG_IDF_TARGET	Defines the specific ESP32 chip family.	esp32s3, esp32c6
CONFIG_HOMEHUB_BUTTON_GPIO	Sets the GPIO pin for the physical setup button.	0, 28
CONFIG_HOMEHUB_LED_BACKEND_*	Selects the status light driver (PWM, RMT, or None).	..._DEVKIT_GPIO27
CONFIG_SPIRAM	Enables or disables external PSRAM support.	y or n
CONFIG_HOMEHUB_TUNNEL	Enables the home-network tunnel (requires PSRAM).	n (if no PSRAM)

Sources: board-port/esp32/AGENTS.md:162-167, board-port/esp32/README.md:161-163

Memory and Tunnel Constraints

Boards without PSRAM, such as standard ESP32 or ESP32-C6 models, cannot support the home-network tunnel. For these boards, you must explicitly set CONFIG_HOMEHUB_TUNNEL=n and CONFIG_SPIRAM=n in the overlay. Additionally, internal-allocation options for mbedtls should be adjusted to fit within limited internal RAM.
Sources: board-port/esp32/README.md:161-163, board-port/esp32/AGENTS.md:164-167

Implementation Procedure

To add a new board profile, you follow these steps:

1. Create the Overlay: Copy an existing overlay from devices/ that most closely matches your hardware and name it devices/sdkconfig.<yourboard>.
2. Define Hardware Pins: Set the GPIO pins for buttons and LEDs. If using a status LED, define the RGB order via CONFIG_HOMEHUB_LED_RGB_ORDER.
3. Configure Flash: Set the flash size and mode (e.g., dio, 80m).
4. Register the Board: Add the board to the supported list in devices/README.md.
5. Update Build Scripts: Add a case for the board in tools/board.sh to define the target, overlays, and USB port patterns.

Sources: board-port/esp32/AGENTS.md:160-167, board-port/esp32/tools/board.sh:45-87

Build Script Integration

The tools/board.sh script automates the build process by creating distinct build directories for each board. You must define the TARGET, DEFAULTS overlay string, and PORTS glob patterns.

  yourboard)
    TARGET=esp32s3
    DEFAULTS="$DEFAULTS;devices/sdkconfig.yourboard"
    PORTS="/dev/cu.usbmodem* /dev/ttyACM*"
    ;;

Sources: board-port/esp32/tools/board.sh:79-83

Conditional Feature Inclusion

The build system uses the CMakeLists.txt file in the main directory to include source files and requirements based on the board configuration.

The diagram illustrates how CMake evaluates configuration flags to append specific source files and component requirements.
Sources: board-port/esp32/main/CMakeLists.txt:59-95

Verification and Testing

After creating a profile, you must verify the implementation through build and boot monitoring.

1. Build: Run tools/board.sh <yourboard> build and ensure the binary size fits within the defined partition slots (typically 2 MB or 4 MB).
2. Flash: Use tools/board.sh <yourboard> flash PORT.
3. Identify: Check the boot log. A correctly configured board with the full UI logs its name via muse: board: <name>.
4. Pairing Test: Ensure the status LED breathes orange, indicating it is ready for BLE pairing.

Sources: board-port/esp32/AGENTS.md:172-200, board-port/esp32/AGENTS.md:275-280

Board profiles are essential for adapting Muse Gadget firmware to varied ESP32 hardware. By correctly defining overlays and integrating with the build scripts, you ensure that hardware-specific features like displays, voice, and status lights function while maintaining the core connectivity and security features of the project.