SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsflash-idf

flash-idf

General & other

View repository

Updated 10-15 23:58

About this skill

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 debug session via JTAG.
  • The team needs a standardized ESP-IDF flashing process that can smoothly hand off to serial monitoring or debugging.

Required Inputs

  • Workspace path (containing the already-built build/ directory), or the artifact_path containing Project Profile。
  • Serial device path and baud rate.
  • Optional debug probe configuration (for JTAG debug mode).

First-Time Parameter Confirmation

On the first invocation, the following parameters must be confirmed with the user and must not be skipped or automatically populated with detected values:

  • Serial device: List the detected serial devices for the user to choose from; even if there is only one, it must not be selected automatically.
  • Baud rate: Show the user the default value 460800 and confirm whether it needs to be changed.

When Project Profile has already recorded the above parameters (i.e., not the first time), they can be reused directly without asking again.

Automatic Detection

  • Upon startup, the script automatically reuses the last successful profile in the project root directory .em_skill.json as the default parameters (explicit parameters take precedence; there is no need to manually pass --resume）；--resume is only used to assert that the cache must exist; if there is no cache, it exits with a non-zero code. When there is no cache or the user explicitly requests re-detection, the script automatically falls back to a normal scan.
  • Scan system serial devices: Linux /dev/ttyUSB*、/dev/ttyACM*，macOS /dev/cu.usbserial*、/dev/cu.wchusbserial*，Windows COM*。
  • Read the Flash size and partition table configuration in sdkconfig .
  • Check whether valid flashing artifacts exist in the build/ directory (*.bin、flasher_args.json）。
  • Detection results are only displayed to the user as a candidate list and are not selected automatically.

Execution Steps

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

Failure Triage

  • When idf.py is unavailable, return environment-missing, prompting the user to install ESP-IDF and activate the environment (v5.x uses export.sh, v6.0+ uses the EIM activation script).
  • When the serial device does not exist or is occupied, return connection-failure。
  • When a Linux user lacks serial port access permissions, return permission-problem, suggesting adding the dialout group.
  • When the build/ directory does not exist or artifacts are missing, return artifact-missing, recommending build-idf。
  • When the chip does not respond during the flashing process, return target-response-abnormal。
  • When multiple serial port devices exist 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。
  • The ESP32 series typically uses USB-UART bridge chips (CP2102, CH340), and the corresponding drivers need to be installed.
  • The bundled script calls idf.pyvia subprocess; the flashing scheduling path itself is cross-platform.

Output Conventions

  • Output the flash command, serial port device, baud rate, Flash size, and flashing status.
  • In Project Profile , retain or update serial_port、baud_rate、idf_target。
  • Recommend the next skill based on the user's intent: to view runtime logs, recommend serial-monitor; for debugging needs, recommend debug-gdb-openocd。

Handoff Relationships

  • When the next step is to view runtime logs, hand off the successful flashing result to serial-monitor。
  • When the user needs breakpoint debugging or crash analysis, hand off the result to debug-gdb-openocd。
  • When the firmware artifact is missing, recommend that the user first use build-idf to compile.