Skip to main content
Use OpenOCD with a supported debug adapter and target configuration, including supported ST-Link and CMSIS-DAP setups. Compatibility depends on the installed OpenOCD build and the exact board wiring and MCU.

​
Prepare

  1. Connect and power the target and debug adapter. Install any host drivers or USB permissions required by that adapter.
  2. Identify the OpenOCD interface and target configurations for the board. Embedder uses interface names such as stlink or cmsis-dap and target names such as stm32f4x, without the interface/ or target/ prefix and .cfg suffix.
  3. Build the firmware ELF with symbols. For attachment, use the ELF matching the firmware already on the board.
  4. Run /debug and ask Embedder to check OpenOCD and GDB readiness. Embedder can provision its managed tools where supported.
Record Debug Interface = st-link or Debug Interface = cmsis-dap in EMBEDDER.md, along with the exact MCU and verified debug command. When automatic target detection is uncertain, provide the target configuration explicitly. To use a particular OpenOCD build, set EMBEDDER_OPENOCD_PATH to its executable path or a command available on PATH in the environment launching Embedder. An invalid override can fall back to managed OpenOCD; check the detected executable before relying on a custom build.

​
Connect and inspect

Replace build/app.elf with your build output. The normal connection programs the ELF and attempts to stop at main. From there, request breakpoints, stepping, variables, registers, or memory using the common debugger workflow. For a repeatable check, a hardware script can use the supported connection helper. This example applies only to a board verified to use ST-Link and the installed stm32f4x target configuration:
Save the script under .embedder/hardware/, replace the artifact and configuration values, and ask Embedder to run it. This example programs the target. A debugger connection opened by the script is disconnected during script cleanup.

​
Preserve an existing run

Request attach-only to load symbols without programming or running to main. Add no-halt when execution should continue. The equivalent script connection options are attach=True, no_halt=True, and run_to_main=False. These options do not make an arbitrary OpenOCD configuration nonintrusive. Startup commands can still affect the target. In particular, 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 does not require SWO output.

​
Troubleshoot

  • No target configuration matches: verify the MCU and inspect the target files in the selected OpenOCD installation. Do not substitute a nearby family.
  • Adapter or USB access fails: check drivers, device permissions, wiring, target power, and competing applications.
  • Transport mismatch: confirm whether the target requires SWD or JTAG and that the interface/target configuration pair supports it.
  • Managed setup fails: use the reported installation error to repair the host setup, or configure a verified OpenOCD executable.
  • Probe busy after switching tools: stop the previous debugger or monitor before retrying. Starting OpenOCD can take over an existing process using the same OpenOCD executable.
Last modified on September 12, 2026