flash-idf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESP-IDF 烧录调试

ESP-IDF Flashing and Debugging

适用场景

Applicable Scenarios

工作区已经具备 ESP-IDF 构建产物，且用户希望烧录到目标板。
用户需要擦除 Flash 或重新烧录固件。
用户需要通过 JTAG 启动 OpenOCD 调试会话。
团队需要一条标准化的 ESP-IDF 烧录流程，并可顺畅交接到串口监视或调试。

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

工作区路径（含已构建的
```
build/
```
目录），或包含
```
artifact_path
```
的
```
Project Profile
```
。
串口设备路径和波特率。
可选的调试探针配置（用于 JTAG 调试模式）。

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

首次调用时，必须向用户确认以下参数，不得跳过或自动使用探测值：

串口设备：列出探测到的串口设备供用户选择，即使只有一个也不得自动选择。
波特率：向用户展示默认值 460800 并确认是否需要修改。

当

Project Profile

中已记录过上述参数（即非首次），可直接复用，无需再次询问。

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

扫描系统串口设备：Linux

/dev/ttyUSB*

、

/dev/ttyACM*

，macOS

/dev/cu.usbserial*

、

/dev/cu.wchusbserial*

，Windows

COM*

。

读取
```
sdkconfig
```
中的 Flash 大小和分区表配置。
检查
```
build/
```
目录中是否存在有效的烧录产物（
```
*.bin
```
、
```
flasher_args.json
```
）。
探测结果仅作为候选列表展示给用户，不自动选择。

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

先阅读 references/usage.md，确认本次是环境探测、烧录、擦除，还是启动调试。
若不确定环境状态，先运行自带脚本 scripts/idf_flasher.py 的
```
--detect
```
模式确认。
使用
```
--flash --project <path>
```
执行烧录，可通过
```
--port
```
和
```
--baud
```
指定串口参数。
若用户需要擦除 Flash，使用
```
--erase-flash
```
。
若用户需要烧录后立即查看串口输出，提示手动运行
```
idf.py flash monitor
```
（交互式长运行命令）。
若用户需要 JTAG 调试，使用
```
--debug
```
检测并启动 OpenOCD 服务。
读取脚本输出的烧录结果报告，重点关注烧录状态和失败分类。
将烧录配置和结果写回
```
Project Profile
```
。

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

当
```
idf.py
```
不可用时，返回
```
environment-missing
```
，提示用户安装 ESP-IDF 并激活环境（v5.x 使用
```
export.sh
```
，v6.0+ 使用 EIM 激活脚本）。
当串口设备不存在或被占用时，返回
```
connection-failure
```
。
当 Linux 用户无串口访问权限时，返回
```
permission-problem
```
，建议添加
```
dialout
```
组。
当
```
build/
```
目录不存在或产物缺失时，返回
```
artifact-missing
```
，推荐
```
build-idf
```
。
当烧录过程中芯片无响应时，返回
```
target-response-abnormal
```
。
当存在多个串口设备且无法确定目标时，返回
```
ambiguous-context
```
。

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

串口设备命名因平台而异：Linux
```
/dev/ttyUSB0
```
，macOS
```
/dev/cu.usbserial-*
```
，Windows
```
COM3
```
。
Linux 用户可能需要将自己添加到
```
dialout
```
组：
```
sudo usermod -aG dialout $USER
```
。
ESP32 系列通常使用 USB-UART 桥接芯片（CP2102、CH340），需要安装对应驱动。
自带脚本通过 subprocess 调用
```
idf.py
```
，烧录调度路径本身是跨平台的。

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

输出烧录命令、串口设备、波特率、Flash 大小和烧录状态。

在

Project Profile

中保留或更新

serial_port

、

baud_rate

、

idf_target

。

根据用户意图推荐下一步 skill：查看运行日志推荐
```
serial-monitor
```
，需要调试推荐
```
debug-gdb-openocd
```
。

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

当下一步要看运行日志时，将成功烧录结果交给
```
serial-monitor
```
。
当用户需要断点调试或崩溃分析时，将结果交给
```
debug-gdb-openocd
```
。
当固件产物缺失时，推荐用户先使用
```
build-idf
```
编译。

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
```
.