debug-platformio

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass, no license.

Audit 0.4.1 · source sha f2eee4d05246 · 28 Oct 2026Report an issue or request a re-scan

• Publisherleokemp223 GitHub userOwner of the repository this skill is read from
• Source folderleokemp223/embed-ai-tool/skills/debug-platformioThe exact folder we audited
• LicenceNot declaredAs the repository states it
• Commit pinned for this verdictf2eee4d05246A new audit runs when the source changes
• Repository statusNot archivedLast push 69 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 当需要通过 PlatformIO 内置调试功能对目标板进行 GDB 调试时使用,支持下载暂停、附加和崩溃现场分析。

---
name: debug-platformio
description: 当需要通过 PlatformIO 内置调试功能对目标板进行 GDB 调试时使用,支持下载暂停、附加和崩溃现场分析。
---

# PlatformIO 调试

## 适用场景

- `Project Profile` 中标明 `build_system: platformio` 或工作区中存在 `platformio.ini`。
- 用户需要对目标板进行在线调试(单步、断点、查看寄存器和变量)。
- 需要分析崩溃现场(HardFault 寄存器、调用栈)。

## 必要输入

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

## 自动探测

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

## 执行步骤

1. 先阅读 [references/usage.md](references/usage.md),确认本次操作。
2. 探测调试环境:
   ```bash
   python scripts/pio_debugger.py --detect --project-dir <工程目录> --env <环境名>
   ```
3. 执行调试:
   ```bash
   python scripts/pio_debugger.py --project-dir <工程目录> --env <环境名> --mode download-and-halt
   ```

## 调试模式

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

## 失败分流

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

## 输出约定

示例输出格式:

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

## 交接关系

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

Excerpt, first 1,294 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/leokemp223/embed-ai-tool
git -C embed-ai-tool checkout f2eee4d05246

Works in

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source f2eee4d05246

Questions about debug-platformio

• github.com/leokemp223/embed-ai-tool/tree/master/skills/debug-pla — the audited source at commit f2eee4d05246 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology