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.

• Windows
• macOS
• GNU/Linux

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:

cd my-project
xpm init # Only at first use.

xpm install @xpack-dev-tools/openocd@latest --verbose

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

Tip: The install location can be configured using the XPACKS_STORE_FOLDER environment variable; for more details please check the xpm folders page.

Tip: The archive content is unpacked into a folder named .content. On some platforms this might be hidden for normal browsing, and require separate options (like ls -A) or, in file browsers, to enable settings like Show Hidden Files.

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

Important: Automatic path discovery for the packages from the new @xpack-dev-tools scope was added to GNU MCU Eclipse plug-ins with v4.6.1 in 2019-09-23; update older versions or configure the path manually.

Uninstall

To remove the links from the current project:

cd my-project

xpm uninstall @xpack-dev-tools/openocd

To completely remove the package from the central xPacks store:

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

Test

To check if the xpm installed OpenOCD starts, use something like:

C:\>%USERPROFILE%\AppData\Roaming\xPacks\@xpack-dev-tools\openocd\0.11.0-4.1\.content\bin\openocd.exe --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

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.11.0-4-win32-x64.zip

Note: In case you wonder where the suffix comes from, it is exactly the Node.js process.platform and process.arch. The win32 part is confusing, but we have to live with it.

Unpack

To manually install the xPack OpenOCD, 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.

Note: For manual installs, the recommended install location is slightly different from the xpm install folders, which use the scope (like @xpack-dev-tools) to group different tools, and .content to store the unpacked archive.

Important: Although perfectly possible to install OpenOCD in any folder, it is highly recommended to use this path, since by default the Eclipse Embedded CDT debug plug-ins search for the executable in this location.

The result is a structure like:

Test

To check if the manually installed OpenOCD starts, use something like:

C:\>%USERPROFILE%\AppData\Roaming\xPacks\openocd\xpack-openocd-0.11.0-4\bin\openocd.exe --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

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.

Warning: Although converting the vendor drivers to WinUSB drivers will make OpenOCD happy, please be aware that other tools using the original drivers will no longer work while Zadig is active, and to make them work you need to uninstall the Zadig driver for the device and reinstall the vendor driver (see Zadig FAQ). Our recommendation is to use Zadig only as a last resort solution, and, when possible, prefer the manufacturer 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.

For other probes follow the manufacturer instructions.

Note: All Windows tests were performed on Windows 10. If, for any reasons, you still use older versions, especially 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.

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:

cd my-project
xpm init # Only at first use.

xpm install @xpack-dev-tools/openocd@latest --verbose

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

Tip: The install location can be configured using the XPACKS_STORE_FOLDER environment variable; for more details please check the xpm folders page.

Tip: The archive content is unpacked into a folder named .content. On some platforms this might be hidden for normal browsing, and require separate options (like ls -A) or, in file browsers, to enable settings like Show Hidden Files.

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

Important: Automatic path discovery for the packages from the new @xpack-dev-tools scope was added to GNU MCU Eclipse plug-ins with v4.6.1 in 2019-09-23; update older versions or configure the path manually.

Uninstall

To remove the links from the current project:

cd my-project

xpm uninstall @xpack-dev-tools/openocd

To completely remove the package from the central xPacks store:

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

Test

To check if the xpm installed OpenOCD starts, use something like:

$ ~/.local/xPacks/@xpack-dev-tools/openocd/0.11.0-4.1/.content/bin/openocd --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

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 macOS versions of xPack OpenOCD are packed as .tar.gz archives. Download the latest version named like:

• xpack-openocd-0.11.0-4-darwin-x64.tar.gz
• xpack-openocd-0.11.0-4-darwin-arm64.tar.gz

Unpack

To manually install the xPack OpenOCD, unpack the archive and copy it to ~/.local/xPacks/openocd/<version>:

mkdir -p ~/.local/xPacks/openocd
cd ~/.local/xPacks/openocd

tar xvf ~/Downloads/xpack-openocd-0.11.0-4-darwin-x64.tar.gz
chmod -R -w xpack-openocd-0.11.0-4

Note: For manual installs, the recommended install location is different from the xpm install folders.

Important: Although perfectly possible to install OpenOCD in any folder, it is highly recommended to use this path, since by default the Eclipse Embedded CDT debug plug-ins search for the executable in this location.

