flash-platformio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PlatformIO 烧录

PlatformIO Firmware Flashing

适用场景

Applicable Scenarios

Project Profile

中标明

build_system: platformio

或工作区中存在

platformio.ini

。

用户希望将编译产物烧录到目标板，利用 PlatformIO 内置的上传机制。
支持串口、JTAG、DFU 等多种上传协议，由
```
platformio.ini
```
中的
```
upload_protocol
```
决定。

Project Profile

specifies

build_system: platformio

platformio.ini

exists in the workspace.

Users want to flash compiled artifacts to the target board using PlatformIO's built-in upload mechanism.
Supports multiple upload protocols such as serial port, JTAG, DFU, determined by
```
upload_protocol
```
in
```
platformio.ini
```
.

必要输入

Required Inputs

PlatformIO 工程目录（包含
```
platformio.ini
```
）。
可选的环境名称和上传端口。

PlatformIO project directory (contains
```
platformio.ini
```
).
Optional environment name and upload port.

自动探测

Automatic Detection

自动定位
```
pio
```
CLI。
解析
```
platformio.ini
```
中的环境列表和
```
upload_protocol
```
。
若未指定环境，使用
```
default_envs
```
或第一个环境。
可列出已连接设备帮助用户确认端口。

Automatically locates the
```
pio
```
CLI.
Parses the list of environments and
```
upload_protocol
```
in
```
platformio.ini
```
.
If no environment is specified, uses
```
default_envs
```
or the first environment.
Can list connected devices to help users confirm the port.

执行步骤

Execution Steps

先阅读 references/usage.md，确认本次操作。

对于常见场景，直接一次调用完成烧录：

bash

python scripts/pio_flasher.py --flash --project-dir <工程目录> --env <环境名>

若需指定上传端口：

bash

python scripts/pio_flasher.py --flash --project-dir <工程目录> --env <环境名> --upload-port COM3

读取脚本输出的烧录结果报告，关注成功/失败状态和证据。
将烧录结果写回
```
Project Profile
```
，推荐下一步 skill。

First read references/usage.md to confirm the operation.

For common scenarios, complete flashing with a single call:

bash

python scripts/pio_flasher.py --flash --project-dir <project directory> --env <environment name>

To specify an upload port:

bash

python scripts/pio_flasher.py --flash --project-dir <project directory> --env <environment name> --upload-port COM3

Read the flashing result report output by the script, focusing on success/failure status and evidence.
Write the flashing result back to
```
Project Profile
```
and recommend the next skill.

失败分流

Failure Diversion

```
connection-failure
```
：设备未连接、串口被占用或权限不足。
```
project-config-error
```
：板卡配置无效或环境名不存在。
```
upload-failure
```
：上传过程中出错。

```
connection-failure
```
: Device not connected, serial port occupied, or insufficient permissions.
```
project-config-error
```
: Invalid board configuration or environment name does not exist.
```
upload-failure
```
: Error occurred during upload.

输出约定

Output Convention

示例输出格式：

烧录成功 ✅
  工程: ESP32_DEV → 环境: esp32dev
  板卡: esp32dev | 平台: espressif32
  固件: firmware.bin (200.0 KB)
  耗时: 15.3 秒

成功后推荐
```
serial-monitor
```
（查看串口输出）或
```
debug-platformio
```
（在线调试）。
失败时输出失败分类和日志证据。

Example output format:

Flashing succeeded ✅
  Project: ESP32_DEV → Environment: esp32dev
  Board: esp32dev | Platform: espressif32
  Firmware: firmware.bin (200.0 KB)
  Time taken: 15.3 seconds

After success, recommend
```
serial-monitor
```
(view serial output) or
```
debug-platformio
```
(online debugging).
Output failure category and log evidence when failed.

交接关系

Handover Relationships

从
```
build-platformio
```
接收编译成功的工程信息。
烧录成功后交给
```
serial-monitor
```
（查看串口输出）或
```
debug-platformio
```
（在线调试）。

Receives project information of successful compilation from
```
build-platformio
```
.
After successful flashing, hand over to
```
serial-monitor
```
(view serial output) or
```
debug-platformio
```
(online debugging).