debug-platformio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PlatformIO 调试

PlatformIO Debugging

适用场景

Applicable Scenarios

Project Profile

中标明

build_system: platformio

或工作区中存在

platformio.ini

。

用户需要对目标板进行在线调试（单步、断点、查看寄存器和变量）。
需要分析崩溃现场（HardFault 寄存器、调用栈）。

build_system: platformio

is specified in the

Project Profile

, or

platformio.ini

exists in the workspace.

Users need to perform online debugging on target boards (single-step execution, breakpoints, viewing registers and variables).
Need to analyze crash contexts (HardFault registers, call stacks).

必要输入

Required Inputs

PlatformIO 工程目录（包含
```
platformio.ini
```
）。
可选的环境名称和调试模式。

PlatformIO project directory (containing
```
platformio.ini
```
).
Optional environment name and debug mode.

自动探测

Auto Detection

自动定位
```
pio
```
CLI。
解析
```
platformio.ini
```
中的
```
debug_tool
```
配置。
PlatformIO 自动管理调试服务器（OpenOCD/pyOCD/J-Link GDB Server），无需手动配置。

Automatically locates the
```
pio
```
CLI.
Parses the
```
debug_tool
```
configuration in
```
platformio.ini
```
.
PlatformIO automatically manages debug servers (OpenOCD/pyOCD/J-Link GDB Server), no manual configuration required.

执行步骤

Execution Steps

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

探测调试环境：

bash

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

执行调试：

bash

python scripts/pio_debugger.py --project-dir <工程目录> --env <环境名> --mode download-and-halt

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

Detect the debugging environment:

bash

python scripts/pio_debugger.py --detect --project-dir <project directory> --env <environment name>

Execute debugging:

bash

python scripts/pio_debugger.py --project-dir <project directory> --env <environment name> --mode download-and-halt

调试模式

Debug Modes

```
download-and-halt
```
：下载固件到目标板，暂停在入口点，输出寄存器和回溯信息。
```
attach-only
```
：附加到正在运行的目标，不下载固件，输出当前状态。
```
crash-context
```
：暂停目标，读取寄存器、完整回溯和 Cortex-M Fault 寄存器（CFSR/HFSR/MMFAR/BFAR）。

```
download-and-halt
```
: Downloads firmware to the target board, pauses at the entry point, and outputs register and backtrace information.
```
attach-only
```
: Attaches to a running target without downloading firmware, outputs the current status.
```
crash-context
```
: Pauses the target, reads registers, complete backtraces, and Cortex-M Fault registers (CFSR/HFSR/MMFAR/BFAR).

失败分流

Failure Diversion

```
connection-failure
```
：调试器未连接或设备无响应。
```
debug-not-supported
```
：板卡不支持调试或未配置 debug_tool。
```
debug-failure
```
：调试会话异常终止。

```
connection-failure
```
: Debugger not connected or device unresponsive.
```
debug-not-supported
```
: Board does not support debugging or
```
debug_tool
```
is not configured.
```
debug-failure
```
: Debug session terminated abnormally.

输出约定

Output Convention

示例输出格式：

调试完成 ✅
  工程: ESP32_DEV → 环境: esp32dev
  板卡: esp32dev | 调试工具: esp-prog
  模式: download-and-halt
  关键观察: 5 条（寄存器、回溯帧）

Sample output format:

Debugging completed ✅
  Project: ESP32_DEV → Environment: esp32dev
  Board: esp32dev | Debug Tool: esp-prog
  Mode: download-and-halt
  Key Observations: 5 items (registers, backtrace frames)

交接关系

Handover Relationship

从
```
build-platformio
```
接收编译成功的工程信息。
调试发现问题后可回交给
```
build-platformio
```
修改代码重新编译。

Receives successfully compiled project information from
```
build-platformio
```
.
After issues are found during debugging, can hand back to
```
build-platformio
```
for code modification and recompilation.