The result is a structure like:

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

21 directories, 14 files

Test

To check if the manually installed OpenOCD starts, use something like:

$ ~/.local/xPacks/openocd/xpack-openocd-0.11.0-4/bin/openocd --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

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:

cd my-project
xpm init # Only at first use.

xpm install @xpack-dev-tools/openocd@latest --verbose

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

Tip: The install location can be configured using the XPACKS_STORE_FOLDER environment variable; for more details please check the xpm folders page.

Tip: The archive content is unpacked into a folder named .content. On some platforms this might be hidden for normal browsing, and require separate options (like ls -A) or, in file browsers, to enable settings like Show Hidden Files.

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

Important: Automatic path discovery for the packages from the new @xpack-dev-tools scope was added to GNU MCU Eclipse plug-ins with v4.6.1 in 2019-09-23; update older versions or configure the path manually.

Uninstall

To remove the links from the current project:

cd my-project

xpm uninstall @xpack-dev-tools/openocd

To completely remove the package from the central xPacks store:

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

Test

To check if the xpm installed OpenOCD starts, use something like:

$ ~/.local/xPacks/@xpack-dev-tools/openocd/0.11.0-4.1/.content/bin/openocd --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

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 GNU/Linux versions of xPack OpenOCD are packed as .tar.gz archives. Download the latest version named like:

• xpack-openocd-0.11.0-4-linux-x64.tar.gz
• xpack-openocd-0.11.0-4-linux-arm.tar.gz
• xpack-openocd-0.11.0-4-linux-arm64.tar.gz

As the name implies, these are GNU/Linux tar.gz archives; they were build on Ubuntu, but can be executed on most recent GNU/Linux distributions.

Unpack

To manually install the xPack OpenOCD, unpack the archive and move it to ~/.local/xPacks/openocd/xpack-openocd-0.11.0-4:

mkdir -p ~/.local/xPacks/openocd
cd ~/.local/xPacks/openocd

tar xvf ~/Downloads/xpack-openocd-0.11.0-4-linux-x64.tar.gz
chmod -R -w xpack-openocd-0.11.0-4

Note: For manual installs, the recommended install location is slightly different from the xpm install folders, which use the scope (like @xpack-dev-tools) to group different tools, and .content to store the unpacked archive.

Important: Although perfectly possible to install OpenOCD in any folder, it is highly recommended to use this path, since by default the Eclipse Embedded CDT debug plug-ins search for the executable in this location.

$ tree -L 2 '/home/ilg/.local/xPacks/openocd/xpack-openocd-0.11.0-4'
/home/ilg/.local/xPacks/openocd/xpack-openocd-0.11.0-4/
├── bin
│   └── openocd
├── contrib
│   ├── 60-openocd.rules
│   └── libdcc
├── distro-info
│   ├── CHANGELOG.md
│   ├── licenses
│   ├── patches
│   └── scripts
├── libexec
│   ├── libftdi1.so.2 -> libftdi1.so.2.5.0
│   ├── libftdi1.so.2.5.0
│   ├── libhidapi-hidraw.so.0 -> libhidapi-hidraw.so.0.0.0
│   ├── libhidapi-hidraw.so.0.0.0
│   ├── libiconv.so.2 -> libiconv.so.2.6.1
│   ├── libiconv.so.2.6.1
│   ├── libudev.so.1 -> libudev.so.1.6.9
│   ├── libudev.so.1.6.9
│   ├── libusb-1.0.so.0 -> libusb-1.0.so.0.3.0
│   └── libusb-1.0.so.0.3.0
├── 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

21 directories, 19 files

Test

To check if the manually installed OpenOCD starts, use something like:

$ ~/.local/xPacks/openocd/xpack-openocd-0.11.0-4/bin/openocd --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

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 ~/.local/xPacks/openocd/xpack-openocd-0.11.0-4/contrib/60-openocd.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules

Tip: 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 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 GitHub Discussions.

Test

To check if the manually installed OpenOCD starts, use something like:

$ ~/.local/xPacks/openocd/xpack-openocd-0.11.0-4/bin/openocd --version
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)

Testing

To test if the xpm installed 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:

$ ~/.local/xPacks/@xpack-dev-tools/openocd/0.11.0-4.1/.content/bin/openocd -f board/stm32f4discovery.cfg
xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2022-03-25-19:34)
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