stm32debug-skill

---

name: "stm32-debug" description: "Compiles, flashes, debugs, and monitors STM32 firmware. Invoke for build, flash, GDB, SWO logs, or real-time variable/register monitoring."

STM32 Debug Skill

This skill provides a comprehensive suite of tools for STM32 development, including compilation, flashing, debugging, SWO logging, and real-time monitoring of variables and registers.

Prerequisites

• arm-none-eabi-gcc
• openocd
• gdb-multiarch
• python3
• SVD file (e.g., STM32F746.svd)

Commands

1. Unified CLI

Prefer the unified entrypoint:

./scripts/stm32-debug <command> [options]

Recommended first step for a project:

./scripts/stm32-debug start \
  --elf build/firmware.elf \
  --svd STM32F746.svd \
  --source-root Core \
  --build-cmd "cmake --build build/Release" \
  --flash-elf build/firmware.elf

2. Build And Flash

Build via your project build system:

make

Flash firmware directly:

./scripts/flash.sh <elf_file>

Or use one-step cycle mode:

./scripts/stm32-debug cycle counter voltage --flash --wait 10

3. Read Variables, Registers, Fields, Addresses

The read command auto-detects the target kind and uses ELF or SVD accordingly.

# Variable from ELF symbols
./scripts/stm32-debug read counter voltage --type uint

# Register using SVD
./scripts/stm32-debug read 'GPIOA->ODR' --type hex

# Dot notation avoids shell quoting issues
./scripts/stm32-debug read GPIOA.ODR GPIOA.MODER.MODER0 --type uint

# Direct address
./scripts/stm32-debug read 0x20000000 --type hex

Generate a GDB memory-read script for offline use:

./scripts/stm32-debug generate-script counter voltage

Read history:

./scripts/stm32-debug history counter --limit 10

Optional variable interpretation config:

# .stm32-debug.yaml
variables:
  test_step:
    0: "Initializing"
    100: "Complete"

4. Breakpoints And Stepping

Logical breakpoints and watchpoints are stored in .stm32-debug/session.json and reapplied to each GDB invocation.

# Breakpoint management
./scripts/stm32-debug break main.c:145
./scripts/stm32-debug break HAL_I2C_Mem_Read --condition "voltage_index==2"
./scripts/stm32-debug break --list
./scripts/stm32-debug break --delete 1

# Watchpoints
./scripts/stm32-debug watch voltage_index
./scripts/stm32-debug watch 0x20000028
./scripts/stm32-debug watch --list

# Run control
./scripts/stm32-debug restart
./scripts/stm32-debug continue
./scripts/stm32-debug step 3
./scripts/stm32-debug next 2
./scripts/stm32-debug finish

5. Inspect Program State

./scripts/stm32-debug info
./scripts/stm32-debug backtrace
./scripts/stm32-debug backtrace 5
./scripts/stm32-debug locals
./scripts/stm32-debug registers
./scripts/stm32-debug registers r0 r1 pc sp
./scripts/stm32-debug frame 1
./scripts/stm32-debug interactive

6. Monitor SWO Output

Capture printf logs via SWO pin. If the MCU is configured to a non-default clock frequency (e.g., 216MHz), you must pass the CPU frequency in Hz:

./scripts/monitor_swo.sh [cpu_frequency_hz]

Example (default 16MHz):

./scripts/monitor_swo.sh

Example (216MHz):

./scripts/monitor_swo.sh 216000000

Use a custom OpenOCD board config when needed:

OPENOCD_CONFIG=board/stm32h7x.cfg ./scripts/monitor_swo.sh 400000000

Read the log:

tail -f swo.log

7. Inspect Register Definitions

View register or field details (address, mask, fields, description) from SVD:

./scripts/read_svd.py <svd_file> <peripheral> [register] [field]

Example:

./scripts/read_svd.py STM32F746.svd RCC CR

# Inspect one field directly
./scripts/read_svd.py STM32F746.svd GPIOA MODER MODER0

8. Session Management

./scripts/stm32-debug start --elf build/firmware.elf --svd STM32F746.svd
./scripts/stm32-debug status
./scripts/stm32-debug stop

9. SVD Sources

If your target SVD is missing, common sources are:

• STM32Cube device packages from ST
• ST official MCU download pages
• CMSIS-SVD mirror: https://github.com/posborne/cmsis-svd/tree/master/data/STMicro

Troubleshooting

• OpenOCD Init Failed: Ensure no other OpenOCD instance is running (pkill openocd).
• Connection Refused: Ensure OpenOCD is running before using monitoring scripts.
• Symbol Not Found: Ensure the variable is global (not static/local) and the ELF file is up-to-date.
• GDB Error: Ensure gdb-multiarch is installed to resolve complex types like structs.
• Shell Redirect Issue: Quote targets using ->, for example 'GPIOA->ODR', or prefer dot notation such as GPIOA.ODR.

--- README.md ---

STM32 Debug Skill for AI Agents

这是一个专为 AI Agent（如基于大语言模型的编程助手）设计的 STM32 调试技能包（Skill）。它封装了常用的 STM32 固件编译、烧录、调试、寄存器查看以及变量实时监控功能，旨在让 AI 助手能够无缝、高效地协助开发者进行 STM32 嵌入式开发。

✨ 核心特性

