m5stack-arduino-cli

name

m5stack-arduino-cli

description

Set up, diagnose, flash, and support development for M5Stack boards with Arduino CLI on Windows. Use when Codex needs to install ESP32 board support, detect the correct COM port, explain why `arduino-cli board list` shows `Unknown`, attach a board/FQBN to a sketch, compile or upload to M5Stack devices such as M5Core2, prepare supporting libraries, add or update sample sketches, or troubleshoot CH9102/CP210x USB-serial behavior.

M5Stack Arduino CLI

Use this skill to work with M5Stack boards from Arduino CLI on Windows, especially when the board appears as Unknown in arduino-cli board list.

Follow this workflow

1. Confirm that Windows sees the device as a serial port.
2. Confirm that arduino-cli exists. If it is not on PATH, look for the Arduino IDE bundled binary.
3. Ensure the ESP32 package index is configured and esp32:esp32 is installed.
4. Identify the correct COM port with arduino-cli board list, Windows device info, and, if needed, esptool.
5. Treat Unknown as a board auto-detection limitation unless Windows or esptool also fails.
6. Install common M5 libraries when the sketch touches display, input, or device helpers.
7. Attach the intended FQBN and port to the sketch with arduino-cli board attach.
8. Compile and upload using the attached settings or explicit --fqbn and -p.
9. When the user needs a starting point, reuse the sample sketch and PowerShell helpers from this repository.
10. When supporting ongoing development, keep the workflow focused on reproducible CLI commands, attached board metadata, and concrete sketch paths.

Key rules

• Do not assume Unknown means a missing driver.
• Prefer proving device health with Windows device status and esptool before changing drivers.
• For M5Core2 on Windows, expect the device to appear as a generic USB-serial bridge such as CH9102 or CP210x.
• Explain the difference between port detection and board identification: Arduino CLI may know the COM port while still not knowing the exact board model.
• If upload already works, do not recommend random driver reinstalls.
• If a sketch folder does not exist, create a minimal one and attach the board there.
• Prefer using the bundled sample scripts before rewriting the same PowerShell every time.
• Prefer updating or cloning the included example sketch before inventing a brand-new starter from scratch.

M5Core2 defaults

• FQBN: esp32:esp32:m5stack_core2
• Common USB bridge names:
  • USB-Enhanced-SERIAL CH9102
  • Silicon Labs CP210x USB to UART Bridge
• Common supporting libraries:
  • M5GFX
  • M5Unified

Reusable resources

• Use scripts/setup-m5core2.ps1 to locate Arduino CLI, ensure ESP32 support is configured, install common libraries, and optionally attach a sketch to a board/port.
• Use scripts/upload-m5core2.ps1 to compile and upload a sketch with attached settings or an explicit board and port.
• Use examples/m5core2/hello/hello.ino as the default sample sketch for setup checks and first-flash validation.
• Use scripts/generate_sprite_animation.py when a user wants to turn a transparent animated WebP into RGB565 frames and preview artifacts for M5Core2.
• Add future examples under examples/<board>/<sample>/ and future board setup flows under scripts/setup/.

Canonical command examples

Use these command shapes when writing guidance for users:

$cli = "C:\Users\<User>\AppData\Local\Programs\Arduino IDE\resources\app\lib\backend\resources\arduino-cli.exe"

& $cli board attach -p COM11 -b esp32:esp32:m5stack_core2 .\examples\m5core2\hello
& $cli compile .\examples\m5core2\hello
& $cli upload -p COM11 .\examples\m5core2\hello

When you need explicit board selection on each command:

& $cli compile --fqbn esp32:esp32:m5stack_core2 .\examples\m5core2\hello
& $cli upload -p COM11 --fqbn esp32:esp32:m5stack_core2 .\examples\m5core2\hello

When you want to show the helper-script path as well:

.\scripts\setup-m5core2.ps1 -SketchPath .\examples\m5core2\hello -Port COM11
.\scripts\upload-m5core2.ps1 -SketchPath .\examples\m5core2\hello -Port COM11

When the user wants to build a cat or pet animation from an external animated WebP:

uv run .\scripts\generate_sprite_animation.py --input 'D:\path\to\cat.webp' --output .\examples\m5core2\pixel_pet\generated_cat_animation.h --preview .\docs\public\examples\pixel_pet\generated_cat_animation_preview.png --sheet .\docs\public\examples\pixel_pet\generated_cat_animation_sheet.png --size 112 --frame-step 4 --sheet-columns 8 --loop-blend-frames 3
.\scripts\upload-m5core2.ps1 -SketchPath .\examples\m5core2\pixel_pet -Port COM11

Prefer this flow when the user already has rendered or background-removed animation frames and wants to keep the original motion instead of redrawing a hand-made sprite. The default loop blend makes the wrap from the last frame back to the first less abrupt.

Read references as needed

• Read references/windows-setup-and-diagnosis.md for the Windows and Arduino CLI workflow, command checklist, and explanation of Unknown.
• Read references/m5-board-notes.md when you need board mappings, M5-specific package/library guidance, or a concise explanation of why M5 boards often stay Unknown in board list.
• Read references/development-and-examples.md when you need setup, flash, and development examples you can adapt quickly.