skill

cardputer-adv-skill

Agent skill: build, flash and debug M5Stack Cardputer-Adv (ESP32-S3FN8) firmware with PlatformIO + Arduino + M5Unified. Hardware-verified, with a complete MIDI keyboard example and the traps that cost

liukjx/cardputer-adv-skillcommunitylistedunreviewed

Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/liukjx/cardputer-adv-skill itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 23, 2026

Cardputer-Adv Agent Skill 🎹

An AgentSkill that lets a coding agent build, flash and debug firmware for the M5Stack Cardputer-Adv (SKU K132-Adv, Stamp-S3A / ESP32-S3FN8) without rediscovering the same traps.

It was distilled from one full hardware session: scaffolding a PlatformIO + Arduino + M5Unified project, chasing a black screen through a misdiagnosed "boot loop", fixing the audio, and shipping a verified MIDI keyboard app. Every claim in here was measured on real hardware — nothing is copied from a blog post.

The four traps this skill exists to prevent

#	Trap	What it costs you
1	`flash_mode = qio` (the stock devkitc default) never boots on this board	Endless reboot + black screen; the ROM reports `boot:0x3 (DOWNLOAD(USB/UART0))`. `dio` fixes it instantly.
2	`Serial.begin()` blocks when no host drains the USB-CDC	`setup()` hangs before any M5 init; looks like a library bug that isn't.
3	Opening the serial port resets the chip (DTR/RTS = reset on USB-Serial/JTAG)	A perfect fake crash loop that wasted hours of the original session.
4	PlatformIO's esptool 4.5.1 cannot sync with this board	`No serial data received`, while esptool 5.x works fine on the same port.

Plus the one that is not a bug but feels like one: the default tone waveform is a 16-point sine, which the 1 W speaker cannot radiate below ~300 Hz — so the low octave is silent until you switch to a sawtooth.

What is inside

SKILL.md                        the workflow + the non-negotiable rules
references/
  hardware.md                   full pin map, specs, Cardputer vs Cardputer-Adv
  toolchain.md                  PlatformIO recipe, library pins, flash/boot procedures
  debugging.md                  symptom -> cause table, LED-first method, the "Saved PC" red herring
  m5-library-notes.md           M5Unified / M5Cardputer / M5GFX API notes and gotchas
  official-docs.md              verified M5Stack doc URLs, how to read the SPA-hosted docs,
                                the official procedures verbatim, and where M5Stack's own
                                published recipe differs from one that boots
scripts/
  flash.sh                      flash a PlatformIO build with esptool 5.x (correct offsets)
  softboot.py                   restart the app over DTR/RTS instead of replugging USB
  serial_capture.py             capture the console without resetting the board
examples/
  midi-keyboard/main.cpp        a complete, hardware-verified app (8-voice synth + UI)
  bring-up/diag.cpp             staged init reported through the RGB LED
  bring-up/selftest.cpp         library-free bring-up (chip info + I2C scan)
  platformio.ini                three ready-to-build environments

Install

As a Claude Code / Codex skill — clone into the skills directory:

git clone https://github.com/liukjx/cardputer-adv-skill.git ~/.claude/skills/cardputer-adv

The agent then picks it up automatically whenever a task mentions the Cardputer-Adv, a Cardputer boot loop, its display / keyboard / audio, or ESP32-S3 native-USB flashing.

As plain documentation — read SKILL.md first; it links to the rest.

Quick start for a new project

python3 -m venv venv && ./venv/bin/pip install -U platformio   # PlatformIO
python3 -m venv ~/esptool-venv && ~/esptool-venv/bin/pip install esptool pyserial
# copy examples/platformio.ini + examples/midi-keyboard/main.cpp, then:
./venv/bin/pio run -e midi-keyboard
bash scripts/flash.sh /dev/cu.usbmodem2301 midi-keyboard
python3 scripts/softboot.py /dev/cu.usbmodem2301               # or replug USB

Verified environment

macOS 15 (Apple Silicon) · PlatformIO Core 6.2.0 · espressif32@6.7.0 (Arduino core 2.0.16) · esptool 5.4.0 · M5Unified / M5GFX / M5Cardputer pinned to tested commits.

The rules are hardware properties, so they carry over to Linux and Windows; only the serial port naming differs (/dev/cu.usbmodem* vs COM*).

Contributing

Found another trap, a wrong pin, or support for the original Cardputer that belongs here? Issues and PRs are welcome — please include the observed symptom and the command that proved it, since that is what makes this document useful.

License

MIT — see LICENSE.