# 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.
- [USB power adapter (5 V / 2 A or more)](https://www.amazon.com/s?k=USB%20power%20adapter%205V%202A) x1 (optional, part): 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.

## Shopping list (ask before buying)
- M5Stack Cardputer ADV x1 (required, est. $30; buy: https://shop.m5stack.com/products/m5stack-cardputer-adv-version-esp32-s3)
- USB data cable x1 (required, est. $10; search: https://www.amazon.com/s?k=USB%20data%20cable)
- USB power adapter (5 V / 2 A or more) x1 (optional, est. $10; search: https://www.amazon.com/s?k=USB%20power%20adapter%205V%202A)
- Estimated total: $40 (estimates checked 2026-10-05)
- Purchase policy: hackshop never buys anything. Your agent can help you buy the parts: it shows you the exact items, sellers and total, then asks "Place this order for $<total> at <seller>?" and waits for a clear yes before it checks out. If it can't check out on a site, or the site doesn't allow automated checkout (Amazon and eBay don't), it gives you the link to buy yourself.

## Constraints
- Never buy anything without a clear yes to "Place this order for $<total> at <seller>?"
- Use `mgst_YOUR_TOKEN` as the placeholder; never commit a real token.
- ESP-IDF v6.0.1 only for ESP32 builds; do not substitute another ESP-IDF version.
- Find the serial port before flashing; only ask the human if the port check is empty or ambiguous.
- 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. (https://gadgets.muse.ai/sdk-terms)

## Steps
1. Get the parts
You need the board and any build-specific accessories before flashing or pairing.
2. 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.
3. Flash the firmware
The board needs the Muse ESP32 firmware configured with your SDK token.
   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`.
   Run the board build once to create the build sdkconfig, set `CONFIG_GADGET_SDK_TOKEN="mgst_YOUR_TOKEN"`, then run the board build again. `idf.py menuconfig` is the interactive alternative.
   Find the serial port: `ls /dev/cu.usbmodem* 2>/dev/null || ls /dev/ttyACM* 2>/dev/null`; Windows Device Manager shows the COM port for the ESP-IDF shell.
   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`
4. 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.
5. 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.
6. 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?

## Assemble
1. Connect the board to the computer with the USB data cable. Check: Board powers on and a new serial port appears. Verify: run `ls /dev/cu.usbmodem* 2>/dev/null || ls /dev/ttyACM* 2>/dev/null`, expect "A new serial port is listed after the board is plugged in."; visual: The screen or status light turns on. Robot feasible: yes (USB-C insertion is feasible with a known connector pose.)
2. 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`. Check: cardputer-adv-backup.bin exists and is 8388608 bytes. Verify: run `wc -c < cardputer-adv-backup.bin`, expect "8388608". Robot feasible: no (Requires a computer, the right serial port and software commands.)
3. Build and flash the Muse firmware with `tools/muse/board.sh flash cardputer-adv PORT`. Check: Flash completes and the serial monitor shows startup logs. Verify: run `tools/muse/monitor.py PORT 20`, expect "link.main: Muse Gadget starting"; status light: The screen or edge status breathes orange (ready for setup). Robot feasible: no (Requires a computer, serial-port selection and software commands.)
4. In the Muse app, turn on Developer mode, add MuseGadget-XXXXXX and press Enter when the screen or edge status breathes blue. Check: Status turns green and the app shows connected. Verify: status light: The screen or edge status is green; muse app: MuseGadget-XXXXXX shows as connected under Settings > Devices. Robot feasible: no (Pairing requires the human's Muse app and account.)
5. Run the checks under Verify. Robot feasible: no (Requires the Muse app and a real prompt.)

## Verify
- run `tools/muse/monitor.py PORT 20`, expect "link.main: Muse Gadget starting"
- status light: The screen or edge status is green
- muse app: MuseGadget-XXXXXX shows as connected under Settings > Devices
- muse app: Hold Space/GO and ask a question such as "Summarize my unread email". The reply shows as text on the screen
- Try: (Hold Space/GO) Summarize my unread email.
- Try: What's the status of the task you're running?

## References
- SDK repo: https://github.com/facebookincubator/muse-gadget-sdk
- AGENTS.md (read this first): https://github.com/facebookincubator/muse-gadget-sdk/blob/main/esp32/AGENTS.md
- Platform docs: https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32
- Board flashing notes: https://github.com/facebookincubator/muse-gadget-sdk/blob/main/esp32/devices/README.md
- Board docs or firmware: https://github.com/facebookincubator/muse-gadget-sdk/blob/main/esp32/devices/README.md
- Board docs or firmware: https://docs.m5stack.com/en/core/Cardputer-Adv
- Build page: https://www.hackshop.dev/build/m5stack-cardputer-adv
- Save it: tell the human to click Start a build on the build page so their progress is saved.