OpenOCD debugging

Use OpenOCD to debug with an ST-Link, a CMSIS-DAP probe, or another adapter that OpenOCD supports. Compatibility depends on the OpenOCD build, the exact MCU, and the board wiring.

What you need

Component	Who provides it
Debug adapter drivers and USB permissions	You install them on the machine connected to the board.
OpenOCD	Embedder uses an OpenOCD you’ve installed. If it finds none, it downloads its own copy on Windows x64, macOS, and Linux x64 or Arm64.
GDB client	Embedder downloads its own on the same hosts. On Linux it needs glibc 2.28 or later.

Embedder looks for OpenOCD in this order:

Embedder’s own copy, if it has already downloaded one.
openocd on PATH, or in a common install folder:
Host Folders searched
macOS /opt/homebrew/bin, /usr/local/bin, /usr/bin
Linux /usr/local/bin, /usr/bin, /bin
Windows C:\Program Files\OpenOCD\bin, C:\Program Files (x86)\OpenOCD\bin
A new download of Embedder’s own copy. This starts in the background when you open a project and no OpenOCD is found, or when a debug session needs one.

Host	Folders searched
macOS	`/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`
Linux	`/usr/local/bin`, `/usr/bin`, `/bin`
Windows	`C:\Program Files\OpenOCD\bin`, `C:\Program Files (x86)\OpenOCD\bin`

Because Embedder’s copy comes first once it’s downloaded, an OpenOCD you install afterward isn’t used. To use your own build, install it before Embedder downloads its copy, and ask Embedder which OpenOCD it detected before you rely on it.

Prepare

Connect and power the target and debug adapter. Install any drivers or USB permissions the adapter needs.
Identify the OpenOCD interface and target configurations for the board (see the table below).
Build the firmware ELF with symbols. To attach, use the ELF that matches the firmware on the board.
Run /debug and ask Embedder to check OpenOCD and GDB readiness.

Setting	Examples	Notes
Interface	`stlink`, `cmsis-dap`, `jlink`	A file under `interface/` in your OpenOCD installation, without the folder or `.cfg`
Target	`stm32f4x`, `nrf52`	A file under `target/`, without the folder or `.cfg`. Embedder picks it from the project’s MCU when it recognizes the part.
Transport	SWD	Embedder selects SWD first, and lets the configuration choose when the target requires JTAG.

In EMBEDDER.md, set Debug Interface = st-link or Debug Interface = cmsis-dap, along with the exact MCU and verified debug command. Without an interface setting, Embedder assumes ST-Link. When the target can’t be detected reliably, give the target configuration explicitly.

Connect and inspect

Use OpenOCD with the interface and target configuration verified for this
board. Program build/app.elf, run to main, and show the current frame and PC.
Confirm the configuration names before starting.

Replace build/app.elf with your build output. Embedder asks you to approve before it connects, unless your approval settings already allow it. A normal connection programs the ELF and tries to stop at main. From there, ask for breakpoints, stepping, variables, registers, or memory, as described in GDB debugging.

Script the connection

For a repeatable check, a hardware script can open the connection itself. This example applies only to a board verified to use ST-Link and the stm32f4x target configuration:

gdb.openocd_connect(
    elf="build/app.elf",
    interface="stlink",
    target="stm32f4x",
    run_to_main=True,
)
print(gdb.stack())
print(gdb.read_registers())

Save the script under .embedder/hardware/, replace the artifact and configuration values, and ask Embedder to run it. This example programs the target. The debugger connection closes when the script ends.

Option	Default	Effect
`elf`	Required	Firmware ELF with symbols
`target`	Required unless you give `mcu`	OpenOCD target configuration name
`mcu`	None	MCU part number Embedder uses to choose the target
`interface`	From `EMBEDDER.md`, otherwise `stlink`	OpenOCD interface configuration name
`run_to_main`	`True`	Run to `main` after programming
`attach`	`False`	Load symbols only, without programming
`no_halt`	`False`	Don’t request a halt when connecting

Preserve an existing run

Ask for attach-only to load symbols without programming or running to main. Add no-halt when execution should continue. In a script, use attach=True and no_halt=True. These options don’t make every OpenOCD configuration nonintrusive. Startup commands in the configuration can still affect the target. No-halt without attach-only still programs the ELF, then resets and halts the target. Read the attachment precautions before investigating a live fault.

Observe output

Use ITM/SWO when the MCU, probe, wiring, and firmware support it. Supply the correct CPU and SWO frequencies. Ordinary GDB debugging doesn’t need SWO.

Flash a bridge board

OpenOCD also programs boards on a remote hardware bridge that have an OpenOCD target and interface but no chip name. Install OpenOCD on the bridge host, then see Flash through a bridge.

Troubleshoot

No target configuration matches: verify the MCU and check the target files in the OpenOCD installation in use. Don’t substitute a nearby family.
No target could be determined: add the platform to the project, or give the target configuration name.
Adapter or USB access fails: check drivers, device permissions, wiring, target power, and competing applications.
Transport mismatch: confirm whether the target needs SWD or JTAG and that the interface and target configurations support it.
Download of Embedder’s OpenOCD fails, or your host isn’t supported: use the reported error to fix the network or host setup, or install OpenOCD yourself, for example with brew install openocd or apt install openocd.
Port already in use: another debug server is running. Stop it, then retry.
Probe busy after switching tools: stop the previous debugger or monitor before retrying. Starting OpenOCD closes other OpenOCD processes that use the same executable.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

OpenOCD debugging

What you need

Prepare

Connect and inspect

Script the connection

Preserve an existing run

Observe output

Flash a bridge board

Troubleshoot

​What you need

​Prepare

​Connect and inspect

​Script the connection

​Preserve an existing run

​Observe output

​Flash a bridge board

​Troubleshoot

What you need

Prepare

Connect and inspect

Script the connection

Preserve an existing run

Observe output

Flash a bridge board

Troubleshoot