embedded-debugger

name	embedded-debugger
description	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.

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

1. If the user has an MCP client configured, start or verify the server: embedded-debugger-mcp serve
2. 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.
3. 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:

1. list_probes
2. connect (add backend: "openocd" and openocd_address to use OpenOCD)
3. Read-only checks such as probe_info, get_status, and read_memory
4. 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).
5. Mutating operations only after the user confirms target, file path, and risk: write_memory, flash_erase, flash_program, run_firmware (probe-rs)
6. RTT operations after firmware is running: rtt_attach, rtt_channels, rtt_read, rtt_write, rtt_detach (probe-rs)
7. 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:

1. 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.
2. 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.
3. 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.
4. 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.