The recommended method is via xpm.

Overview

The xPack OpenOCD can be installed automatically, via xpm (the recommended method), or manually, by downloading and unpacking one of the portable archives.

Easy install

The easiest way to install OpenOCD is by using the binary xPack, available as @xpack-dev-tools/openocd from the npmjs.com registry.

Prerequisites

The only requirement is a recent xpm, which is a portable Node.js command line application. To install it, follow the instructions from the xpm install page.

Install

With xpm available, installing the latest version of the package is quite easy:

$ xpm install --global @xpack-dev-tools/openocd@latest

This command will always install the latest available version, in the central xPacks repository, which is a platform dependent folder (check the output of the xpm command or the actual folder used on your platform).

xPacks aware tools, like the Eclipse Embedded CDT plug-ins automatically identify binaries installed with xpm and provide a convenient method to manage paths.

Uninstall

To remove the installed xPack, the command is similar:

$ xpm uninstall --global @xpack-dev-tools/openocd

(Note: not yet implemented. As a temporary workaround, simply remove the xPacks/@xpack-dev-tools/openocd folder, or one of the versioned subfolders.)

Manual install

For all platforms, the xPack OpenOCD binaries are released as portable archives that can be installed in any location.

The archives can be downloaded from the GitHub Releases page.

Download

The Windows versions of xPack OpenOCD are packed as ZIP files. Download the latest version named like:

  • xpack-openocd-0.10.0-13-win32-x64.zip
  • xpack-openocd-0.10.0-13-win32-x32.zip

Select the -x64 file for 64-bit Windows machines and the -x32 file for 32-bit Windows machines.

Unpack

Unpack the archive and copy it into the %userprofile%\AppData\Roaming\xPacks\openocd (for example C:\Users\ilg\AppData\Roaming\xPacks\openocd) folder; according to Microsoft, AppData\Roaming is the recommended location for installing user specific packages.

The result is a structure like:

The OpenOCD folders structure

To check if OpenOCD starts, use the following command:

C:\Users\ilg>C:\Users\ilg\AppData\Roaming\xPacks\openocd\xpack-openocd-0.10.0-13\bin\openocd.exe --version
xPack OpenOCD, 64-bit Open On-Chip Debugger 0.10.0+dev (2019-07-17-15:21)

Drivers

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.

Zadig

The OpenOCD distribution includes some libusb drivers, and recommends to run the zadig.exe tool to activate them.

For example ARM-USB-OCD from Olimex, after installing the vendor drivers, asks to install Zadig and convert the vendor drivers to WinUSB drivers.

