agentleFS
SensorsIotSensorsIot/Embedded-AI-Harness/.claude/skills/esp-pio-handling/SKILL.md

esp-pio-handling

Skill235 starsChanged 3 months agoMITView on GitHub

PlatformIO lifecycle for ESP32 firmware: platformio.ini, environment selection, build, upload and serial monitor, on local USB or through the testbench. Covers what differs from ESP-IDF — the .pio/build layout, the boot_app0 image an Arduino-framework build needs, and RFC2217 upload ports. Triggers on "pio", "platformio", "pio run", "pio upload", "platformio.ini", "lib_deps", "Arduino framework".

  • Sends data out

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Prefer POST /api/flash over driving esptool through RFC2217, for the reasons in esp-idf-handling.

    line 55

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PlatformIO Handling

Build, upload and monitor a PlatformIO ESP32 project, locally or through the testbench.

The testbench does not care which build system produced the image. Slot discovery, /api/flash, GPIO download mode, crash-loop and flapping recovery are the same either way and live in esp-idf-handling. This skill covers only what PlatformIO does differently. When something goes wrong with the bench rather than the build, read that skill.

Step 1: Detect environment

Same as esp-idf-handling: if /api/info answers, use the testbench; if nothing answers, flash over local USB. The discovery script is shared — .claude/skills/esp-idf-handling/discover-testbench.py --hosts.

Step 2: Build

pio run                    # default environment
pio run -e esp32dev        # one environment
pio run -t clean

With several environments in platformio.ini, ask which to build rather than guessing — they often target different boards. After a build, read the size report, and check lib_deps when a header is missing rather than installing libraries globally.

Step 3a: Upload — local USB

pio device list
pio run -t upload
pio run -e esp32dev -t upload
pio run -t upload && pio device monitor

Step 3b: Upload — testbench

Prefer POST /api/flash over driving esptool through RFC2217, for the reasons in esp-idf-handling. What differs here is where the images are and which ones exist.

PlatformIO writes them to .pio/build/<env>/, and there is no flash_args, so use the explicit bin@<offset> form:

cd .pio/build/<env>
curl -s -X POST $TESTBENCH_URL/api/flash \
  -F slot=SLOT1 -F chip=esp32 \
  -F 'bin@0x1000=@bootloader.bin' \
  -F 'bin@0x8000=@partitions.bin' \
  -F 'bin@0x10000=@firmware.bin' | jq .

An Arduino-framework build also needs boot_app0.bin at 0xe000. It is not in .pio/build/ — it ships inside the framework package, under ~/.platformio/packages/framework-arduinoespressif32*/tools/partitions/. Without it the bootloader has no OTA-selection data and boots the wrong slot after an update. An ESP-IDF project has no equivalent, which is why this step is not simply a pointer.

testbench-flash.py beside this skill collects all four and posts them:

pio run
python3 .claude/skills/esp-pio-handling/testbench-flash.py \
  --host <bench>:8080 --slot SLOT3 --chip esp32

Offsets: classic ESP32 → 0x1000, C3/S3/C6/H2 → 0x0. Fields and response: FSD Appendix D.9.

Fallback: RFC2217 upload (LAN clients only)

upload_port  = rfc2217://<bench>:4001
monitor_port = rfc2217://<bench>:4001
pio run -t upload --upload-port 'rfc2217://<bench>:4001?ign_set_control'

?ign_set_control is required: PlatformIO's esptool drives DTR/RTS, and over RFC2217 each one is a network roundtrip.

Step 4: Monitor

pio device monitor                                                    # local
pio device monitor --port 'rfc2217://<bench>:4001?ign_set_control'

For pattern matching, UDP logs, or watching a device whose USB port is occupied, use testbench-logging.

Troubleshooting

Bench-side problems — absent, flapping, download_mode, crash loops — are in esp-idf-handling. PlatformIO-specific:

IssueFix
No device foundpio device list; check the cable
Permission deniedsudo usermod -a -G dialout $USER, then re-login
Upload timeout on local USBEnter boot mode: hold BOOT, press RESET, release RESET then BOOT
Port busyAnother terminal holds the same RFC2217 port
Wrong boot mode detected (0x13)Classic ESP32 behind a USB-serial bridge (CP2102/CH340/CH9102) — its external auto-reset cannot be driven through the proxy. Flash via POST /api/flash (Step 3b). Native-USB C3/S3/C6/H2 strap internally and are unaffected
Wrong firmware runs after an OTAboot_app0.bin was not flashed — see Step 3b

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.