• 一键烧录: 封装 OpenOCD 烧录流程，支持快速部署。
• 统一调试 CLI: 新增 stm32-debug 统一入口，覆盖读取、断点、单步、观察点、历史、一键调试循环和会话管理。
• 实时监控 (无停机): 利用 GDB 和 OpenOCD TCL 接口，支持在程序运行期间实时读取全局变量、结构体成员、寄存器、寄存器位域以及直接内存地址。
• 寄存器解析: 内置 read_svd.py 脚本，可直接解析 .svd 文件，根据外设、寄存器和位域名称查看地址、掩码和定义。
• 自动 OpenOCD 管理: stm32_monitor.py 在需要时会自动拉起 OpenOCD，减少手工启动和残留进程问题。
• SWO 日志捕获: 自动配置并捕获通过 SWO (Serial Wire Output) 输出的 printf 调试信息。
• 断点与单步调试: 支持断点、条件断点、观察点、继续执行、单步、调用栈、局部变量和寄存器查看。
• 开箱即用: 提供预打包好的 stm32-debug-skill.tar.gz，解压即用。

📦 包含内容

解压 stm32-debug-skill.tar.gz 后，包含以下内容：

stm32-debug-skill/
├── SKILL.md                  # AI Agent 读取的技能说明和使用指南
├── STM32F746.svd             # (示例) 芯片 SVD 文件，用于解析寄存器
└── scripts/
    ├── stm32-debug           # 统一命令入口
    ├── stm32_debug.py        # 统一 CLI 实现
    ├── flash.sh              # 固件烧录脚本
    ├── monitor_swo.sh        # SWO 日志监听脚本
    ├── read_svd.py           # SVD 解析与寄存器读取脚本
    └── stm32_monitor.py      # GDB 符号解析与内存实时监控脚本

🛠️ 环境依赖

在使用此 Skill 前，主机环境需要安装以下工具：

• arm-none-eabi-gcc (用于编译)
• openocd (用于烧录和底层通信)
• gdb-multiarch (用于解析 ELF 符号和结构体类型)
• python3 (运行监控脚本)

🚀 使用示例 (Agent 指令)

当将此 Skill 挂载到 AI Agent 后，你可以直接使用自然语言下达指令，Agent 会自动调用对应的脚本。

1. 初始化一次调试会话

# Agent 将执行：
./scripts/stm32-debug start \
  --elf build/firmware.elf \
  --svd STM32F746.svd \
  --source-root Core \
  --build-cmd "cmake --build build/Release" \
  --flash-elf build/firmware.elf

2. 读取变量、寄存器、位域、地址

# Agent 将执行：
./scripts/stm32-debug read counter "my_sensor.value" --type uint
./scripts/stm32-debug read 'GPIOA->ODR' GPIOA.MODER.MODER0 --type uint

# 或读取直接地址：
./scripts/stm32-debug read 0x20000000 --type hex

注意：带 -> 的目标在 shell 中要加引号，或者改写成 GPIOA.ODR 这样的点号形式。

3. 设置断点并单步调试

# Agent 将执行：
./scripts/stm32-debug break main.c:145
./scripts/stm32-debug break HAL_I2C_Mem_Read --condition "voltage_index==2"
./scripts/stm32-debug restart
./scripts/stm32-debug continue
./scripts/stm32-debug step 3
./scripts/stm32-debug locals
./scripts/stm32-debug backtrace
./scripts/stm32-debug registers

4. 观察点和历史

# Agent 将执行：
./scripts/stm32-debug watch voltage_index
./scripts/stm32-debug history counter --limit 10
./scripts/stm32-debug generate-script counter voltage

5. 一键调试循环

# Agent 将执行：
./scripts/stm32-debug cycle counter voltage --flash --wait 10

6. 监听 printf 日志 (SWO)

支持自定义 CPU 主频（如果芯片被配置为了非默认的 16MHz，比如 216MHz，需显式指定以保证波特率正确）：

# Agent 将执行 (默认 16MHz)：
./scripts/monitor_swo.sh

# 如果 CPU 配置为 216MHz，则 Agent 将执行：
./scripts/monitor_swo.sh 216000000

# 并在后台查看 swo.log

如果不是 stm32f7discovery，也可以通过环境变量切换 OpenOCD 配置：

OPENOCD_CONFIG=board/stm32h7x.cfg ./scripts/monitor_swo.sh 400000000

7. SVD 获取方式

当当前 Skill 未附带目标芯片的 SVD 时，推荐从以下来源获取：

• STM32Cube 设备包自带的 CMSIS 目录
• ST 官网对应系列的 STM32Cube 下载页
• CMSIS-SVD GitHub 镜像

8. 变量解释配置

可以在项目根目录放置 .stm32-debug.yaml 或 .stm32-debug.json，给关键状态变量增加可读解释：

variables:
  test_step:
    0: "Initializing"
    100: "Complete"
    99: "Failed"

之后 stm32-debug read test_step 和 stm32-debug history test_step 会附带解释文本。

📝 如何集成到你的 Agent

1. 下载 stm32-debug-skill.tar.gz。
2. 解压到你的项目或 Agent 的 skills 目录下（例如 .trae/skills/stm32-debug/）。
3. 确保 scripts/ 目录下的所有 .sh 和 .py 文件具有可执行权限 (chmod +x scripts/*)。
4. Agent 读取 SKILL.md 后即可习得这些调试能力。