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.

3installs
Sourceleokemp223/embed-ai-tool
Added on

NPX Install

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

Tags

Translated version includes tags in frontmatter
platformio-debugginggdb-debugembedded-developmentcrash-analysisdebug-workflow

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

  1. First read references/usage.md to confirm the operation.
  2. Detect the debugging environment:
    bash
    python scripts/pio_debugger.py --detect --project-dir <project directory> --env <environment name>
  3. 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.