ESP-IDF Flashing and Debugging

Applicable Scenarios

The workspace already has ESP-IDF build artifacts, and the user wants to flash them to the target board.
The user needs to erase Flash or re-flash firmware.
The user needs to start an OpenOCD debugging session via JTAG.
The team needs a standardized ESP-IDF flashing process that can smoothly transition to serial port monitoring or debugging.

Required Inputs

Workspace path (including the built
```
build/
```
directory), or a
```
Project Profile
```
containing
```
artifact_path
```
.
Serial port device path and baud rate.
Optional debug probe configuration (for JTAG debugging mode).

First-Time Parameter Confirmation

When calling for the first time, the following parameters must be confirmed with the user; skipping or automatically using detected values is not allowed:

Serial Port Device: List detected serial port devices for the user to select; do not automatically select even if there is only one.
Baud Rate: Show the user the default value 460800 and confirm if modification is needed.

If the above parameters are already recorded in the

Project Profile

(i.e., not the first time), they can be directly reused without asking again.

Automatic Detection

Scan system serial port devices: Linux

/dev/ttyUSB*

/dev/ttyACM*

; macOS

/dev/cu.usbserial*

/dev/cu.wchusbserial*

; Windows

COM*

Read Flash size and partition table configuration from
```
sdkconfig
```
.
Check if valid flashing artifacts (
```
*.bin
```
,
```
flasher_args.json
```
) exist in the
```
build/
```
directory.
Detection results are only displayed to the user as a candidate list; no automatic selection is made.

Execution Steps

First read references/usage.md to confirm whether this operation is environment detection, flashing, erasure, or starting debugging.
If the environment status is uncertain, first run the built-in script scripts/idf_flasher.py in
```
--detect
```
mode to confirm.
Use
```
--flash --project <path>
```
to perform flashing; serial port parameters can be specified via
```
--port
```
and
```
--baud
```
.
If the user needs to erase Flash, use
```
--erase-flash
```
.
If the user needs to view serial port output immediately after flashing, prompt them to manually run
```
idf.py flash monitor
```
(an interactive long-running command).
If the user needs JTAG debugging, use
```
--debug
```
to detect and start the OpenOCD service.
Read the flashing result report output by the script, focusing on the flashing status and failure categories.
Write the flashing configuration and results back to the
```
Project Profile
```
.

Failure Diversion

When
```
idf.py
```
is unavailable, return
```
environment-missing
```
and prompt the user to install ESP-IDF and activate the environment (use
```
export.sh
```
for v5.x, use EIM activation script for v6.0+).
When the serial port device does not exist or is occupied, return
```
connection-failure
```
.
When a Linux user does not have serial port access permission, return
```
permission-problem
```
and recommend adding to the
```
dialout
```
group.
When the
```
build/
```
directory does not exist or artifacts are missing, return
```
artifact-missing
```
and recommend
```
build-idf
```
.
When the chip does not respond during flashing, return
```
target-response-abnormal
```
.
When there are multiple serial port devices and the target cannot be determined, return
```
ambiguous-context
```
.

Platform Notes

Serial port device naming varies by platform: Linux
```
/dev/ttyUSB0
```
, macOS
```
/dev/cu.usbserial-*
```
, Windows
```
COM3
```
.
Linux users may need to add themselves to the
```
dialout
```
group:
```
sudo usermod -aG dialout $USER
```
.
ESP32 series usually use USB-UART bridge chips (CP2102, CH340), and corresponding drivers need to be installed.
The built-in script calls
```
idf.py
```
via subprocess, and the flashing scheduling path itself is cross-platform.

Output Conventions

Output the flashing command, serial port device, baud rate, Flash size, and flashing status.

Retain or update

serial_port

baud_rate

, and

idf_target

in the

Project Profile

Recommend the next skill based on the user's intention: recommend
```
serial-monitor
```
for viewing running logs, and
```
debug-gdb-openocd
```
for debugging needs.

Handover Relationships

When the next step is to view running logs, pass the successful flashing result to
```
serial-monitor
```
.
When the user needs breakpoint debugging or crash analysis, pass the result to
```
debug-gdb-openocd
```
.
When firmware artifacts are missing, recommend the user to compile first using
```
build-idf
```
.

flash-idf

NPX Install

Tags

SKILL.md Content (Chinese)