Take a breath. Then check the cable.
The most common issues have a short diagnostic path. Start with power, the cable and the serial log before rewriting flash.
Common issues
No serial port appears
Try another USB‑C data cable. On macOS, look for /dev/cu.usbmodem*; on Linux, /dev/ttyACM0 or /dev/ttyUSB0; on Windows, a COM.
sudo usermod -aG dialout $USERFlashing does not enter download mode
- Disconnect the USB cable.
- Hold RESET/POWER on the bottom.
- Connect USB, wait two seconds and release.
- Run
./flash.sh.
The screen stays black on first boot
Check that you wrote all five images, especially sagwa_clips.bin at 0x830000. Without that package, the firmware falls back to the previous pose mode.
python3 -m serial.tools.miniterm <PORT> 115200A healthy boot shows Muse Gadget starting and initializes the LTR‑553 and BMI270.
The microSD card is missing or does not update
Format the card as FAT32; exFAT and NTFS are not supported by this ESP‑IDF flow. In Settings → Sagwa you can see free space or the “Not FAT32” warning.
An update fails to finish booting
The image must confirm that it can reach GitHub or the Muse control connection again. If it cannot within five minutes, the bootloader restores the previous slot. Check Wi‑Fi, the configured repository and the signing key before retrying.
Return to a known release
python3 flash.py --release v1.0.9
# If you only want to restore the application
python3 flash.py --release v1.0.9 --app-only