Build: M5Stack Cardputer ADV

About 30-45 minutes · needs a Mac or PC and a USB-C data cable · some Terminal, or let your agent do it

Let your agent do itRecommended Or follow the steps yourself

Intermediate · extra stepsBack up the 8 MB firmware first, and enter download mode by holding GO while you plug in USB.

A working Muse Gadgets: ESP32 Device SDK (Full UI) build on M5Stack Cardputer ADV, paired to your Muse account and ready for first prompts.

Screen and voiceBoard $30 · about $40 with cable/parts

Download build.md

Get the parts

You need the board and any build-specific accessories before flashing or pairing.

1 × M5Stack Cardputer ADV

Requiredboard

Main board or device for this build.

Buy from shop.m5stack.com

1 × USB data cable

Requiredpart

Must carry data, not just charge. Most flashing problems are charge-only cables. Check which USB port your board has, then pick the matching cable.

Find on amazon.com

1 × USB power adapter (5 V / 2 A or more)

Optionalpart

Optional. Runs the gadget from a wall outlet instead of your computer, with the same data cable. A phone charger that supplies 5 V / 2 A or more works.

Find on amazon.com

Hackshop never buys for you. Links open the store.

Get your Muse SDK token

Muse gadgets pair with your account by using a private SDK token.

Create a token at gadgets.muse.ai > Account > SDK tokens (https://gadgets.muse.ai/settings/sdk-tokens). It starts with mgst_. For this ESP32 build, set CONFIG_GADGET_SDK_TOKEN="mgst_YOUR_TOKEN" in build-muse-m5stack-cardputer-adv/sdkconfig after the board build command has created that file, then run the build command again. idf.py menuconfig > ESP32 Device SDK > Muse Gadgets SDK token is the interactive alternative. Never commit the real token or paste it anywhere public.

Muse SDK tokens Muse Gadgets: ESP32 Device SDK terms

Flash the firmware

The board needs the Muse ESP32 firmware configured with your SDK token.

Read this first: flashing this board

Port: Native USB: it shows up as /dev/cu.usbmodem* on macOS or /dev/ttyACM* on Linux. On Linux, add yourself to the dialout (or uucp) group.
To enter download mode: switch it off, hold GO while you connect USB, then release GO.
Before the first flash, back up the original 8 MB firmware: python -m esptool --chip esp32s3 -p PORT read-flash 0 0x800000 cardputer-adv-backup.bin. Keep cardputer-adv-backup.bin safe, outside Git.
To go back, write the backup: python -m esptool --chip esp32s3 -p PORT write-flash 0 cardputer-adv-backup.bin.

Source: https://github.com/facebookincubator/muse-gadget-sdk/blob/main/esp32/devices/README.md

Let your agent do it

Give your coding agent the build brief at https://www.hackshop.dev/build/m5stack-cardputer-adv/build.md. Tell it to keep the token private, use mgst_YOUR_TOKEN as the placeholder, and find the serial port before flashing. It should find the port with ls /dev/cu.usbmodem* 2>/dev/null || ls /dev/ttyACM* 2>/dev/null; on Windows, use Device Manager to find the COM port, then run commands in the ESP-IDF shell. Before the first flash, it must back up the original 8 MB firmware.

Do it yourself

Install ESP-IDF v6.0.1 and only the esp32s3 target for this board. Muse's ESP32 README verifies macOS and Linux. Windows is not documented by the Muse SDK; if you use it, install ESP-IDF v6.0.1 with Espressif's Windows installer and run commands in the ESP-IDF shell. Clone the Muse Gadget SDK, run tools/muse/board.sh build cardputer-adv once to create build-muse-m5stack-cardputer-adv/sdkconfig, set CONFIG_GADGET_SDK_TOKEN="mgst_YOUR_TOKEN" in that file, run tools/muse/board.sh build cardputer-adv again, then flash. If esptool can't connect, switch it off, hold GO while you connect USB, then release GO.

git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6
~/esp/esp-idf-v6/install.sh esp32s3
. ~/esp/esp-idf-v6/export.sh
git clone https://github.com/facebookincubator/muse-gadget-sdk
cd muse-gadget-sdk/esp32
tools/muse/board.sh build cardputer-adv
printf '\nCONFIG_GADGET_SDK_TOKEN="mgst_YOUR_TOKEN"\n' >> build-muse-m5stack-cardputer-adv/sdkconfig
tools/muse/board.sh build cardputer-adv
ls /dev/cu.usbmodem* 2>/dev/null || ls /dev/ttyACM* 2>/dev/null
python -m esptool --chip esp32s3 -p PORT read-flash 0 0x800000 cardputer-adv-backup.bin
tools/muse/board.sh flash cardputer-adv PORT

Muse Gadget SDK ESP32 SDK docs Board flashing notes

Pair it with the Muse app

Pairing links the freshly flashed board to your Muse account.

In the Muse app, turn on Settings > Devices > Developer mode, then Settings > Devices > Add Device (+). Pick MuseGadget-XXXXXX and press Enter when the screen or edge status breathes blue. Green means connected. Status meanings: orange = ready for setup, blue breathing = press the button, blue = joining Wi-Fi and connecting, green = connected, yellow blinking = reconnecting, purple = unpaired, red blinking = error. Hold the button for 5 seconds to reset pairing.

Muse Gadgets Community help

Put it together

A physical agent body needs to sit safely, keep the cable clear and leave controls reachable.

Put the board in its stand, case or a stable spot on the desk. Route the cable through the slot or open edge, power it, and check that the buttons and display are reachable.

Try it

A first prompt proves the device is paired, reachable, and useful for the project.

“(Hold Space/GO) Summarize my unread email.”“What's the status of the task you're running?”

Hand it to your agent

# Build: M5Stack Cardputer ADV as a Muse gadget
Difficulty: Intermediate (extra steps). Back up the 8 MB firmware first, and enter download mode by holding GO while you plug in USB.

## Goal
A working Muse Gadgets: ESP32 Device SDK (Full UI) build on M5Stack Cardputer ADV, paired to your Muse account and ready for first prompts.

## Warnings (read before flashing)
- M5Stack Cardputer ADV (experimental): back up the original 8 MB firmware before the first flash.

## Hardware
- [M5Stack Cardputer ADV](https://shop.m5stack.com/products/m5stack-cardputer-adv-version-esp32-s3) x1 (required, board): Main board or device for this build.
- [USB data cable](https://www.amazon.com/s?k=USB%20data%20cable) x1 (required, part): Must carry data, not just charge. Most flashing problems are charge-only cables. Check which USB port your board has, then pick the matching cable.

Download build.md

Caveats + terms

Personal, non-commercial use with your own Muse account. A token can be linked to at most 50 devices. You may not put it in any device you sell, advertise, or list publicly or in a marketplace or app store; other distribution needs Meta's written permission. Provided as-is; Meta can change, withdraw or revoke access at any time. Read terms.

Boards without PSRAM (classic ESP32, ESP32-C6) run without the home-network tunnel; Muse can still reach and control them.
Pairing has no manufacturer verification and can't prevent an active man-in-the-middle attack.
Builds are signed with the included development key and never enable Secure Boot. Enable NVS encryption (CONFIG_HOMEHUB_NVS_ENCRYPTION).
Custom ESP32 commands are not a documented API yet: the command set (display.draw_url, sensors.read, camera.capture, ...) is hardcoded in main/app.c.
Experimental in the Muse SDK. Hold Space/GO to send a voice note; replies scroll past as text. No images, home-network tunnel or battery telemetry.