| name | esp32-flash-test |
| description | Auto-flash PlatformIO firmware to ESP32 via USB serial and run automated serial CLI tests. Use when the user needs to: (1) upload firmware to an ESP32 dev board, (2) send CLI commands over serial and verify responses, (3) detect crashes (Guru Meditation / panic) automatically, or (4) iterate on embedded UI/ESP32 code with rapid build-flash-test cycles.
|
ESP32 Flash & Serial Test
Prerequisites
- PlatformIO CLI installed (
pio in PATH)
pyserial available (python3 -c "import serial")- ESP32 connected via USB (WCH/CP210/FTDI etc.)
Quick Start
Run the bundled script from the project root:
python3 .agents/skills/esp32-flash-test/scripts/flash_and_test.py
Default behavior:
- Auto-detects
/dev/cu.wchusbserial* (or similar)
- Runs
pio run --target upload
- Opens serial @ 115200
- Sends:
demo → home → demo → home
- Prints all output and flags any crash signatures
Custom Commands
python3 .agents/skills/esp32-flash-test/scripts/flash_and_test.py \
--cmd "launch filemanager" \
--cmd "home" \
--wait 4
Skip Flash (Serial-only)
python3 .agents/skills/esp32-flash-test/scripts/flash_and_test.py --no-flash
Manual Serial Port
python3 .agents/skills/esp32-flash-test/scripts/flash_and_test.py --port /dev/cu.wchusbserial140
Crash Detection
The script watches for these keywords in serial output:
Guru Meditation Errorpanic'edLoadProhibitedStoreProhibitedInstrFetchProhibited
If any appear, the script exits with code 1 and prints [!!!] CRASH DETECTED.
Backtrace Decoding (Manual)
If a crash occurs, copy the backtrace addresses and run:
export PATH="$HOME/.platformio/packages/toolchain-xtensa-esp32s3/bin:$PATH"
xtensa-esp32s3-elf-addr2line -e .pio/build/<env>/firmware.elf \
0x420xxxxx 0x420xxxxx ...
Replace <env> with the actual PIO environment name.
Script Reference
scripts/flash_and_test.py — Main flash + serial test runner
--port Specify serial port--baud Baud rate (default 115200)--no-flash Skip upload--cmd Add command (repeatable)--wait Seconds to wait after each command
