| name | flash |
| description | Build and flash firmware to connected ESP32-S3, then open serial monitor |
Flash Skill / Tester Guide
This file is both:
- the
/flash operational skill for Claude
- a tester-facing guide for building, flashing, verifying, and debugging FLP firmware on LilyGo T3-S3 boards
Scope
Use this guide when a tester needs to:
- build firmware
- flash an exit node
- flash a relay / sensor node
- switch a board from exit mode to relay mode or back
- capture boot / monitor logs for debugging
Core concepts
Build roles
- Exit node / gateway build
- uses
sdkconfig.defaults
- WiFi + MQTT enabled
- Relay / sensor build
- uses
sdkconfig.defaults plus sdkconfig.defaults.relay
- WiFi AP connection disabled
- still uses WiFi STA / ESP-NOW for mesh participation
Role switch rule
Whenever a board changes role between exit and relay, delete sdkconfig and rebuild.
This avoids stale configuration leaking from a previous build mode.
Current defaults worth knowing
- target =
esp32s3
- auto-demo currently defaults to enabled with 60 second interval
- manual demo button default is GPIO 1 when auto-demo is disabled
What success looks like after flash
Exit node
Expected indicators:
- serial shows WiFi startup and IP acquisition
- serial shows MQTT connected
- OLED title shows
GATEWAY
- OLED shows
W:OK
Relay / sensor node
Expected indicators:
- serial shows WiFi STA started for ESP-NOW / mesh use
- serial does not connect to an AP
- OLED title shows
RELAY
- OLED shows
W:--
Useful OLED fields
W:OK = WiFi connected to APW:-- = no AP connection (expected for relay build)Lo P:<n> = LoRa present / ESP-NOW peer count lineN<n> C<h> D<h> = neighbors, control-path hops, data-path hops>> Cloud CMD = recent cloud command received
macOS / Linux workflow
Use the in-repo wrapper from flp-node/.
Why use the wrapper
The ./idf wrapper:
- sources
~/esp/esp-idf-v5.5.3/export.sh
- tracks whether the current build is exit or relay mode
- clears
sdkconfig on build / fresh
- auto-picks a serial port if one is not specified
Exit node
cd flp-node
./idf build
./idf flash monitor
Relay / sensor node
cd flp-node
./idf relay build
./idf relay flash monitor
Optional commands
./idf fresh
./idf relay fresh
./idf flash -p /dev/cu.usbmodem12301 monitor
./idf relay flash -p /dev/cu.usbmodem12301 monitor
If multiple serial ports are detected, the wrapper will prompt for selection.
Windows workflow
Run commands inside ESP-IDF PowerShell or ESP-IDF CMD.
If idf.py is not found, the tester is in the wrong terminal.
Exit node
cd flp-node
Remove-Item sdkconfig -ErrorAction SilentlyContinue
idf.py -D "SDKCONFIG_DEFAULTS=sdkconfig.defaults" set-target esp32s3
idf.py build
idf.py -p COM3 flash monitor
Relay / sensor node
cd flp-node
Remove-Item sdkconfig -ErrorAction SilentlyContinue
idf.py -D "SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.defaults.relay" set-target esp32s3
idf.py build
idf.py -p COM4 flash monitor
Replace COM3 / COM4 with the actual port shown in Device Manager.
Port identification
macOS / Linux
Common device names:
/dev/cu.usbmodem*/dev/cu.usbserial*/dev/cu.SLAB*
Windows
Check Device Manager > Ports (COM & LPT).
Typical labels:
- USB Serial Device
- USB-SERIAL CH340
- CP210x USB to UART Bridge
If the port disappears during flash/monitor work, try a different USB cable first.
Flashing one board at a time
Recommended tester workflow:
- label the board physically
- connect only one board when possible
- flash it
- record:
- board role
- USB port
- node address from OLED
- disconnect it
- repeat for the next board
This avoids mixing up ports and addresses later in experiment runs.
Post-flash checklist
After every flash, verify:
- build mode was the intended one
- serial monitor opened successfully
- device booted without repeated crash/reboot loop
- OLED came up
- role shown on OLED matches intended role
- connectivity state matches intended role
- node address
FLP-XXXX is recorded
Do not move on to experiment testing until these checks pass.
Common failure modes and fixes
idf.py not found
Cause:
Fix:
- macOS/Linux: use the repo wrapper
./idf
- Windows: open ESP-IDF PowerShell / CMD
Capture:
- exact terminal command used
- terminal output
Serial port not found
Cause:
- bad cable
- driver missing
- wrong port selected
- board not enumerated
Fix:
- reconnect board
- change cable
- check Device Manager or
/dev/cu.*
- close other tools holding the port
Capture:
- port list screenshot / output
- cable / adapter details if known
could not open port
Cause:
- another serial monitor still owns the port
Fix:
- close Arduino IDE, PuTTY, screen, minicom, tmux monitor sessions, or other
idf.py monitor instances
Wrong role after flashing
Cause:
sdkconfig was reused from the previous build mode
Fix:
- delete
sdkconfig
- rebuild using the correct role workflow
Exit node shows W:--
Cause:
- exit node did not connect to WiFi / AP
Check:
- WiFi credentials
- access point availability
- build role really is exit mode
Relay node shows W:OK
Cause:
- wrong firmware image flashed (exit instead of relay)
Fix:
- rebuild using relay overlay
OLED blank or missing
Check:
- board really finished booting
- build is current
- power is stable
- if needed, rebuild from clean state and retry
Reboot loop immediately after flash
Check:
- full serial boot log
- whether the first boot after flash differs from the second boot
- power quality / cable stability
Do not summarize from memory; capture the full boot log.
Evidence to capture when flashing fails
Ask the tester for:
- exact command used
- OS used
- port used
- full terminal output
- OLED photo if the board boots at all
- whether the board ever entered monitor
- whether the same cable/port works with another board
Suggested tester handoff format
When giving this to a tester, ask them to fill in:
- board label:
- intended role:
- OS used:
- flash command used:
- port used:
- OLED address after flash:
- OLED role shown:
- WiFi state shown:
- serial result summary:
- pass / fail:
- notes:
Assistant interaction pattern
When used as a skill, guide the user in this order:
- ask OS
- ask board role to flash
- ask whether they want build-only or flash+monitor
- ask port if not obvious
- provide only the matching command set
- wait for the result
- if flash fails, switch to the failure mode checklist above
Do not assume the same commands work unchanged across macOS/Linux and Windows.
