Supported Hardware & Boards
Relevant source files
The following files were used as context for generating this wiki page:
The Muse Gadget SDK supports a wide variety of ESP32-based hardware, ranging from simple development kits to complex devices with integrated displays and audio capabilities. This firmware connects these boards to home Wi-Fi and establishes an encrypted Noise session with a virtual machine (VM), enabling local device control through the Muse app.
Supported hardware is categorized by its capabilities, specifically the presence of a screen for the Full UI, PSRAM for home-network tunneling, and audio peripherals for push-to-talk functionality.
Sources: [board-port/esp32/README.md:16-24], [board-port/esp32/AGENTS.md:20-24]
Hardware Categories and Capabilities
The firmware adapts its feature set based on the specific hardware profile of the board.
Core Capability Tiers
- Status Light/Ring Boards: Use an RGB LED or LED ring to communicate device states (e.g., ESP32-C5 DevKitC-1).
- Status Screen Boards: Display connection state via colored bars, animations, and text on small LCD or E-paper screens (e.g., ESP32 CYD).
- Full UI Boards: Run a comprehensive on-screen interface including an animated avatar, touch settings, and push-to-talk (e.g., Waveshare ESP32-S3-Touch-AMOLED).
Technical Requirements
- Home-Network Tunnel: Requires boards with PSRAM (e.g., ESP32-S3, ESP32-C5) to handle additional memory requirements.
- Voice/Audio: Requires specific I2S microphones and speakers. Boards like the Home Assistant Voice Preview Edition utilize dedicated audio chips.
Sources: [board-port/esp32/README.md:113-146], [board-port/esp32/AGENTS.md:32-60], [README.md:12-22]
Supported Boards Reference
The following table summarizes the primary supported boards and their build requirements:
| Board | Build Method / Helper | Key Features |
|---|---|---|
| ESP32-C5 DevKitC-1 | idf.py build | Status LED, BOOT button |
| ESP32 CYD | tools/board.sh cyd build | 2.8" ILI9341, Status Screen, Images |
| ESP32-S3-BOX-3 | tools/muse/board.sh build box3 | Full UI, Touch, Audio, Images |
| SenseCAP Watcher | tools/muse/board.sh build watcher | Full UI, PTT, Settings, Camera |
| HA Voice PE | tools/board.sh home-assistant-voice | LED Ring, Volume Dial, PTT |
| M5Stack CoreS3 | tools/muse/board.sh build cores3 | Full UI, Touch, PTT, Images |
| Seeed SenseCAP Indicator | tools/board.sh sensecap-indicator | 4" Screen, Status UI, Images |
Sources: [board-port/esp32/README.md:123-146], [board-port/esp32/AGENTS.md:32-60]
Architecture and Data Flow
The system architecture consists of a core application layer that interfaces with hardware-specific drivers and a Noise-encrypted control session for remote communication.
The diagram shows the interaction between physical hardware components, the central application logic in app.c, and the secure transport layers.
Sources: [board-port/esp32/main/app.c], [board-port/esp32/main/noise_control.cpp], [board-port/esp32/main/led_status.c]
Display and Status Backends
The led_status.c module manages various display backends via Kconfig options.
Backend Drivers
- PWM RGB: Drives common-anode or common-cathode LEDs using LEDC (e.g., Pins 2, 3, 6).
- Addressable Strip: Controls WS2812B LEDs via RMT (e.g., GPIO 27 on DevKitC-1).
- SPI Displays: Supports ST7789 and ILI9341 controllers using
esp_lcdfor status animations and images. - RGB Displays: Supports ST7701 controllers (e.g., SenseCAP Indicator) using a 16-bit RGB bus and PSRAM frame buffers.
Status Indicators
| Light/UI State | Meaning |
|---|---|
| Orange, breathing | BLE advertising, ready for setup |
| Blue, breathing | Pending pairing; requires button press |
| Blue, solid | Joining Wi-Fi / Connecting to VM |
| Green, solid | Connected (Tunnel or Control session active) |
| Yellow, blinking | Reconnecting or VM switching |
| Red, blinking | Error state |
Sources: [board-port/esp32/main/led_status.c:50-135], [board-port/esp32/README.md:92-101], [board-port/esp32/AGENTS.md:144-152]
Board Identification and Flashing
Before flashing, identifying the board is critical to ensure the correct pin map and flash settings are applied.
Identification Logic
- Running Firmware: Use
tools/muse/chat.py --statusto query an existing installation. - USB Descriptors: Check VID/PID (e.g.,
303a:1001for native Espressif USB). - Esptool: Run
esptool chip-idto identify the chip target (e.g.,esp32s3,esp32c6). - Hardware Hints: Observe specific button wake logs (e.g.,
yellowindicates M5Stack StopWatch).
Flashing Procedures
- Standard Boards: Use
idf.py -p PORT flashor thetools/board.shhelper. - SenseCAP Watcher: Requires
tools/muse/paced_esptool.pyto prevent checksum errors on the CH342 USB bridge. - M5Stack StickC Plus2: Must be flashed at a lower baud rate (230400).
Sources: [board-port/esp32/AGENTS.md:96-140], [README.md:63-82]
Technical Wiki Summary
The Muse Gadget SDK supports a tiered hardware model based on the ESP32 family. It provides specific drivers for a variety of displays (SPI, RGB, E-paper) and status indicators (LED strips, PWM RGB). By using board-specific overlays (sdkconfig.<board>), the firmware optimizes its memory usage and peripheral management for different hardware profiles.