build-platformio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

构建 PlatformIO 工程

Building PlatformIO Projects

适用场景

Applicable Scenarios

Project Profile

中标明

build_system: platformio

或工作区中存在

platformio.ini

。

用户希望对 PlatformIO 工程执行编译、清理或上传固件。
烧录或调试流程需要新的
```
ELF
```
、
```
HEX
```
或
```
BIN
```
。
需要在构建前确认 PlatformIO CLI 是否就绪。

The

Project Profile

specifies

build_system: platformio

or a

platformio.ini

exists in the workspace.

Users want to compile, clean, or upload firmware for a PlatformIO project.
A new
```
ELF
```
,
```
HEX
```
, or
```
BIN
```
is required for flashing or debugging processes.
Need to confirm if PlatformIO CLI is ready before building.

必要输入

Required Inputs

工作区路径（包含
```
platformio.ini
```
），或一份已有的
```
Project Profile
```
。
可选的环境名称（environment）。

Workspace path (containing
```
platformio.ini
```
), or an existing
```
Project Profile
```
.
Optional environment name.

自动探测

Automatic Detection

脚本自动检测
```
pio
```
命令是否可用并获取版本。
解析
```
platformio.ini
```
中的环境列表，提取 platform、board、framework 和上传协议。
识别
```
[platformio]
```
section 中的
```
default_envs
```
作为默认环境。
若未指定环境且存在默认环境，使用默认环境；否则使用第一个环境。
在
```
.pio/build/<env>/
```
中搜索 firmware.elf/hex/bin 产物，按
```
ELF > HEX > BIN
```
排序。
若存在多个同样合理的环境，列出候选而不是静默猜测。

The script automatically detects if the
```
pio
```
command is available and retrieves its version.
Parses the list of environments in
```
platformio.ini
```
, extracting platform, board, framework, and upload protocol.
Identifies
```
default_envs
```
in the
```
[platformio]
```
section as the default environment.
If no environment is specified and a default environment exists, use the default environment; otherwise, use the first environment.
Searches for firmware.elf/hex/bin artifacts in
```
.pio/build/<env>/
```
, sorted by
```
ELF > HEX > BIN
```
.
If multiple equally reasonable environments exist, list candidates instead of making silent guesses.

执行步骤

Execution Steps

先阅读 references/usage.md，确认本次是环境探测、列出环境、执行构建，还是仅扫描产物。
若不确定环境是否就绪，先运行自带脚本 scripts/platformio_builder.py 的
```
--detect
```
模式确认。

使用

--list-envs --project-dir <dir>

确认可用环境，再用

--project-dir

--env

执行构建。

读取脚本输出的构建结果和产物扫描报告，重点关注首选产物（ELF > HEX > BIN）和失败分类。
将构建环境、产物路径和板卡信息写回
```
Project Profile
```
，并在需要时交给下游 skill。

First read references/usage.md to confirm whether this is environment detection, listing environments, executing builds, or just scanning artifacts.
If unsure whether the environment is ready, first run the
```
--detect
```
mode of the built-in script scripts/platformio_builder.py to confirm.
Use
```
--list-envs --project-dir <dir>
```
to confirm available environments, then use
```
--project-dir
```
+
```
--env
```
to execute the build.
Read the build results and artifact scan report output by the script, focusing on the preferred artifacts (ELF > HEX > BIN) and failure categories.
Write the build environment, artifact path, and board information back to the
```
Project Profile
```
, and hand it over to downstream skills when needed.

失败分流

Failure Handling

当
```
pio
```
命令不可用时，返回
```
environment-missing
```
。
当
```
platformio.ini
```
不存在或环境名无效时，返回
```
project-config-error
```
。
当构建看似成功但未找到可烧录或可调试产物时，返回
```
artifact-missing
```
。
当存在多个同样合理的环境，且任意选择都不安全时，返回
```
ambiguous-context
```
。

When the
```
pio
```
command is unavailable, return
```
environment-missing
```
.
When
```
platformio.ini
```
does not exist or the environment name is invalid, return
```
project-config-error
```
.
When the build appears successful but no flashable or debuggable artifacts are found, return
```
artifact-missing
```
.
When multiple equally reasonable environments exist and arbitrary selection is unsafe, return
```
ambiguous-context
```
.

平台说明

Platform Notes

PlatformIO 完全跨平台（Linux / macOS / Windows），无平台限制。
自带脚本使用 Python 标准库和 subprocess 调用
```
pio
```
，构建调度路径本身是跨平台的。
输出中的构建目录和产物路径应保持为绝对路径，方便下游烧录和调试 skill 直接复用。

PlatformIO is fully cross-platform (Linux / macOS / Windows) with no platform restrictions.
The built-in script uses Python standard libraries and subprocess to call
```
pio
```
, and the build scheduling path itself is cross-platform.
The build directory and artifact paths in the output should remain absolute paths for direct reuse by downstream flashing and debugging skills.

输出约定

Output Conventions

输出构建命令、工程目录、环境名、板卡和首选产物路径。

用

artifact_path

、

artifact_kind

和板卡信息更新

Project Profile

。

成功后推荐
```
flash-openocd
```
或
```
debug-gdb-openocd
```
。

Output the build command, project directory, environment name, board, and preferred artifact path.

Update the

Project Profile

with

artifact_path

artifact_kind

, and board information.

Recommend
```
flash-openocd
```
or
```
debug-gdb-openocd
```
after success.

交接关系

Handover Relationships

当下一步意图是给硬件烧录程序时，将成功构建结果交给
```
flash-openocd
```
。
当下一步需要符号信息或调试会话时，将成功构建结果交给
```
debug-gdb-openocd
```
。
PlatformIO 自带上传功能（
```
--upload
```
），简单场景可直接使用而无需交接。

When the next step is to flash the program to hardware, hand over the successful build result to
```
flash-openocd
```
.
When the next step requires symbol information or a debugging session, hand over the successful build result to
```
debug-gdb-openocd
```
.
PlatformIO has a built-in upload function (
```
--upload
```
), which can be used directly in simple scenarios without handover.