OpenOCD

Description

OpenOCD (the open on-chip debugger) is an open source tool for debugging and flashing microcontrollers. In RIOT we try to use this tool for as many platforms as possible to reduce the overhead of having to keep track of many different (and sometimes proprietary) tools.

Versions

Many of the boards supported by RIOT use top-edge hardware that is only supported by very recent versions of OpenOCD. The OpenOCD versions that come with Linux distributions (e.g. 0.7.0 in Mint 17) are mostly not up-to-date. For this reason we recommend that you manually build the current upstream version.

How to build/install

The following steps are for building and installing OpenOCD under Linux Mint 17. But this howto should work unchanged also for recent Ubuntu versions. For other Linux distributions the steps have to slightly altered, Windows is TODO.

Linux Mint

1. Install prerequisites
   apt-get install build-essential autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev
2. Clone the OpenOCD git repository
   git clone git://git.code.sf.net/p/openocd/code openocd
3. Switch into the directory
   cd openocd
4. Bootstrap the build envoronment
   ./bootstrap
5. Call configure. Make sure all devices are put to yes in the configuration summary
   ./configure
6. Build the thing
   make
7. Install it
   sudo make install
8. Test if everything worked out properly
   openocd --version

This should give you the version you have just build, probably something like 0.9.0-dev-xxxx. Voila, thats it!

OS X

1. Using homebrew one can install the most recent version of openocd by
   brew install openocd --HEAD
2. Test if everything worked out properly
   openocd --version

This should give you the version you have just build, probably something like 0.9.0-dev-xxxx. Voila, thats it!

Problems & Fixes

When using OpenOCD on Mac OS X and you encounter an error similar to

Error: libusb_claim_interface() failed with LIBUSB_ERROR_ACCESS
Error: unable to open ftdi device with vid 0403, pid 6010, description '*' and serial '*'

make sure you are running make flash with sudo and that the system ftdi driver is unloaded:

From OpenOCD documentation ( source ):

If you're using a USB adapter and have a driver kext matched to it,
you will need to unload it prior to running OpenOCD. E.g. with Apple
driver (OS X 10.9 or later) for FTDI run:
  sudo kextunload -b com.apple.driver.AppleUSBFTDI
for FTDI vendor driver use:
  sudo kextunload FTDIUSBSerialDriver.kext

Transports and board support

To figure out if a board is supported by OpenOCD it's best to a look on the scripts that come with OpenOCD. On Ubuntu/Mint these are put into /usr/local/share/openocd/scripts/.

udev rules

When using OpenOCD on Linux and you encounter something similar to

Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
Error: no device found
Error: unable to open ftdi device with vid 0403, pid 6010, description 'FITECO M3' and serial '*'
in procedure 'init'

chances are you have to configure udev rules to work with the device. When built from source, OpenOCD provides examples in contrib/99-openocd.rules. Copy this file to your udev configuration directory make sure your vid and pid are covered and adjust the GROUP to some group you are part of.