STM32 Debug Assistant
AI-powered debugging assistant for STM32 microcontrollers. Reads live MCU state via OpenOCD and uses Claude to analyze crashes, HardFaults, and peripheral configuration — all inside VS Code.
Features
- HardFault analysis — decodes CFSR/HFSR bits, reads exception stack frame, identifies fault type, faulting instruction, and root cause
- Peripheral inspection — reads any peripheral registers with SVD-driven field decoding (USART, SPI, I2C, GPIO, RCC, TIM, etc.) without halting the core
- CPU register snapshot — full view of r0–r12, SP, LR, PC, xPSR, MSP, PSP, PRIMASK, BASEPRI, FAULTMASK
- Memory & disassembly — read arbitrary memory addresses and disassemble instructions at any location
- Symbol resolution — resolve code addresses to function names, source files, and line numbers via ELF debug info
- Source code search — AI greps your firmware source to understand which peripherals are actually used before diagnosing issues
- Interactive chat — ask questions about MCU state in natural language, AI calls tools automatically to gather data
Supports Cortex-M0/M0+/M3/M4/M7 cores.
Demo
See the extension in action: Watch on YouTube
Fault Context panel
AI Analysis
Quick Start
1. Start OpenOCD
Connect your board and start OpenOCD:
# STM32F4 + ST-Link
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
# STM32F1 + J-Link
openocd -f interface/jlink.cfg -f target/stm32f1x.cfg
2. Open the panel
Ctrl+Shift+P → STM32 Debug: Open Panel
Click the gear icon and fill in:
| Field |
Example |
Notes |
| MCU Name |
STM32F411RET6 |
Helps AI understand the specific chip |
| SVD File |
STM32F411.svd |
Auto-downloaded or from your workspace |
| ELF File |
build/firmware.elf |
Your firmware compiled with -g |
| OpenOCD Port |
6666 |
Default OpenOCD TCL port |
Or click Auto-detect — the extension will scan your workspace for SVD/ELF files, detect OpenOCD port, and offer to download the SVD from GitHub if needed.
4. Enter API key
On the first message the extension will ask for your Anthropic API key. It is stored securely in VS Code's secret storage.
5. Ask anything
Type a question in the chat:
- "How is TIM1 configured? What is the clock source?"
- "Which GPIO pins are used in the project?"
- "HSE or HSI — what's the system clock source?"
- "Analyze the current HardFault"
- "How is USART2 set up? What's the baud rate?"
The AI automatically reads registers, searches your source code, and provides analysis.
The AI has access to tools that it calls automatically based on your question:
| Tool |
Description |
read_peripheral |
Read all registers of a peripheral via DAP (no halt) |
read_cpu_registers |
Read core registers r0–r12, SP, LR, PC, xPSR |
read_fault_context |
Read HFSR, CFSR, MMFAR, BFAR + exception stack frame |
list_peripherals |
List all peripherals from the SVD file |
read_memory |
Read memory at any address via DAP (no halt) |
disassemble |
Disassemble instructions at an address |
resolve_address |
Resolve address to symbol + source file:line |
search_source |
Grep firmware source with regex |
list_source_files |
Show project file tree |
Requirements
| Requirement |
Notes |
| OpenOCD |
Connects to the target MCU over SWD/JTAG |
| Debug probe |
ST-Link, J-Link, or CMSIS-DAP |
| SVD file |
Peripheral register definitions (auto-download available) |
| ELF file |
Firmware compiled with debug symbols (-g) |
| Anthropic API key |
For Claude AI analysis |
Optional: arm-none-eabi-addr2line for precise source file:line resolution from DWARF debug info.
Tips
- Peripheral registers can be read while firmware is running — the extension uses DAP bus access (no halt)
- CPU registers and fault context require a brief halt — the extension halts, reads, and resumes automatically
- SVD files are auto-downloaded from cmsis-svd-data on GitHub
- All AI interactions are logged to
.stm32-debug-log.txt in your workspace root
Troubleshooting
| Problem |
Solution |
| Cannot connect to OpenOCD |
Make sure OpenOCD is running and the port matches (default 6666) |
| Peripheral reads show "read failed" |
Peripheral clock is probably disabled — normal for unused peripherals |
| No ELF / No SVD configured |
Set the file paths in settings or use Auto-detect |
| AI gives wrong analysis |
Use "Reset AI Context" in settings and ask again with a more specific question |
