Embedded Debugger
Use the local embedded-debugger-mcp binary as the source of truth. Prefer CLI
checks first, then MCP tools when an MCP client is available.
Entry Decision
- If the user has an MCP client configured, start or verify the server:
embedded-debugger-mcp serve
- If the user wants no MCP install, use CLI-first mode:
embedded-debugger-mcp doctor, embedded-debugger-mcp probes list, and
embedded-debugger-mcp skill print-prompt.
- If hardware access is required, confirm the probe and target are connected
before destructive actions such as flash erase or program.
CLI Workflow
Run these in order and report the exact outcome:
embedded-debugger-mcp doctor
embedded-debugger-mcp probes list
embedded-debugger-mcp config show
Use JSON for automation:
embedded-debugger-mcp doctor --json
embedded-debugger-mcp probes list --json
Backends
One tool set runs over two interchangeable engines, chosen at connect:
backend: "probe-rs" (default) — native probe-rs; supports flash and RTT.
backend: "openocd" (experimental) — talks to an already-running openocd
over its GDB port via openocd_address (default 127.0.0.1:3333). Use for
chips probe-rs does not cover well (e.g. Xtensa ESP32 via openocd-esp32).
Memory access and halt/run/step/reset are validated on real ESP32-S3; flash
and RTT are not available on this backend. Register reads currently use ARM
gdb register numbers, so PC/SP are wrong on Xtensa (known limitation).
diagnose_fault and unwind_exception are Cortex-M specific and do not
apply to Xtensa targets.
- Start openocd with
gdb_memory_map disable, otherwise it probes flash on
the GDB connect, fails, and REJECTS the connection. Example:
openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable".
The AI uses the same tools regardless of backend; only connect differs.
MCP Workflow
Use MCP tools for session-based operations:
list_probes
connect (add backend: "openocd" and openocd_address to use OpenOCD)
- Read-only checks such as
probe_info, get_status, and read_memory
- On a crash or halt, call
diagnose_fault: it reads the Cortex-M SCB fault
registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR and returns a
compact structured evidence bundle in one call. Halt the target first for
meaningful values; reason over the set fault bits yourself. Then call
unwind_exception with elf_path to map the crash to a source line
(full DWARF backtrace on probe-rs; faulting PC/LR on OpenOCD).
- Mutating operations only after the user confirms target, file path, and risk:
write_memory, flash_erase, flash_program, run_firmware (probe-rs)
- RTT operations after firmware is running:
rtt_attach, rtt_channels,
rtt_read, rtt_write, rtt_detach (probe-rs)
disconnect
Fetch authoritative info yourself
You are a capable model: prefer fetching ground truth over relying on memorized
or hardcoded chip data. This skill points you to sources; it does not embed
register tables. In order of authority:
- The target itself (runtime, most authoritative for this exact chip):
registers are self-described by the GDB target description; memory is read
with
read_memory; core identity from CPUID / the connected target.
- The firmware ELF (what is actually running): symbols and source lines come
from DWARF — use
unwind_exception (pass elf_path) to map addresses to
file:line.
- The chip datasheet / reference manual (external, per-chip): for a peripheral
or fault register, find the peripheral's base in the memory-map chapter, add
the register offset, then
read_memory. Search the vendor document for the
exact value; do not guess addresses from memory. CMSIS-SVD files are a
machine-readable source for register maps.
- ARM Cortex-M architecture registers (SCB fault regs, CPUID) are fixed by the
ARM architecture and identical across vendors —
diagnose_fault reads them.
They do not exist on non-Cortex-M targets (e.g. Xtensa ESP32).
Do not hardcode or invent register/peripheral addresses. If a value is not
recoverable from the target, the ELF, or a cited datasheet, say so.
Know your versions
Behavior and target support depend on tool versions — check them before
concluding something is unsupported or broken:
- probe-rs version determines which chips and architectures are supported
(e.g. Xtensa support is comparatively new). Check
embedded-debugger-mcp doctor.
- OpenOCD version and fork matter: the Espressif fork (openocd-esp32) is needed
for Xtensa ESP32, and some targets need flags like
gdb_memory_map disable.
Check openocd --version.
- Probe firmware (ST-Link / J-Link) can affect connectivity;
probes list
reports the connected probe.
Safety Rules
- Treat flash erase, flash program, memory write, reset, run, and RTT write as
mutating hardware operations.
- Prefer read-only discovery before mutation.
- Respect project configuration limits for file paths, file sizes, memory
ranges, and flash erase permissions.
- Do not claim hardware success from command text alone; cite the command or MCP
tool result that produced the evidence.
Prompt Reference
For a reusable CLI+Skill prompt, read
references/default-prompt.md.
1---2name: embedded-debugger3description: Embedded hardware debugging workflow for probe-rs targets using embedded-debugger-mcp. Use when Codex or Claude Code needs to inspect debug probes, validate embedded debugger setup, start the MCP server, guide a user through ARM Cortex-M/RISC-V flashing/debugging/RTT workflows, or operate without installing an MCP client by using the CLI plus prompts.4metadata:5 source: https://skillmd.com/skills/adancurusul-embedded-debugger-mcp/embedded-debugger6---78# Embedded Debugger910Use the local `embedded-debugger-mcp` binary as the source of truth. Prefer CLI11checks first, then MCP tools when an MCP client is available.1213## Entry Decision14151. If the user has an MCP client configured, start or verify the server:16 `embedded-debugger-mcp serve`172. If the user wants no MCP install, use CLI-first mode:18 `embedded-debugger-mcp doctor`, `embedded-debugger-mcp probes list`, and19 `embedded-debugger-mcp skill print-prompt`.203. If hardware access is required, confirm the probe and target are connected21 before destructive actions such as flash erase or program.2223## CLI Workflow2425Run these in order and report the exact outcome:2627```bash28embedded-debugger-mcp doctor29embedded-debugger-mcp probes list30embedded-debugger-mcp config show31```3233Use JSON for automation:3435```bash36embedded-debugger-mcp doctor --json37embedded-debugger-mcp probes list --json38```3940## Backends4142One tool set runs over two interchangeable engines, chosen at `connect`:4344- `backend: "probe-rs"` (default) — native probe-rs; supports flash and RTT.45- `backend: "openocd"` (experimental) — talks to an already-running `openocd`46 over its GDB port via `openocd_address` (default `127.0.0.1:3333`). Use for47 chips probe-rs does not cover well (e.g. Xtensa ESP32 via openocd-esp32).48 Memory access and halt/run/step/reset are validated on real ESP32-S3; flash49 and RTT are not available on this backend. Register reads currently use ARM50 gdb register numbers, so PC/SP are wrong on Xtensa (known limitation).51 `diagnose_fault` and `unwind_exception` are Cortex-M specific and do not52 apply to Xtensa targets.53 - Start openocd with `gdb_memory_map disable`, otherwise it probes flash on54 the GDB connect, fails, and REJECTS the connection. Example:55 `openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable"`.5657The AI uses the same tools regardless of backend; only `connect` differs.5859## MCP Workflow6061Use MCP tools for session-based operations:62631. `list_probes`642. `connect` (add `backend: "openocd"` and `openocd_address` to use OpenOCD)653. Read-only checks such as `probe_info`, `get_status`, and `read_memory`664. On a crash or halt, call `diagnose_fault`: it reads the Cortex-M SCB fault67 registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR and returns a68 compact structured evidence bundle in one call. Halt the target first for69 meaningful values; reason over the set fault bits yourself. Then call70 `unwind_exception` with `elf_path` to map the crash to a source line71 (full DWARF backtrace on probe-rs; faulting PC/LR on OpenOCD).725. Mutating operations only after the user confirms target, file path, and risk:73 `write_memory`, `flash_erase`, `flash_program`, `run_firmware` (probe-rs)746. RTT operations after firmware is running: `rtt_attach`, `rtt_channels`,75 `rtt_read`, `rtt_write`, `rtt_detach` (probe-rs)767. `disconnect`7778## Fetch authoritative info yourself7980You are a capable model: prefer fetching ground truth over relying on memorized81or hardcoded chip data. This skill points you to sources; it does not embed82register tables. In order of authority:83841. The target itself (runtime, most authoritative for this exact chip):85 registers are self-described by the GDB target description; memory is read86 with `read_memory`; core identity from CPUID / the connected target.872. The firmware ELF (what is actually running): symbols and source lines come88 from DWARF — use `unwind_exception` (pass `elf_path`) to map addresses to89 `file:line`.903. The chip datasheet / reference manual (external, per-chip): for a peripheral91 or fault register, find the peripheral's base in the memory-map chapter, add92 the register offset, then `read_memory`. Search the vendor document for the93 exact value; do not guess addresses from memory. CMSIS-SVD files are a94 machine-readable source for register maps.954. ARM Cortex-M architecture registers (SCB fault regs, CPUID) are fixed by the96 ARM architecture and identical across vendors — `diagnose_fault` reads them.97 They do not exist on non-Cortex-M targets (e.g. Xtensa ESP32).9899Do not hardcode or invent register/peripheral addresses. If a value is not100recoverable from the target, the ELF, or a cited datasheet, say so.101102## Know your versions103104Behavior and target support depend on tool versions — check them before105concluding something is unsupported or broken:106107- probe-rs version determines which chips and architectures are supported108 (e.g. Xtensa support is comparatively new). Check `embedded-debugger-mcp doctor`.109- OpenOCD version and fork matter: the Espressif fork (openocd-esp32) is needed110 for Xtensa ESP32, and some targets need flags like `gdb_memory_map disable`.111 Check `openocd --version`.112- Probe firmware (ST-Link / J-Link) can affect connectivity; `probes list`113 reports the connected probe.114115## Safety Rules116117- Treat flash erase, flash program, memory write, reset, run, and RTT write as118 mutating hardware operations.119- Prefer read-only discovery before mutation.120- Respect project configuration limits for file paths, file sizes, memory121 ranges, and flash erase permissions.122- Do not claim hardware success from command text alone; cite the command or MCP123 tool result that produced the evidence.124125## Prompt Reference126127For a reusable CLI+Skill prompt, read128`references/default-prompt.md`.