# Build: M5Stack Core2 (v1.0) as a Muse gadget
Difficulty: Intermediate (extra steps). Back up the 16 MB flash first, flash at 230400 baud, and check it's a v1.0.

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

## Warnings (read before flashing)
- M5Stack Core2: only v1.0 (AXP192) is supported; v1.1 (AXP2101) isn't. Check the back sticker or PCB, and back up the 16 MB flash before the first flash.

## Hardware
- [M5Stack Core2 (v1.0)](https://www.ebay.com/sch/i.html?_nkw=M5Stack%20Core2%20(v1.0)) x1 (required, board): Main board or device for this build.
- [USB-C data cable](https://www.adafruit.com/product/4199) x1 (required, part): Must carry data, not just charge. Most flashing problems are charge-only cables. This Adafruit cable is USB-C on both ends with all data pins connected ($9.95 on 2026-10-05). If your computer has USB-A ports, the Seeed USB-C to USB-A cable works too.
- [USB-C power adapter (5 V / 2 A or more)](https://www.amazon.com/s?k=USB-C%20power%20adapter%205V%202A) x1 (optional, part): Optional. Runs the gadget from a wall outlet instead of your computer. A phone charger that supplies 5 V / 2 A or more works.

## Shopping list (ask before buying)
- M5Stack Core2 (v1.0) x1 (required, price unknown; search: https://www.ebay.com/sch/i.html?_nkw=M5Stack%20Core2%20(v1.0))
- USB-C data cable x1 (required, est. $10; buy: https://www.adafruit.com/product/4199)
- USB-C power adapter (5 V / 2 A or more) x1 (optional, est. $10; search: https://www.amazon.com/s?k=USB-C%20power%20adapter%205V%202A)
- Estimated total: unknown (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-core2/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: Its USB-UART bridge is a CP2104 on early units and a CH9102F on later ones; tools/muse/board.sh flash core2 uses 230400 baud, which both take.
   Keep any esptool command you run by hand at -b 230400.
   Before the first flash, back up the full 16 MB flash: `python -m esptool --chip esp32 -p PORT -b 230400 read-flash 0 0x1000000 core2.bin`. Keep `core2.bin` safe, outside Git.
   To go back, write the backup with the same chip, port and baud: `python -m esptool --chip esp32 -p PORT -b 230400 write-flash 0 core2.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: macOS `ls /dev/cu.usbmodem* /dev/cu.usbserial*`; Linux `ls /dev/ttyACM* /dev/ttyUSB*`; Windows Device Manager shows the COM port for the ESP-IDF shell.
   If flashing cannot connect, hold BOOT, tap RESET, then release BOOT.
   - `git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6`
   - `~/esp/esp-idf-v6/install.sh esp32`
   - `. ~/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 core2`
   - `printf '\nCONFIG_GADGET_SDK_TOKEN="mgst_YOUR_TOKEN"\n' >> build-muse-m5stack-core2/sdkconfig`
   - `tools/muse/board.sh build core2`
   - `ls /dev/cu.usbmodem* /dev/cu.usbserial* 2>/dev/null || ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null`
   - `python -m esptool --chip esp32 -p PORT -b 230400 read-flash 0 0x1000000 core2.bin`
   - `tools/muse/board.sh flash core2 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 the middle touch zone 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 the middle touch zone) What's on my calendar tomorrow?
   - Show me the image you just found.

## Assemble
1. Connect the board to the computer with the USB-C data cable. Check: Board powers on and a new serial port appears. Verify: run `ls /dev/cu.usbmodem* /dev/cu.usbserial* 2>/dev/null || ls /dev/ttyACM* /dev/ttyUSB* 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 full 16 MB flash: `python -m esptool --chip esp32 -p PORT -b 230400 read-flash 0 0x1000000 core2.bin`. Check: core2.bin exists and is 16777216 bytes. Verify: run `wc -c < core2.bin`, expect "16777216". 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 core2 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 the middle touch zone 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 the middle touch zone and ask a question such as "What's on my calendar tomorrow". The reply shows as text on the screen
- Try: (Hold the middle touch zone) What's on my calendar tomorrow?
- Try: Show me the image you just found.

## 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/Core2
- Board docs or firmware: https://github.com/m5stack/M5Unified
- Build page: https://www.hackshop.dev/build/m5stack-core2-v1-0
- Save it: tell the human to click Start a build on the build page so their progress is saved.