M5Stack Onboarding
Detect, flash, and provision M5Stack ESP32 boards with UIFlow firmware and MicroPython apps.
The document describes device detection, flashing, manual button confirmation, log monitoring, cache permissions, and recovery paths, while disclosing WiFi, BLE, USB, and external-download data flows. However, the default flow flashes the device and installs external dependencies, may bootstrap Python through system package managers, and lacks sufficiently explicit least-privilege, credential-handling, and pre-flash confirmation controls, so points are deducted.
The documentation gives concrete cross-platform guidance for ports, baud rates, retries, flashing failures, and manual resets. However, the executable scripts, test suite, and key-path reproduction evidence are not included, and the statements about backing up boot.py are inconsistent, so the static score remains limited.
The audience, device variants, some non-fit cases, manual-button conditions, and operating-system differences are fairly clear. Still, the default model relies on an operational assumption, Chinese-language support is unspecified, and core operation depends on external GitHub, M5Burner, pip, and Claude Desktop services without documented mainland-China reachability or substitutes, so points are deducted.
The documentation is well organized and covers triggers, decision flow, stages, platform notes, dependencies, and recovery. Repository-level Apache-2.0 licensing and official provenance are available, but the skill lacks its own version, changelog, explicit maintenance owner, fully pinned installation dependencies, and systematic troubleshooting FAQ, so it is not full marks.
The stated goal is concrete: detect an M5Stack device, flash firmware, and install applications. Commands, stages, and expected device behavior are described and could directly support the core task. However, neither the scripts nor resulting device output are verified in the supplied material, and external bundle and network dependencies add failure and manual-rework costs, so the score stays within the static ceiling.
The skill supplies commands, paths, log markers, hardware signatures, and specific failure modes, providing some auditability. It does not provide committed tests, CI coverage for this skill, third-party execution records, or independent reproduction evidence; the repository CI shown does not establish this skill’s key-path correctness, so only limited points are justified.
- The default flow flashes firmware and installs files; users should explicitly confirm the target port, model, and acceptable device-state changes before execution.
- The app bundle comes from an external local clone, while firmware and esptool use external services or pip; source, versions, hashes, and network reachability should be verified.
- The document states that event WiFi credentials are embedded in the app bundle; inspect and remove or replace hard-coded configuration before use.
- The boot.py backup statement conflicts with later behavior, so complete rollback should not be assumed from the documentation alone.
What it does & when to use it
m5-onboard is for freshly connected, previously provisioned, or reset M5Stack ESP32 devices, including Cardputer, Cardputer-Adv, Core, CoreS3, and Stick variants. It detects the USB port, identifies the hardware, downloads and flashes UIFlow 2.0 firmware, and uploads a MicroPython application bundle such as Claude Buddy. It supports macOS, Linux, and Windows, with Cardputer-Adv as the default target. Native-USB ESP32-S3 boards still require a manual G0/RST button sequence during flashing.
The onboard.py orchestrator discovers serial ports, probes the chip, determines a likely hardware variant, downloads firmware through the M5Burner manifest API, flashes it with esptool, and uploads Python files from buddy/device to /flash/ through a paste-mode REPL. When the bundle contains a root main.py, install_apps.py also sets UIFlow boot_option=2. install_apps.py can refresh applications without reflashing, while smoke_test.py checks I2C, LCD, speaker, and buttons.
- A user has connected a Cardputer-Adv and wants firmware plus the Claude Buddy bundle installed end to end.
- A user already has UIFlow installed and wants to refresh the MicroPython applications only.
- A user suspects a hardware or boot problem and wants to run I2C, display, speaker, and button checks.
- A user is provisioning a Core, CoreS3, Basic, Fire, or another supported board and needs an explicit firmware variant.
- A user wants to repeat the same provisioning workflow on macOS, Linux, or Windows.
Pros & cons
- Covers detection, identification, flashing, and application installation in one cold-start workflow.
- Supports multiple M5Stack and ESP32 variants, including Cardputer-Adv, Cardputer, Core, CoreS3, and Stick.
- Runs on macOS, Linux, and Windows.
- Vendors pyserial and can prompt for esptool installation on first use.
- Accounts for native-USB bootloader entry, NVS boot settings, REPL paste mode, and common flashing recovery cases.
- Requires physical M5Stack/ESP32 hardware and USB serial access.
- Native-USB ESP32-S3 flashing cannot be fully automated and requires manual buttons.
- Requires network access for firmware downloads and may install esptool.
- The executable scripts and buddy bundle live in the build-with-claude clone's onboard/ directory rather than alongside the provided SKILL.md.
- The supplied source gives no evidence of a standalone test suite or a complete per-platform validation matrix.
How to install
This skill is part of the cwc-makers plugin in anthropics/claude-plugins-official. The README says plugins can be installed in Claude Code through the plugin system; using its documented format, run /plugin install cwc-makers@claude-plugins-official. Then use /maker-setup to create the local build-with-claude clone, because the executable scripts and buddy application bundle are located in that clone's onboard/ directory. Python must exist before the workflow can run; the first run can prompt to install esptool if it is missing.
How to use
After connecting the M5Stack over USB, run python3 scripts/onboard.py --apps buddy from the clone's onboard/ directory. When a native-USB board prompts for download mode, hold G0 on the back of the device, briefly press and release RST, keep holding G0 for about one more second, then release it; the screen should be fully dark before continuing. To install apps without reflashing, run python3 scripts/install_apps.py --port <PORT> --src buddy. To inspect hardware, run python3 scripts/smoke_test.py.