Running OpenOCD

Revision as of 14:33, 18 April 2012 by Wmat (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

OpenOCD provides a command line interface for interacting with embedded devices. To use OpenOCD you will need to run it from the command line. This guide includes basic information about using your operating system's command line interface. Unless otherwise noted, commands are identical in Linux and in Windows. If you are already proficient with the command line, you can find information specific to OpenOCD under the OpenOCD Config Files and Telnet Connection headings.

Opening the Command Prompt

In Ubuntu, open the Applications menu from the menu bar on your desktop, and choose Accessories > Terminal.

In Windows, open the Start Menu and click on Run... A small dialog box will appear. Type:


...and click OK. In Windows 7/Vista, the Run command does not appear in the Start Menu by default. To enable it, see Configuring Windows 7 for OpenOCD.

Command Prompt Basics - Paths and Navigation

The command prompt displays your current directory location. You will need to navigate to the OpenOCD directory to run it. To change directories, type 'cd followed by a file path. File paths can be absolute...

cd /usr/local/lib
cd \Program Files\TinCanTools
cd C:

...or relative...

cd Program Files
cd TinCanTools
cd lib/mingw

Absolute paths are from your root directory, and begin with a slash (or the current drive letter, on Windows). Relative paths are from the current directory and do not begin with a slash. On Windows, absolute paths use forward slashes (\) and relative paths use backslashes (/). On Linux, absolute and relative paths both use backslashes.

If you need to move to a new drive, type the drive letter followed by a colon...


If you need to go back to the parent of the current directory, you can type...

cd ..

You can even use this as part of a longer relative path. For example...

cd ../../TinCanTools

...would take you up two levels, and then into a folder called TinCanTools.

Running OpenOCD

Navigate to the directory containing your openocd executable. If you have just compiled OpenOCD according to the instructions on this wiki, the executable is located in openocd/src or openocd-0.4.0/src. In that directory, simply type...


To run the program. It won't do anything though, because you need the appropriate permissions and config files. To exit openocd, press CTRL + C.

OpenOCD and Permissions

OpenOCD needs administrator privileges to interact with your USB drivers. On Windows, you will need to be logged onto an account with administrator privileges. If you do not have access to such an account, contact your system administrator.

On Ubuntu, even users with administrator privileges do not typically log on with those privileges active. However, Linux provides commands to run another command as the root user. On Ubuntu, this command is sudo. To run a program as root, type sudo, then a space, then the name of the program. For example...


...runs OpenOCD with your user permissions, and likely prevents OpenOCD from interacting with libUSB. However...

sudo openocd

...runs OpenOCD as root, with full permission to access your USB drivers.

When you use the sudo command, Linux will prompt you for the root user's password. If you do not have access to this password, contact your system administrator.

OpenOCD Config Files

OpenOCD uses files with the .cfg extension to communicate with embedded devices. In the OpenOCD 0.4.0 release, these files are found in openocd-0.4.0/tcl and its subdirectories. From the tcl directory, the configuration file for the Flyswatter is at interface/flyswatter.cfg. The file for the TinCanTools Hammer is at board/hammer.cfg. If your copy of OpenOCD includes support for the Flyswatter2, its config file is at interface/flyswatter2.cfg.

When you start OpenOCD, you tell it to use the config files for your hardware with the -f switch, like this:

openocd -f path_to/cfg_file [-f path_to/other_cfg_file]

For example, suppose you want to run OpenOCD for the Flyswatter2 and the Hammer. The current directory contains the OpenOCD executable and the tcl directory. You would type:

openocd -f tcl/interface/flyswatter2.cfg -f tcl/board/hammer.cfg

On Ubuntu, remember to use the sudo command to run OpenOCD as root:

sudo openocd -f tcl/interface/flyswatter2.cfg -f tcl/board/hammer.cfg

Telnet Connection

OpenOCD runs as a daemon. It accepts connections from other programs, but does not provide any means for you to give it commands directly. Once OpenOCD is running on your computer you will need to connect to it through another program, such as telnet.

Ubuntu and Windows XP provide a telnet client by default. To use telnet in Windows 7/Vista you will need to enable it manually. The Configuring Windows 7 for OpenOCD page will show you how to enable the telnet client.

To run telnet and connect to OpenOCD, open a new command prompt. From any directory, type:

telnet localhost 4444

On Linux, you may need to run telnet as root:

sudo telnet localhost 4444

You should see a simple prompt (>). From this prompt you will be able to send commands to OpenOCD. To exit the telnet prompt, press CTRL + C.