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
In this repository17 other files it gives its agents.
- buildSkill
- commissionSkill
- defineSkill
- esp-idf-handlingSkill
- grill-meSkill
- harnessSkill
- sdr-receiverSkill
- setup-actionSkill
- signal-generatorSkill
- testbench-bleSkill
- testbench-debugSkill
- testbench-installSkill
- testbench-integrationSkill
- testbench-loggingSkill
- testbench-mqttSkill
- testbench-test-handlingSkill
- testbench-wifiSkill
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
- Very specific: line 55
Prefer POST /api/flash over driving esptool through RFC2217, for the reasons in esp-idf-handling.
≈ “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.
Files
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 cleanWith 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 monitorStep 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 esp32Offsets: 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>:4001pio 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:
| Issue | Fix |
| No device found | pio device list; check the cable |
| Permission denied | sudo usermod -a -G dialout $USER, then re-login |
| Upload timeout on local USB | Enter boot mode: hold BOOT, press RESET, release RESET then BOOT |
| Port busy | Another 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 OTA | boot_app0.bin was not flashed — see Step 3b |
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
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.

