How to install the OpenOCD binaries?
OpenOCD is an open source project hosted on SourceForge, and project maintainers insist that all end-users should compile it from the latest version of the source code available from their repository. There are no special stable branches or tags and there are no clear release dates for future versions. On Windows you need to install MSYS2 and use the appropriate package build procedure.
If you are like us and consider that professional solutions should include stable, hassle free binary distributions, you might be interested to know that a custom packed version of OpenOCD, based on the latest public version (0.9.0) was added to GNU MCU Eclipse, as GNU MCU Eclipse OpenOCD. It can be downloaded from the GitHub Releases page.
So, if you are not interested in building from sources, and appreciate a better integration with the Eclipse plug-in, please feel free to use the GNU MCU Eclipse OpenOCD binaries, and preferably install them in the default locations.
Warning: OpenOCD is a very complex project, capable of working with many JTAG probes, but support for them must be explicitly included at build time, so be sure that support for your JTAG probe was included in the binaries you plan to use. The GNU MCU Eclipse OpenOCD includes support for most existing probes.
If the only reason to run OpenOCD is to use the ST-LINK on-board programmer on STM Discovery or Nucleo boards, then, thanks to SEGGER, a better solution exists: it is possible to upgrade the on-board programmer firmware to behave like a J-Link lite, and then use the GNU MCU Eclipse J-Link plug-in. The conversion is reversible, you can return the board to ST-LINK at any time.
Please follow the instructions on Converting ST-LINK on-board into a J-Link.
If you are using the GNU MCU Eclipse OpenOCD, the documentation is part of the installed package.
For user convenience, the Windows versions of GNU MCU Eclipse OpenOCD are packed as Windows setup wizards. Go to the GitHub Releases page and download the latest version named like:
-win64- file for Windows x64 machines and the
-win32- file for Windows x32 machines.
Run the setup as usual.
It is recommended to keep the default install location:
The default install location is:
C:\Program Files\GNU MCU Eclipse\OpenOCD\*
The result is a structure like:
To check if OpenOCD starts, use the following command:
C:>"C:\Program Files\GNU MCU Eclipse\OpenOCD\0.8.0-201503201840\bin\openocd" --version GNU MCU Eclipse 64-bits Open On-Chip Debugger 0.8.0-00036 (2015-03-20-18:40)
As usual on Windows, mastering drivers is a challenge and OpenOCD is no exceptions, so don’t be surprised to encounter many incompatible drivers for various JTAG probes. The OpenOCD distribution includes some libusb drivers, and recommends to run the
zadig.exe tool to activate them. Although this manoeuvre will make OpenOCD happy, it will most probably ruin other USB drivers you might have installed. Our strong recommendation is to NOT do this, and instead use the manufacturer drivers, when compatible with OpenOCD.
One example of compatible drivers are the ST-LINK/V2 USB drivers, from ST, available as part number STSW-LINK009. Download the
stsw-link009.zip archive, extract its content to a separate folder, and run the
dpinst_x86.exe) with administrative privileges.
As for most Windows drivers, to complete the installation, a restart usually helps.
Connect the ST-LINK/v2 or the DISCOVERY board and check in Control Panel → System → Device Manager if the JTAG is operational.
For other probes follow the manufacturer instructions.
Note 1: All Windows tests were performed on Windows 7. If, for any reasons, you still use the venerable Windows XP, some differences may be observed in the USB subsystem; to stay on the safe side, try to always use original manufacturer drivers.
Note 2: OpenOCD v0.7.0 does not work with the current J-Link drivers, so on Windows it is not possible to use OpenOCD with J-Link; use the SEGGER supplied software instead.
For user convenience, the macOS version of GNU MCU Eclipse OpenOCD is packed as an macOS install package. Go to the GitHub Releases page and download the latest version named like:
As the name implies, this is an macOS package, that can be installed on any recent 64-bits macOS.
Run the install as usual.
The package is installed in:
/Applications/GNU MCU Eclipse/OpenOCD/*
To check if OpenOCD starts, use:
$ /Applications/GNU\ ARM\ Eclipse/OpenOCD/0.8.0-201501181257/bin/openocd --version GNU MCU Eclipse 64-bits Open On-Chip Debugger 0.8.0-00036 (2015-01-18-12:57)
The GNU/Linux versions of GNU MCU Eclipse OpenOCD are packed as TGZ archives. Go to the GitHub Releases page and download the latest version named like:
As the name implies, these are Debian
tar.gz archives, but can be executed on most recent GNU/Linux distributions (they were tested on Debian, Ubuntu, Manjaro, SuSE and Fedora). Select the
-debian64- file for 64-bits machines and the
-debian32- file for 32-bits machines.
In case you use an older distribution and encounter difficulties to run GNU MCU Eclipse OpenOCD, you can also try to build it from sources on your machine. As a last resort, if your distribution includes an OpenOCD package, you can install it using the specific tools.
To install this package, unpack the archive and copy it to
$ sudo mkdir -p /opt/gnuarmeclipse $ cd /opt/gnuarmeclipse $ sudo tar xvf ~/Downloads/gnuarmeclipse-openocd-debian64-0.10.0-201510281129-dev.tgz
Note: although perfectly possible to install it in any location, it is recommended to use this location, since by default the plug-in searches for the executable in this location.
To check if OpenOCD starts and is recent, use:
$ /opt/gnuarmeclipse/openocd/0.10.0-201510281129-dev/bin/openocd --version GNU MCU Eclipse 64-bits Open On-Chip Debugger 0.10.0-dev-00141-g09aeb96-dirty (2015-10-28-11:56)
For the JTAG probes implemented as USB devices (actually most of them), the last installation step on GNU/Linux is to configure the UDEV subsystem. OpenOCD provides an UDEV rules file defining all the supported IDs; to install it, just copy the file to
/etc/udev/rules.d and eventually notify the daemon:
$ sudo cp /opt/gnuarmeclipse/openocd/0.10.0-201510281129-dev/contrib/99-openocd.rules \ /etc/udev/rules.d/ $ sudo udevadm control --reload-rules
Note: If you previously installed the J-Link binaries, the USB IDs were already added to UDEV. The above OpenOCD rules file also defines the J-Link ID. Apparently UDEV does not complain; if you encounter problems, just comment out the definition in the OpenOCD file.
USB access rights
On some GNU/Linux distributions, the UDEV definitions are not enough, or are not effective, and when trying to access the JTAG probe, an error is issued:
libusb_open failed: LIBUSB_ERROR_ACCESS
If this happens, first try to start openocd with sudo; if this works, for regular work you also need to grant your user permission to use the USB.
For example, on Ubuntu 15.10 you need to issue something like:
sudo usermod -aG plugdev $USER
Then relogin or restart.
If you still have problems, check your distribution documentation and when you have a functional solution post it on the project forum.
To test if OpenOCD is able to connect to a specific board, you generally need to select the interface and the processor. As a shortcut, for some well known boards, there are ready made configuration files to set both the interface and the processor. For example, on macOS, to test a connection via ST/LINK v2 to the STM32F4DISCOERY board, you can use the sample below:
$ /Applications/GNU\ ARM\ Eclipse/OpenOCD/0.8.0-201501181257/bin/openocd \ -f board/stm32f4discovery.cfg GNU MCU Eclipse 64-bits Open On-Chip Debugger 0.8.0-00036-gb7535dd (2015-01-18-12:57) Licensed under GNU GPL v2 For bug reports, read http://openocd.sourceforge.net/doc/doxygen/bugs.html srst_only separate srst_nogate srst_open_drain connect_deassert_srst Info : This adapter doesn't support configurable speed Info : STLINK v2 JTAG v14 API v2 SWIM v0 VID 0x0483 PID 0x3748 Info : using stlink api v2 Info : Target voltage: 2.905638 Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints ^C
OpenOCD Debugging plug-ins
The OpenOCD debugging plug-ins are not included in these packages, and need to be installed as usual. Just be sure that the GNU ARM C/C++ OpenOCD Debugging plug-ins are selected.
Update OpenOCD path
Right after installing OpenOCD, or updating to a new version, it is necessary to inform Eclipse where the binaries were installed. If OpenOCD was installed in the default location, Eclipse has a mechanism to autodetect the most recent version, but this mechanism sometimes fails, and manual path setting is necessary.
To set the path, first exit Eclipse, and start it again, to allow the autodetect mechanism to give it a try:
in the Eclipse menu, go to (Window →) Preferences → Run/Debug → OpenOCD
click the Restore Defaults button
For more details please refer to the OpenOCD plug-in page, where the entire procedure is explained.