# Programming Microcontrollers using OpenOCD on a Raspberry Pi
## Overview
Yay you have finally moved on from 8-bit chips and are ready to try out some 32-bit hotness! Those ARM Cortex chips look fun, some have built in bluetooth, or 2.4ghz radios, or usb...all you have to do is learn how to program them.
# OpenOCD
On your way to learning how to use your favorite new ARM Cortex you may have heard of [OpenOCD](http://openocd.org/). OpenOCD is the software that we will use to do the actual programming of chips. Unlike the AVR ISP programming protocol, every ARM chip is significantly different to program, with platform-unique commands, flash locations, fuse bits, settings, etc. Teasing out those details is a struggle and if you change chips you have to start all over _even if both chips are, say, Cortex-M3 based!_
Each chip fab tends to supply its own programming software - Atmel has Atmel Studio, Nordic has NRFGo, ST has ST Link - but often times that software is Windows only.
OpenOCD is great because its cross platform, open source, and has support for a vast number of chips & programmers.
You can use OpenOCD with dongle-programmers such as J-Link and ST-Link or even an FTDI chip. But, if you have a spare Raspberry Pi (and who doesn't these days?) you can use it as a native OpenOCD programmer with just a few wires.
It's also really _fast_ to program chips natively, and if you have to program a mess of chips, it can make things speedy - an extra 30 seconds adds up when you're doing 1000!
# Programming Microcontrollers using OpenOCD on a Raspberry Pi
## Compiling OpenOCD
Compiling OpenOCD takes about 15 minutes but is worth the effort to get the latest code. You'll need to have command line access and a Pi on the Internet so you can download packages and software.
Thanks to [https://petervanhoyweghen.wordpress.com/2015/10/11/burning-zero-bootloader-with-beaglebone-as-swd-programmer/](https://petervanhoyweghen.wordpress.com/2015/10/11/burning-zero-bootloader-with-beaglebone-as-swd-programmer/) for the great tutorial, we're just adapting it for Pi usage!
# Compiling OpenOCD
Start by doing a fresh **sudo apt-get update** this will make sure you have the latest packages and repository set up.
Install all the tools you'll need to compile OpenOCD. OpenOCD changes a lot and is under constant development so we do suggest compiling your own!
```auto
sudo apt-get install git autoconf libtool make pkg-config libusb-1.0-0 libusb-1.0-0-dev libjim-dev
```
Download the latest source code for OpenOCD with:
```auto
git clone http://openocd.zylin.com/openocd
```
Change into the code directory and run the bootstrapper with:
```auto
cd openocd
./bootstrap
```
Next, we will compile OpenOCD with the Raspberry Pi native GPIO twiddling support - this will work on various Raspberry Pi's despite being called 'bcm2835gpio'
If you're following this guide on a non-Pi embedded linux board, you can skip the **--enable-bcm2835gpio** part and try to just use sysfsgpio. Sysfsgpio is much slower than native GPIO twiddling but it may not matter too much in your application.
```auto
./configure --enable-sysfsgpio --enable-bcm2835gpio
```
Note that when done, it wont mention GPIO support in the configuration summary, thats OK!
Run make. This can take a few minutes so you can also pass it the -j$(nproc) to build across all your processor cores.
```auto
make
```
Assuming compilation completes successfully as above, you can install with:
```auto
sudo make install
```
That's pretty much it!
You can see the list of interfaces available in **/usr/local/share/openocd/scripts/interface**
There's a _lot_ of options, in particular check out **raspberrypi2-native.cfg** and **raspberrypi-native.cfg** if you are interested in using OpenOCD with a non-Pi, look at **sysfsgpio-raspberrypi.cfg** which can help you port to a different linux computer
# Programming Microcontrollers using OpenOCD on a Raspberry Pi
## Wiring and Test
# Connecting to Target
OK you've done the compiling, now you are ready to connect!
In this case, I'll be connecting to an Atmel ATSAMD21G18 Cortex-M0 over SWD and uploading the Arduino bootloader to it. You can, of course, connect to _any_ processor that OpenOCD supports but this is the one I've got handy
# Wire up the target to SWD
Of course connections must be made! [Note that we are using the "BCM" pin numbering convention](http://elinux.org/RPi_BCM2835_GPIOs)
Connect:
- **Target GND** to **Pi GND**
- **Target SWDIO** to **Raspberry Pi #24**
- **Target SWCLK** to **Raspberry Pi #25**
- **Target Reset** to **Raspberry Pi #18** (may not be required)
- If powering the chip directly from the Pi, connect **3.3V** to **3.3V** (I'm just powering the chip over USB)
Of course, this assumes that your chip is running at 3.3V logic. For 1.8 or 5V logic, level shifting may be required.
You can later change the pins used in the **interfaces** configuration file but for now, I suggest just going with the default
# Create OpenOCD config
The easiest way to connect is creating a new directory in your home dir
**cd ~
mkdir bootloader
cd bootloader**
and then putting the file you want to program there, in this case I'm going to just grab the latest Arduino Zero bootloader (of course, substitute your own binary or hex!)
**wget https://github.com/arduino/ArduinoCore-samd/raw/master/bootloaders/zero/samd21\_sam\_ba.bin**
In the same directory, make a new file called **openocd.cfg**
**nano openocd.cfg**
and put the following into it:
```
source [find interface/raspberrypi2-native.cfg]
transport select swd
set CHIPNAME at91samd21g18
source [find target/at91samdXX.cfg]
# did not yet manage to make a working setup using srst
#reset_config srst_only
reset_config srst_nogate
adapter_nsrst_delay 100
adapter_nsrst_assert_width 100
init
targets
reset halt
```
Change **raspberrypi2-native.cfg** to whatever config you are using, e.g. for a Pi Zero or 1 use **raspberrypi1-native.cfg** or **raspberrypi-native.cfg**
If you're using a Pi Zero/1 you may also need to add
`bcm2835gpio_swd_nums 25 24 `
`bcm2835gpio_trst_num 7 `
`bcm2835gpio_srst_num 18`
You may need to also comment out `reset_config srst_nogate`, some people report that is required to make it work
Save the config file and then run **sudo openocd** (no other args, its all in the config!) in the directory. You _should_ get the following indicating a good connection
In particular make sure you get that **target state:halted** to you know it was able to connect!
Hit control-C to cancel out of openocd.
If you get **unknown** for state, or other errors, check your wiring! You may also need to powercycle or disconnect parts from the chip to get it into a good programming state. You may also need to change the programming frequency
Hit control-C to cancel out of openocd (or you can **telnet 127.0.0.1 4444** if you want to send commands, won't be covered here.
Now you can change the **openocd.cfg** with nano to add commands for burning the binary file. At the bottom put in:
```
init
targets
reset halt
at91samd bootloader 0
program samd21_sam_ba verify
at91samd bootloader 8192
reset
shutdown
```
This will init, look for targets, reset and halt the chip, turn off bootloader protection, burn in the bootloader file and verify it, re-turn-on bootloader protection, reset and shutdown openocd
You can skip the bootloader protection parts if you are not burning in a bootloader, of course
Of course, change the commands if you have a different file name, different chip, etc.
Save the file and run **sudo** **openocd** again:
Zoom! Programmed the bootloader in 0.02 seconds!
# More Options
If you don't want to set up the configure file, you can actually do it all from the command line:
** sudo openocd -f interface/raspberrypi2-native.cfg -c "transport select swd; set WORKAREASIZE 0; adapter\_nsrst\_delay 100; adapter\_nsrst\_assert\_width 100; source [find target/nrf51.cfg]" -c "init; reset; halt; nrf51 mass\_erase; reset" -c "shutdown"**
This will, for example, erase and reset a Nordic nRF51822 (which is a pretty finicky chip by the way, you may need to do hard resets to get it to talk to openocd)
## Featured Products
### Raspberry Pi 3 - Model B - ARMv8 with 1G RAM
[Raspberry Pi 3 - Model B - ARMv8 with 1G RAM](https://www.adafruit.com/product/3055)
Did you really think the Raspberry Pi would stop getting better? At this point, we sound like a broken record, extolling on the new Pi’s myriad improvements like we’re surprised that the folks at the Raspberry Pi Foundation are continuously making their flagship board better. ...
In Stock
[Buy Now](https://www.adafruit.com/product/3055)
[Related Guides to the Product](https://learn.adafruit.com/products/3055/guides)
### Raspberry Pi 2 - Model B v1.2 - ARM Cortex-A53 with 1G RAM
[Raspberry Pi 2 - Model B v1.2 - ARM Cortex-A53 with 1G RAM](https://www.adafruit.com/product/2358)
Didn't think the Raspberry Pi could get any better? You're in for a big surprise! The Raspberry Pi 2 Model B is out and it's amazing! With an upgraded ARM Cortex-A53 quad-core processor, Dual Core VideoCore IV Multimedia coprocessor, and a full Gigabyte of RAM, this...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2358)
[Related Guides to the Product](https://learn.adafruit.com/products/2358/guides)
### Raspberry Pi Model B+ 512MB RAM
[Raspberry Pi Model B+ 512MB RAM](https://www.adafruit.com/product/1914)
OMG OMG OMG, did you hear? There's a Raspberry Pi called the Model B+ and check it out...more USB ports, more GPIO, better power supply, four mounting holes, less sticky-out SD card! Yep, that's right, the fantastic engineers at Raspberry Pi HQ have blessed us with a new design....
In Stock
[Buy Now](https://www.adafruit.com/product/1914)
[Related Guides to the Product](https://learn.adafruit.com/products/1914/guides)
### SWD (2x5 1.27mm) Cable Breakout Board
[SWD (2x5 1.27mm) Cable Breakout Board](https://www.adafruit.com/product/2743)
This adapter board is designed to make it easier to use ARM dev boards that use slimmer 2x5 (0.05"/1.27mm pitch) SWD cables for programming. It's helpful for using products like the [JTAGulator](https://www.adafruit.com/products/1550),
In Stock
[Buy Now](https://www.adafruit.com/product/2743)
[Related Guides to the Product](https://learn.adafruit.com/products/2743/guides)
### 10-pin 2x5 Socket-Socket 1.27mm IDC (SWD) Cable - 150mm long
[10-pin 2x5 Socket-Socket 1.27mm IDC (SWD) Cable - 150mm long](https://www.adafruit.com/product/1675)
These little cables are handy when programming or debugging a tiny board that uses 10-pin 1.27mm (0.05") pitch SWD programming connectors. We see these connectors often on ARM Cortex dev kits, and have a few handy in our ARM-dev box. We thought you may want a backup cable as well, so now...
In Stock
[Buy Now](https://www.adafruit.com/product/1675)
[Related Guides to the Product](https://learn.adafruit.com/products/1675/guides)
### JTAG (2x10 2.54mm) to SWD (2x5 1.27mm) Cable Adapter Board
[JTAG (2x10 2.54mm) to SWD (2x5 1.27mm) Cable Adapter Board](https://www.adafruit.com/product/2094)
This adapter board is designed for adapting a 'classic' 2x10 (0.1"/2.54mm pitch) JTAG cable to a slimmer 2x5 (0.05"/1.27mm pitch) SWD Cable. It's helpful for using products like the [JTAGulator](https://www.adafruit.com/products/1550) or
In Stock
[Buy Now](https://www.adafruit.com/product/2094)
[Related Guides to the Product](https://learn.adafruit.com/products/2094/guides)
### SEGGER J-Link EDU - JTAG/SWD Debugger
[SEGGER J-Link EDU - JTAG/SWD Debugger](https://www.adafruit.com/product/1369)
[Discontinued - **you can grab ** SEGGER J-Link EDU Mini - JTAG/SWD Debugger **instead!**](https://www.adafruit.com/product/3571)
The SEGGER J-Link EDU is identical to the more expensive [J-Link BASE](https://www.adafruit.com/products/2209) model except...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/1369)
[Related Guides to the Product](https://learn.adafruit.com/products/1369/guides)
### SEGGER J-Link BASE - JTAG/SWD Debugger
[SEGGER J-Link BASE - JTAG/SWD Debugger](https://www.adafruit.com/product/2209)
The SEGGER J-Link BASE is identical to the cheaper [J-Link EDU](https://www.adafruit.com/products/1369) model except for the **terms of use**.
If you're going to use your debugger strictly for personal, non-commercial projects, such as publishing...
In Stock
[Buy Now](https://www.adafruit.com/product/2209)
[Related Guides to the Product](https://learn.adafruit.com/products/2209/guides)
## Related Guides
- [Introducing the Adafruit Bluefruit LE Friend](https://learn.adafruit.com/introducing-adafruit-ble-bluetooth-low-energy-friend.md)
- [Adafruit Metro M0 Express](https://learn.adafruit.com/adafruit-metro-m0-express.md)
- [Desktop or Laptop TFT Sidekick With FT232H](https://learn.adafruit.com/tft-sidekick-with-ft232h.md)
- [Google Docs Sensor Logging From Your PC](https://learn.adafruit.com/gdocs-sensor-logging-from-your-pc.md)
- [Bootloading Basics](https://learn.adafruit.com/bootloader-basics.md)
- [Proper Debugging of ATSAMD21 Processors](https://learn.adafruit.com/proper-step-debugging-atsamd21-arduino-zero-m0.md)
- [How to Program SAMD Bootloaders](https://learn.adafruit.com/how-to-program-samd-bootloaders.md)
- [CircuitPython Libraries and Jupyter Notebook on any Computer with MCP2221](https://learn.adafruit.com/jupyter-on-any-computer-with-circuitpython-libraries-and-mcp2221.md)
- [Introducing the Adafruit Grand Central M4 Express](https://learn.adafruit.com/adafruit-grand-central.md)
- [Adafruit FT232H Breakout](https://learn.adafruit.com/adafruit-ft232h-breakout.md)
- [Adafruit Metro M4 Express featuring ATSAMD51](https://learn.adafruit.com/adafruit-metro-m4-express-featuring-atsamd51.md)
- [Introducing Adafruit ItsyBitsy M4](https://learn.adafruit.com/introducing-adafruit-itsybitsy-m4.md)
- [Bluefruit nRF52 Feather Learning Guide](https://learn.adafruit.com/bluefruit-nrf52-feather-learning-guide.md)
- [Adafruit Metro M4 Express AirLift (WiFi)](https://learn.adafruit.com/adafruit-metro-m4-express-airlift-wifi.md)
- [Debugging CircuitPython On SAMD w/Atmel Studio 7](https://learn.adafruit.com/circuitpython-samd-debugging-w-atmel-studio-7.md)