ST-LINK/V2

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 into a separate folder, and run the dpinst_amd64.exe (or 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.

ST-LINK Windows device

For other probes follow the manufacturer instructions.

Download

The macOS version of xPack OpenOCD is packed as a TGZ archive. Download the latest version named like:

  •  xpack-openocd-0.10.0-13-darwin-x64.tgz

Unpack

To install OpenOCD, unpack the archive and copy it to /${HOME}/opt/xPacks/openocd/<version>:

$ mkdir -p ~/opt
$ cd ~/opt

$ tar xvf ~/Downloads/xpack-openocd-0.10.0-13-darwin-x64.tgz
$ chmod -R -w xPacks/openocd/0.10.0-13

The result is a structure like:

$ tree -L 2 /Users/ilg/Library/xPacks/openocd/0.10.0-13
/Users/ilg/Library/xPacks/openocd/0.10.0-13
├── OpenULINK
│   └── ulink_firmware.hex
├── README.md
├── bin
│   ├── libftdi1.2.4.0.dylib
│   ├── libftdi1.2.dylib -> libftdi1.2.4.0.dylib
│   ├── libgcc_s.1.dylib
│   ├── libhidapi.0.dylib
│   ├── libusb-0.1.4.dylib
│   ├── libusb-1.0.0.dylib
│   └── openocd
├── contrib
│   ├── 60-openocd.rules
│   └── libdcc
├── distro-info
│   ├── CHANGELOG.md
│   ├── licenses
│   ├── patches
│   └── scripts
├── scripts
│   ├── bitsbytes.tcl
│   ├── board
│   ├── chip
│   ├── cpld
│   ├── cpu
│   ├── fpga
│   ├── interface
│   ├── mem_helper.tcl
│   ├── memory.tcl
│   ├── mmr_helpers.tcl
│   ├── target
│   ├── test
│   └── tools
└── share
    └── doc

20 directories, 15 files

To check if OpenOCD starts, use:

$ ~/opt/xPacks/openocd/0.10.0-13/bin/openocd --version
xPack OpenOCD, 64-bit Open On-Chip Debugger 0.10.0+dev (2019-07-17-15:21)

Download

The GNU/Linux versions of xPack OpenOCD are packed as TGZ archives. Download the latest version named like:

  • xpack-openocd-0.10.0-13-linux-x64.tgz
  • xpack-openocd-0.10.0-13-linux-x32.tgz

As the name implies, these are GNU/Linux tar.gz archives; they were build on CentOS, but can be executed on most recent GNU/Linux distributions. Select the -x64 file for 64-bit machines and the -x32 file for 32-bit machines.

Unpack

To install OpenOCD, unpack the archive and copy it to /${HOME}/opt/xPacks/openocd/<version>:

$ mkdir -p ~/opt
$ cd ~/opt

$ tar xvf ~/Downloads/xpack-openocd-0.10.0-13-linux-x64.tgz
$ chmod -R -w xPacks/openocd/0.10.0-13
$ tree -L 2 '/home/ilg/opt/xPacks/openocd/0.10.0-13'
/home/ilg/opt/xPacks/openocd/0.10.0-13
├── bin
│   ├── libftdi1.so.2 -> libftdi1.so.2.4.0
│   ├── libftdi1.so.2.4.0
│   ├── libhidapi-hidraw.so.0 -> libhidapi-hidraw.so.0.0.0
│   ├── libhidapi-hidraw.so.0.0.0
│   ├── libiconv.so.2 -> libiconv.so.2.6.0
│   ├── libiconv.so.2.6.0
│   ├── libudev.so
│   ├── libudev.so.0 -> libudev.so
│   ├── libusb-0.1.so.4 -> libusb-0.1.so.4.4.4
│   ├── libusb-0.1.so.4.4.4
│   ├── libusb-1.0.so.0 -> libusb-1.0.so.0.1.0
│   ├── libusb-1.0.so.0.1.0
│   └── openocd
├── contrib
│   ├── 60-openocd.rules
│   └── libdcc
├── distro-info
│   ├── CHANGELOG.md
│   ├── licenses
│   ├── patches
│   └── scripts
├── OpenULINK
│   └── ulink_firmware.hex
├── README.md
├── scripts
│   ├── bitsbytes.tcl
│   ├── board
│   ├── chip
│   ├── cpld
│   ├── cpu
│   ├── fpga
│   ├── interface
│   ├── mem_helper.tcl
│   ├── memory.tcl
│   ├── mmr_helpers.tcl
│   ├── target
│   ├── test
│   └── tools
└── share
    └── doc

20 directories, 21 files

To check if OpenOCD starts and is recent, use:

$ ~/opt/xPacks/openocd/0.10.0-13/bin/openocd --version
xPack OpenOCD, 64-bit Open On-Chip Debugger 0.10.0+dev (2019-07-17-15:21)

UDEV

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/xPacks/openocd/0.10.0-13/contrib/60-openocd.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules

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 you need to issue something like:

$ sudo usermod -aG plugdev $USER

Then restart and login again.

If you still have problems, check your distribution documentation and when you have a functional solution post it on the project forum.

Testing

To test if OpenOCD is able to connect to a specific board, it is generally necessary 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 STM32F4DISCOVERY board, you can use the sample below:

$ ~/opt/xPacks/openocd/0.11.0-13/bin/openocd -f board/stm32f4discovery.cfg
xPack OpenOCD, 64-bit Open On-Chip Debugger 0.10.0+dev (2019-07-17-15:21)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 2000 kHz
adapter_nsrst_delay: 100
none separate
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 2000 kHz
Info : STLINK V2J14S0 (API v2) VID:PID 0483:3748
Info : Target voltage: 2.881412
Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections
^C
Edit

If you have comments on the content of the page that you consider useful for other readers, please enter them here. For question and general support, please use the Project Forums.