{"id":"ae24569b-541c-4485-a74a-d82c5acde054","slug":"cardputer-adv-skill","kind":"skill","name":"cardputer-adv-skill","summary":"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","owner":"liukjx","repoUrl":"https://github.com/liukjx/cardputer-adv-skill","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-09-13T10:52:02.000Z","addedAt":"2026-10-21T13:00:01.159Z","logoUrl":"https://avatars.githubusercontent.com/u/33191606?u=6d96d657697ae1d42e41de5505aa7ed1106493a3&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["arduino","cardputer","esp32-s3","esptool","m5stack","m5unified","platformio"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T06:00:05.218Z","sample":false,"url":"https://conduits.dev/tools/cardputer-adv-skill","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Cardputer-Adv Agent Skill 🎹\n\nAn [AgentSkill](https://docs.claude.com/en/docs/claude-code/skills) that lets a coding agent\n**build, flash and debug firmware for the M5Stack Cardputer-Adv** (SKU K132-Adv,\nStamp-S3A / ESP32-S3FN8) without rediscovering the same traps.\n\nIt was distilled from one full hardware session: scaffolding a PlatformIO + Arduino +\nM5Unified project, chasing a black screen through a misdiagnosed \"boot loop\", fixing the\naudio, and shipping a verified MIDI keyboard app. Every claim in here was measured on real\nhardware — nothing is copied from a blog post.\n\n## The four traps this skill exists to prevent\n\n| # | Trap | What it costs you |\n|---|---|---|\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n\nPlus the one that is not a bug but feels like one: the default tone waveform is a 16-point\n**sine**, which the 1 W speaker cannot radiate below ~300 Hz — so the low octave is silent\nuntil you switch to a sawtooth.\n\n## What is inside\n\n```\nSKILL.md                        the workflow + the non-negotiable rules\nreferences/\n  hardware.md                   full pin map, specs, Cardputer vs Cardputer-Adv\n  toolchain.md                  PlatformIO recipe, library pins, flash/boot procedures\n  debugging.md                  symptom -> cause table, LED-first method, the \"Saved PC\" red herring\n  m5-library-notes.md           M5Unified / M5Cardputer / M5GFX API notes and gotchas\n  official-docs.md              verified M5Stack doc URLs, how to read the SPA-hosted docs,\n                                the official procedures verbatim, and where M5Stack's own\n                                published recipe differs from one that boots\nscripts/\n  flash.sh                      flash a PlatformIO build with esptool 5.x (correct offsets)\n  softboot.py                   restart the app over DTR/RTS instead of replugging USB\n  serial_capture.py             capture the console without resetting the board\nexamples/\n  midi-keyboard/main.cpp        a complete, hardware-verified app (8-voice synth + UI)\n  bring-up/diag.cpp             staged init reported through the RGB LED\n  bring-up/selftest.cpp         library-free bring-up (chip info + I2C scan)\n  platformio.ini                three ready-to-build environments\n```\n\n## Install\n\n**As a Claude Code / Codex skill** — clone into the skills directory:\n\n```bash\ngit clone https://github.com/liukjx/cardputer-adv-skill.git ~/.claude/skills/cardputer-adv\n```\n\nThe agent then picks it up automatically whenever a task mentions the Cardputer-Adv, a\nCardputer boot loop, its display / keyboard / audio, or ESP32-S3 native-USB flashing.\n\n**As plain documentation** — read `SKILL.md` first; it links to the rest.\n\n## Quick start for a new project\n\n```bash\npython3 -m venv venv && ./venv/bin/pip install -U platformio   # PlatformIO\npython3 -m venv ~/esptool-venv && ~/esptool-venv/bin/pip install esptool pyserial\n# copy examples/platformio.ini + examples/midi-keyboard/main.cpp, then:\n./venv/bin/pio run -e midi-keyboard\nbash scripts/flash.sh /dev/cu.usbmodem2301 midi-keyboard\npython3 scripts/softboot.py /dev/cu.usbmodem2301               # or replug USB\n```\n\n## Verified environment\n\nmacOS 15 (Apple Silicon) · PlatformIO Core 6.2.0 · `espressif32@6.7.0` (Arduino core 2.0.16)\n· esptool 5.4.0 · M5Unified / M5GFX / M5Cardputer pinned to tested commits.\n\nThe rules are hardware properties, so they carry over to Linux and Windows; only the serial\nport naming differs (`/dev/cu.usbmodem*` vs `COM*`).\n\n## Contributing\n\nFound another trap, a wrong pin, or support for the original Cardputer that belongs here?\nIssues and PRs are welcome — please include the observed symptom and the command that\nproved it, since that is what makes this document useful.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n"}