OpenOCD doesn't come built into Arduino IDE, but you can add it as a tool so the IDE can use it for debugging microcontroller boards

OpenOCD is a debugger that lets you step through code running on a microcontroller, set breakpoints, and inspect variables in real time. Arduino IDE doesn't include it by default, but you can install it through the IDE's built-in tool manager. The process takes about five minutes and works on Windows, macOS, and Linux.

You'll need Arduino IDE version 1.8.13 or later. If you're using an older version, update it first from arduino.cc. You'll also need a compatible debug probe — a small hardware device that connects your computer to the microcontroller's debug pins. Common probes include ST-Link, J-Link, and CMSIS-DAP devices.

Key Takeaways

  • OpenOCD installs through Arduino IDE's Boards Manager, not as a separate download.
  • You need a debug probe (like ST-Link or CMSIS-DAP) connected between your computer and the microcontroller to use OpenOCD.
  • After installing OpenOCD through the IDE, you configure it by editing a board definition file to point to your specific probe type.
  • Not all Arduino boards support debugging — check your board's documentation to confirm it has debug pins exposed.

Installing OpenOCD through the Boards Manager

Open Arduino IDE and go to Tools > Board > Boards Manager. Search for "OpenOCD" in the search box. You should see a package called "OpenOCD" maintained by Arduino. Click it and select the latest version, then click Install.

The download is about 50 to 100 MB depending on your operating system. Once installation finishes, close the Boards Manager window. OpenOCD is now available on your system, but you still need to tell Arduino IDE which debug probe you're using.

Identifying your debug probe and connecting it

Before you configure OpenOCD, you need to know what debug probe you have. Common types include ST-Link (used with STM32 boards), J-Link (Segger), CMSIS-DAP (generic ARM debuggers), and Atmel-ICE. Check your probe's documentation or the label on the device itself.

Connect the probe to your computer via USB. Then connect the probe's debug pins to your microcontroller board. Most boards have a standard pinout: SWDIO (data), SWCLK (clock), GND (ground), and sometimes 3.3V power. Consult your board's pinout diagram to locate these pins. If your board doesn't expose debug pins, you cannot use OpenOCD with it.

Configuring OpenOCD for your specific probe

OpenOCD needs a configuration file that tells it which probe you're using and how to connect to your board. Arduino IDE stores board definitions in a folder on your computer. On Windows, this is usually Documents\Arduino\hardware. On macOS, it's ~/Documents/Arduino/hardware. On Linux, it's ~/.arduino15/packages.

Navigate to the folder for your board type. For example, if you're using an STM32 board, look for a folder named something like STM32. Inside, find the board's JSON or properties file. Open it with a text editor (Notepad on Windows, TextEdit on macOS set to plain text, or any text editor on Linux).

Look for a section that mentions "openocd" or "debugger". You'll see a line that specifies the probe type, often something like interface/stlink.cfg for ST-Link or interface/cmsis-dap.cfg for CMSIS-DAP probes. Make sure this matches your actual probe. Save the file and restart Arduino IDE.

Verifying OpenOCD is working

Plug in your microcontroller board via USB and connect your debug probe. In Arduino IDE, go to Tools and look for a Debugger option. Select your debug probe from the dropdown. Upload a sketch to your board using the normal upload button.

Once the sketch is on the board, go to Debug > Start Debugging (or press Ctrl+Alt+D on Windows, Cmd+Shift+D on macOS). If OpenOCD is configured correctly, the IDE will connect to the board and pause execution. You'll see the Variables panel populate with your program's current state. If you see an error message, check that your probe is connected and that the configuration file points to the correct probe type.

Common setup problems and fixes

If debugging won't start, the most common cause is a mismatch between the probe type in your configuration file and the actual probe you're using. Double-check the board definition file and make sure the interface name matches your probe's type.

On Windows, you may need to install USB drivers for your probe. ST-Link probes often require the ST-Link driver from st.com. CMSIS-DAP probes usually work without extra drivers, but check the probe manufacturer's website if the IDE doesn't detect it.

If the IDE says "OpenOCD not found", the installation didn't complete. Go back to Boards Manager, uninstall OpenOCD, and reinstall it. Make sure you have at least 200 MB of free disk space before installing.

What you can do once OpenOCD is set up

With OpenOCD running, you can set breakpoints by clicking the line number in your sketch. When execution hits a breakpoint, the program pauses and you can inspect variables, step through code line by line, and watch memory change in real time. This is much faster than debugging with Serial.print() statements.

You can also set conditional breakpoints (pause only when a variable equals a specific value) and watch expressions (monitor a variable's value as the program runs). These tools are especially useful when tracking down bugs in interrupt handlers or timing-sensitive code.

Frequently Asked Questions

Do I need a special microcontroller board to use OpenOCD?

Your board needs to have debug pins exposed and a compatible processor. Most STM32, SAMD, and nRF boards support debugging. Arduino Uno and Nano do not. Check your board's documentation or look for a "Debug" or "SWD" label on the pinout diagram.

Can I use OpenOCD with Arduino boards like the Uno?

No. The Uno and Nano use ATmega processors that don't have standard debug interfaces. You'd need a different board, such as an STM32 Nucleo or Arduino MKR board, to use OpenOCD.

What's the difference between OpenOCD and the Arduino debugger?

OpenOCD is the underlying tool that Arduino IDE uses for debugging. When you use the Debug menu in the IDE, it's actually running OpenOCD in the background. Installing it through Boards Manager just makes sure the IDE has access to it.

Do I need to reinstall OpenOCD when I update Arduino IDE?

Usually not. OpenOCD is stored separately from the IDE itself. However, if you update to a major new version of the IDE, it's a good idea to reinstall OpenOCD through Boards Manager to make sure everything is compatible.

Can I use OpenOCD with boards from other manufacturers?

Yes, as long as the board has a compatible processor and exposed debug pins. You may need to create or edit a custom board definition file to tell OpenOCD which probe and processor to use. This requires editing JSON or properties files and is more advanced than the standard setup.