Muse gadgets split into two SDKs, and pairing always needs a token

Two SDKs, two very different targets

The repository splits into an esp32/ directory and a linux/ directory, and the split is not cosmetic. The ESP32 Device SDK connects a microcontroller board to Muse, and the README describes adding a screen to show images, adding audio in and out, and wiring up other sensors. The Linux Device SDK turns a spare Raspberry Pi or Linux box into a gadget, where the interesting capability is hacking in your own commands so Muse handles sysadmin chores or drives a Home Assistant setup.

The two targets share a concept, pairing, and diverge in everything else. An ESP32 has no operating system to speak of, so the SDK has to carry the protocol, the display handling and the audio path itself. A Raspberry Pi has Linux, a filesystem and a package manager, so that side is about integration with what is already there.

The README frames the whole effort candidly, describing the SDKs as built by hackers for hackers, just for fun, and listing the possible consequences as bricked boards, voided warranties, brownouts, or bankruptcies. That framing is worth taking at face value when you plan to flash firmware.

Two more top-level directories round out the picture: web-flasher/ for getting firmware onto a board from a browser, and skills/, which sits alongside the per-directory AGENTS.md files as a machine-readable instruction set.

Pairing is gated on developer mode and a per-gadget token

Nothing works without Meta's side of the deal, and this is the part that decides whether the SDK is usable for you.

Before flashing or pairing, you get an SDK token from the SDK tokens page at gadgets.muse.ai and review the Gadget SDK Terms at gadgets.muse.ai/sdk-terms. Every gadget needs a token to pair, per the README.

The pairing flow itself runs through the Muse mobile app on iOS or Android. Open Settings, then Devices, turn on Developer mode there first, and then look for devices prefixed with MuseGadget. The prefix is how you distinguish your hardware from the commercial device and any other gadget already paired.

So the sequence is: obtain a token, flash or install the SDK on your hardware, enable developer mode in the app, then pair when the MuseGadget-prefixed device appears. There is no offline pairing path described, and the token is not optional, which makes this a different proposition from building a display for a Raspberry Pi that boots on its own.

The homepage is gadgets.muse.ai, and every subdirectory carries a README.md to get started plus an AGENTS.md aimed at coding agents, with Muse Code linked as one such agent.

The diagnostic core is board-neutral on purpose

The most interesting engineering in the repository is the battery power profiling setup, and its design decision is worth understanding before you wire anything up.

A porting recipe at esp32/docs/power/README.md covers battery-input power profiling. The README describes an opt-in diagnostic core that is board-neutral, where boards supply its hooks and state matrices, and a tool, esp32/tools/power/power_sweep.py, that drives a USB-free sweep.

Board-neutral means the profiling logic is written once and each board definition supplies the callbacks and the state transition tables that describe what that hardware can be doing. For a kit of hobby boards with different power domains and different sleep modes, that separation is what makes a single tool usable across all of them rather than a script that works on the reference board only.

The sweep is USB-free, which matters for a battery profile: if you are measuring what the board draws from a battery, powering it from USB would measure the wrong thing entirely.

Two safety points are stated rather than assumed. The isolated diagnostic does not pair and does not need an SDK token, so you can profile hardware before Meta's servers are involved at all. And fixture safety plus explicit hardware authorization still come first, as the PPK2 rules at esp32/docs/power/ppk2.md describe. That file is a gate, not a suggestion, and the ordering it implies is: read it, confirm the rig is safe, then sweep.

A simulator exists so you can build without hardware

The repository contains a simulator under esp32/simulator/, which changes the cost of getting started more than any documentation would.

Building firmware for a display board normally means owning the board. A simulator means you can iterate on the rendering and protocol side against a desktop host first, and only reach for hardware once the logic is settled. The third-party notices for the simulator list its dependencies as LVGL and SDL, and those are recorded in esp32/simulator/THIRD_PARTY.md.

That dependency choice also tells you something about the UI layer. The simulator lists LVGL and SDL among its dependencies.

The README notes the web-flasher/ directory, which is the counterpart for deployment: once the code works, firmware goes onto the board from a browser rather than through a command line toolchain.

The README does not document build commands for either the firmware or the simulator, so the per-directory README.md files under esp32/ and linux/ are where a first build is actually described.

Third-party files inside an Apache-2.0 repository

The licence section is unusually explicit and worth reading before you reuse any of this.

Muse Gadgets is Apache-2.0 with LICENSE at the root, except for named third-party files that keep their upstream licences. There are three listed. The minimp3 audio decoder header at esp32/components/minimp3/include/minimp3.h comes from lieff/minimp3 and is CC0-1.0, with its own LICENSE in that component directory. The panel init header at esp32/components/muse/boards/ostb_echoear_display_init.h derives from the ESP-VoCat panel sequence in the xiaozhi-esp32 project and stays MIT, with the notice retained in the file header. The pixel font at esp32/main/pixel_font.c is Adafruit GFX glcdfont.c under BSD-2-Clause, again noted in the file header.

Dependencies fetched at build time sit outside the repository and under their own licences: ESP-IDF components land in esp32/managed_components/, and the simulator's LVGL and SDL are listed in its third-party file.

The one carve-out that is not a licence but a rights question: the Apache License does not cover the Jollybot avatar in esp32/avatar. So if your gadget renders that avatar, you are outside the terms of this repository for that asset.

Apache-2.0 otherwise means no copyleft obligation on your gadget firmware, and a patent grant, which is a real consideration for a commercial hardware product.

Where this sits against building a display the ordinary way

The comparison is worth making because Muse hardware is not the only way to get a dashboard onto a screen.

What it lacks is any path to the Muse display itself. If the point is to put information on Muse, there is no open alternative in this repository and the token requirement is the boundary, not a technicality.

Building against Muse's existing app APIs is the other route, and the README does not describe one. What it describes is device-side SDKs for hardware you build, which is a different relationship: the gadget is a peripheral that Muse drives, not an integration that runs inside Muse.

For the ESP32 side specifically, the nearest comparison is writing your own display firmware from scratch against ESP-IDF. The SDK supplies the Muse protocol, board definitions and diagnostics; doing it yourself means maintaining that yourself across board revisions.

The honest summary is that this is an SDK for a specific device ecosystem with a vendor-controlled pairing gate, not a general-purpose display toolkit. If Muse is not the screen you want on the wall, none of the value transfers.

Editorial conclusion

The SDK fits a maker with an ESP32 board or a spare Linux machine who wants Muse to render a custom dashboard, play audio, or run their own commands on a display they own. It does not fit anyone who wants a consumer gadget without assembly, because pairing requires a developer mode toggle in the Muse app and a token from gadgets.muse.ai, and there is no documented path for a gadget that must pair without that. Before flashing, read esp32/docs/power/README.md and esp32/docs/power/ppk2.md, because the power measurement setup is where hardware gets damaged, and check the third-party licence table for the board files you are about to use.

Frequently asked questions

Official sources

1. facebookincubator/muse-gadget-sdk on GitHub
2. Issues
3. License: Apache-2.0
4. README