Supported Boards & Porting
Relevant source files
The following files were used as context for generating this wiki page:
The Muse Gadget SDK supports a wide range of ESP32-based hardware, from simple development kits with status LEDs to sophisticated devices featuring AMOLED touchscreens and integrated audio. The porting system allows developers to extend the SDK to new boards by defining board-specific hardware abstractions and configurations.
This page describes the architecture of board support, the process for adding new devices, and the specific hardware requirements for various device "kinds" (Light, Status screen, E-paper, and UI).
Sources: esp32/README.md:162-192, esp32/devices/AGENTS.md:15-100
Device Architecture and Types
The SDK categorizes supported hardware into four distinct kinds based on the user interface capabilities provided by the device.
| Kind | Capabilities | Primary Hardware Components |
|---|---|---|
| Light | Basic status indication | Status LED, BOOT button |
| Status Screen | Edge bars and animations | Display (SPI/RGB), Backlight |
| E-paper | Persistent text/images | E-ink display |
| UI | Full LVGL avatar and menus | Display, Touch, Mic, Speaker, PSRAM |
Sources: esp32/devices/AGENTS.md:129-138, esp32/README.md:162-192
Board Abstraction Layer
Devices running the full UI interface interact with the system through the muse_board_t structure. This structure defines the function pointers and metadata required to manage display, audio, power, and input.
Hardware Requirements for Full UI
Devices intended to run the full UI (avatar and settings) must meet specific memory and peripheral requirements:
- Flash: Minimum 8 MB is required. 16 MB boards use
partitions_muse.csv, while 8 MB boards usepartitions_muse_8mb.csv. - PSRAM: Highly recommended. Without PSRAM, devices lose home-network tunnel capabilities and image support, and voice notes transition to text-only replies.
- Audio: Requires a supported I2S codec (e.g., ES8311 for speaker, ES7210 for microphones).
Sources: esp32/devices/AGENTS.md:139-144, esp32/README.md:195-197
Porting Procedure
Adding a new board involves seven primary steps to define the hardware facts and integrate them into the build system.
1. Identify Hardware Facts
You must collect chip details (target, flash, PSRAM mode), USB bridge type, GPIO assignments for buttons, status lights, display controllers, and audio peripherals. Do not guess pins; use vendor schematics or reference firmware.
2. Configure SDK Overlays
Every board requires a specific Kconfig overlay file located in esp32/devices/sdkconfig.muse-<name>. This file sets the IDF_TARGET, flash size, and PSRAM mode.
CONFIG_IDF_TARGET="esp32s3"
CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
CONFIG_SPIRAM_MODE_OCT=y
CONFIG_MUSE_BOARD_WAVESHARE_S3_216=y
Sources: esp32/devices/AGENTS.md:164-187, esp32/devices/waveshare-s3-216.md:28-30
3. Implement Board Logic
For UI-capable boards, create a new source file in esp32/components/muse/boards/board_<id>.c. This file implements the muse_board_t interface.
4. Build and Integration
The board must be registered in several locations:
- Kconfig: Add the board to the
MUSE_BOARDchoice incomponents/muse/Kconfig. - CMake: Append the new board file to the
srcslist incomponents/muse/CMakeLists.txt. - Tools: Add an alias and target mapping in
tools/muse/board.sh.
Sources: esp32/devices/AGENTS.md:193-207, esp32/devices/AGENTS.md:237-243
Power and Battery Management
Power management varies significantly between boards. Devices like the M5Stack Core2 use an AXP192 PMU, while others use AXP2101 or simple GPIO dividers.
| Feature | Implementation Method | Source Reference |
|---|---|---|
| Battery Level | ADC reading with lookup table | board_vn_s3_183.c:266-289 |
| PMU Control | I2C commands to AXP192/AXP2101 | board_m5stack_core2.c:263-268 |
| Power Off | Deep sleep or PMU shutdown | board_aipi.c:168-178 |
Sources: esp32/components/muse/boards/board_vn_s3_183.c:266-289, esp32/components/muse/boards/board_m5stack_core2.c:263-268, esp32/components/muse/boards/board_aipi.c:168-178
Hardware Verification
After porting, you must verify the implementation using the following checklist:
- Build Verification: Ensure all lines in the overlay are applied in the generated
sdkconfig. - Partition Check: Confirm the app fits within the partition table and has at least 10% free space.
- Boot Verification: Monitor the serial output for
link.main: Muse Gadget startingand ensure no reboot loops occur. - Peripheral Test: Verify the status LED breathes orange (ready for setup) and the display renders the UI.
Sources: esp32/devices/AGENTS.md:255-274, esp32/devices/esp32-s3-box-3.md:83-93
The porting system ensures that Muse Gadgets can be deployed on a variety of hardware while maintaining a consistent software interface for the core application logic. This modularity allows for rapid support of new ESP32 modules as they are released by vendors.