debug-platformio

Original：🇨🇳 Chinese

Translated

1 scriptsChecked / no sensitive code detected

Used when performing GDB debugging on target boards via PlatformIO's built-in debugging features, supporting download-and-halt, attach-only, and crash context analysis.

4installs

Sourceleokemp223/embed-ai-tool

Added on2026-05-16

NPX Install

npx skill4agent add leokemp223/embed-ai-tool debug-platformio

SKILL.md Content (Chinese)

View Translation Comparison →

PlatformIO Debugging

Applicable Scenarios

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 project directory (containing
```
platformio.ini
```
).
Optional environment name and debug mode.

Auto Detection

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

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

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

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.