Getting Started & Prerequisites
Relevant source files
The following files were used as context for generating this wiki page:
Muse Gadgets are open-source devices that connect hardware displays, buttons, sensors, and actuators to the Muse platform. This SDK allows developers to build gadgets using off-the-shelf ESP32 boards or Linux-based computers like the Raspberry Pi.
The project is divided into two primary SDKs: the ESP32 Device SDK, which provides firmware for microcontroller-based devices, and the Linux Device SDK, which enables full-featured Linux machines to act as Muse gadgets. Both SDK types pair with the Muse mobile app via Bluetooth Low Energy (BLE) and communicate with Muse VMs through encrypted sessions.
Sources: README.md:20-41, esp32/README.md:18-29, linux/README.md:18-25
Global Prerequisites
Before setting up either SDK, you must obtain a Muse SDK token and the Muse mobile app.
- SDK Token: Required for every gadget to pair. Obtain this from gadgets.muse.ai/settings/sdk-tokens.
- Muse Mobile App: Used to pair devices, configure Wi-Fi, and manage settings. Enable Developer Mode in the app via Settings > Devices.
- Hardware: An ESP32-compatible board or a Linux computer with Bluetooth LE support.
Sources: README.md:43-52, esp32/README.md:31-41, linux/README.md:27-36
ESP32 Device SDK Setup
The ESP32 firmware supports various boards, ranging from simple status-light devices to UI-capable gadgets with AMOLED screens.
1. Development Environment
The firmware requires ESP-IDF v6.0.1. Other versions are not supported.
- macOS: Install
cmake,ninja,dfu-util, andpython3via Homebrew. - Linux: Install standard Espressif prerequisites for your distribution.
- Installation Commands:
git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6 ~/esp/esp-idf-v6/install.sh esp32c5,esp32s3,esp32c6,esp32 . ~/esp/esp-idf-v6/export.sh
Sources: esp32/README.md:73-86
2. Supported ESP32 Boards
| Board Type | Example Hardware | Build Command |
|---|---|---|
| Standard | ESP32-C5 DevKitC-1 | idf.py build |
| UI-Enabled | Waveshare ESP32-S3 AMOLED | tools/muse/board.sh build s3 |
| Status Screen | Seeed SenseCAP Indicator | tools/board.sh sensecap-indicator build |
| E-Paper | reTerminal E1001 | tools/board.sh reterminal-e1001 build |
Sources: esp32/README.md:118-150, esp32/devices/AGENTS.md:73-78
3. Flash and Monitor Process
Connect the board via a data-capable USB cable. Use idf.py for standard builds or the provided helper scripts for specific board overlays.
The diagram shows the standard flashing and monitoring workflow for ESP32 devices.
Sources: esp32/README.md:88-106
Linux Device SDK Setup
The Linux SDK converts a machine into a Muse Home Link capable of running shell commands and managing files.
1. System Requirements
- Hardware: Raspberry Pi (3B+, 4, 5, or Zero 2 W) or any Linux PC with Bluetooth LE.
- Operating Systems:
- Raspberry Pi OS Bullseye or later.
- Debian 11 or later.
- Ubuntu 22.04 or later.
- Arch Linux (Untested but supported by installer).
- Dependencies: Python 3.9+, BlueZ,
python3-dbus, andpython3-gi.
Sources: linux/README.md:27-36, linux/install.sh:81-125
2. Installation Procedure
Run the automated installer to set up the environment, install the musegadget service, and configure BlueZ GATT MTU settings.
- Download and inspect the script:
curl -fsSL [URL] -o install.sh. - Execute installation with the SDK token:
bash install.sh --sdk-token mgst_.... - The installer creates a virtual environment in
/opt/musegadget/venvusing the system interpreter to access D-Bus bindings.
Sources: linux/README.md:38-48, linux/install.sh:172-187
3. Linux Architecture Overview
The diagram illustrates how the Linux service interacts with local hardware, the mobile app for setup, and the Muse cloud for command execution.
Sources: linux/AGENTS.md:26-40, linux/README.md:65-75
UI Simulator
For developers without physical hardware, the UI simulator provides a desktop preview of the Muse interface.
- Platform Support: macOS and Linux.
- Prerequisites: CMake 3.24+, Ninja, GCC/Clang (C11), and SDL2.
- Build Commands:
cmake -S esp32/simulator -B esp32/simulator/build -G Ninja cmake --build esp32/simulator/build - Functionality: Emulates avatar rendering, status transitions, and user input (mouse/keyboard). It does not emulate Bluetooth or actual audio hardware.
Sources: esp32/simulator/README.md:18-60
Setup Validation
After installation, verify the device state using the following commands:
| Platform | Command | Expected Result |
|---|---|---|
| ESP32 | idf.py monitor | Log shows Muse Gadget starting and link.led: LED status ready |
| Linux | sudo musegadget info | Displays Name, Node ID, and Pairing state |
| Linux | sudo systemctl status musegadget | Service status is active (running) |
Sources: esp32/devices/AGENTS.md:248-256, linux/README.md:95-100
The SDKs provide a complete path from environment setup to hardware deployment, ensuring devices can communicate securely with Muse while allowing for local hardware extension through Python (Linux) or C/C++ (ESP32).
Sources: README.md:54-56, esp32/README.md:200-205, linux/README.md:120-125