Esden's Blog - libopenstm32

Black Magic Discovery

Esden — Mon, 29 Dec 2014 00:00:00 +0000

Hey everyone!

Today I had to fix another STM32F4 Discovery board. By fixing I mean replacing the STLink firmware with Black Magic Probe firmware. I do that on a semi regular basis but as I have not done it in a long time I did not remember the process anymore. Obviously this calls for a blog post with some step by step instructions on how to do it, so that I have a reference in the future. Also you might find it useful yourself.

First of all let's explain what we are trying to do. The objective is to replace the STLink SWD (Serial Wire Debug) firmware with Black Magic Probe firmware. The board is setup by default to use a smaller chip to run the STLink firmware to talk to the main stm32. We need to change the smaller chips firmware. The initial adjustments to the board are needed to be able to access the programming pins of the smaller chip and replace it's contents to Black Magic Probe firmware so that we can use GDB (GNU DeBugger) to program and debug the board instead of the very unstable and unreliable proprietary STLink protocol. The adjustments needed to access the small chips programming pins need to be reversed once the firmware is changed to Black Magic Probe firmware, resulting with an stm32 f4 discovery board with Black Magic Probe firmware ready to use.

For the "Fixing" process I use a genuine Black magic probe, I have one of those very early ones with a 0.1" header that is very useful in this particular case. You can also use a Black Magic Probe Mini with a PCB adapter, make an adapter cable or you can use another Discovery board that has already been "fixed".

Step 1

First step is to change the two solder jumpers on the bottom of the discovery board.

[caption id="attachment_503" align="alignnone" width="510"] Jumper modification for SWD programming.[/caption]

Remove the 0Ohm resistor/jumpers marked with red circles, and close the jumpers marked with blue circles.

Note: The easiest way to do that is to use a soldering tip, add a bunch more solder over the resistor and swipe them of. After that is done use solder wick to make sure there is no short on the "red" jumper. You can discard the 0Ohm resistors. It is much easier to just add a small blob of solder to close the "blue" jumpers, it is easy to remove them later in the process by just using some solder wick.

Step 2

Remove the SWD and slave MCU jumpers as indicated by the red circles in the photo.

[caption id="attachment_507" align="alignnone" width="576"] STM32F4 Discovery board Jumpers for updating the programmer chip firmware[/caption]

Step 3

Attach jumper wires to the Black Magic Probe header.

[caption id="attachment_509" align="alignnone" width="576"] Black Magic Probe Serial Wire Debug connections for Discovery board "fixing"[/caption]

Standard JTAG/SWD 20Pin 0.1" header

Black wire - Pin 14 (GND)
Orange wire - Pin 9 (TCLK/SWCLK)
Yellow wire - Pin 8 (TMS/SWDIO)

In case you are trying to figure out which pins these are on a standard ARM Cortex 10Pin 0.05" header. Here you go:

Standard JTAG/SWD Cortex 10Pin 0.1" header

Black wire - Pin 3, 5 or 9 (GND)
Orange wire - Pin 4 (TCLK/SWCLK)
Yellow wire - Pin 2 (TMS/SWDIO)

Step 4

Attach the Black Magic Probe to the discovery board.

[caption id="attachment_510" align="alignnone" width="576"] STM32F4 Discovery board Serial Wire Debug connection for "fixing" the on board programmer firmware[/caption]

Black wire (GND) - Pin 3 of the SWD (CN2) header
Orange wire (SWCLK) - Pin 2 of the ST-LINK/DISCOVERY (CN3) header
Yellow wire (SWDIO) - Pin 4 of the ST-LINK/DISCOVERY (CN3) header

Step 5

Now you can connect the discovery board and the Black Magic probe to your computer via USB. The order should not matter, but usually I tend to connect the usb wires to the laptop before connecting the SWD wires between the two devices, just to make sure we don't have some strange current loop that powers one or the other via IO pins, which might be problematic.

Step 6

Now we turn our attention to the software. You can obviously do these steps before you wire everything up but this is the order I followed.

The process requires a few dependencies that you should install using either apt on Linux or homebrew or macports on OS X:

Python
pyserial

In my case I use OS X and homebrew so I needed to run the following two commands:

brew install python pip install pyserial

Step 7

Download and make the an arm gcc compiler "findable". I recommend using GCC ARM Embedded as it is maintained by the ARM developers themselves and they seem to generally know what they are doing. :)

So download it from here: https://launchpad.net/gcc-arm-embedded

Then unpack it into your home directory:

[code language="text" gutter="false"] cd ~ tar xfvj ~/Downloads/gcc-arm-none-eabi-replace this with the version-mac.tar.bz2 [/code]

Then you should add the binary directory of the newly unpacked compiler package to your system. Obviously to do this you add the directory to your PATH environment variable. If you don't know what that is you should learn a bit more about your Unix/Linux basics. :)

export PATH=~/gcc-arm-none-eabi-someversion/bin:$PATH

To make this addition persistent you can also add that to your .profile, .bash_profile or .zprofile depending on the shell and setup you use.

Step 8

Download blackmagic firmware source code. You can get it at https://github.com/blacksphere/blackmagic

The easiest way is to clone the github repository, look for the small window at the center right of the github page for the git repository url. If you have a github account choose the ssh url but if you refuse to do so then you can go with the https one too. :)

If you did not learn about GIT and GitHub yet this is the perfect time to take a break from all of this here and come back after you have caught up on your homework. :D

git clone git@github.com:blacksphere/blackmagic.git

Step 9

Now let's build the firmware. This consists of three steps:

Fetch the libopencm3 submodule
Build from the toplevel so libopencm3 is built
Build the blackmagic firmware for the stlink

cd blackspheregit submodule initgit submodule updatemakecd srcmake cleanmake PROBE_HOST=stlink

Step 10

We can finally connect to the hardware we wired up before and erase the pesky stlink firmware. When the discovery boards ship, the firmware is read and write protected on the STLink chip. So to be able to overwrite the firmware we will have to unlock the chip. Thanks to Gareth there is a small python script that can do that for us. You just have to call the following command inside the src directory of the blackmagic repository and it should be able to remove the write protection:

../scripts/hexprog.py -s -d /dev/cu.usbmodemSOMESERIAL1 -r blackmagic.bin

In the case you are on Linux you can leave out the -d device parameter. For reference the -s parameter tells hexprog to use Serial Wire Debug instead of JTAG and -r tells it to unlock and erase the target chip.

If you skip any of those two parameters it will not work for you.

Step 11

Flash the bootloader. We are getting very close. To upload the blackmagic bootloader you use arm-none-eabi-gdb.

arm-none-eabi-gdb blackmagic_dfutarget extended_remote /dev/usbmodemSOMESERIAL1monitor swdp_scanattach 1loadexit

This sequence of commands attaches to the virtual gdb server that is provided by the Black Magic Probe on it's virtual serial port 1. (The second serial port is the USB to serial interface located on the back of the BMPM) We then tell the monitor (this is the BMP) to scan using Serial Wire Debug as our protocol. Next we attach to the virtual process number 1. (As we are on the embedded systems there usually should only ever be 1 process unless you run an RTOS) We load the firmware from the elf file that we passed on to gdb earlier and exit GDB.

Simple right? :D (Believe me that is definitely simpler than setting up and making OpenOCD work with Eclipse)

Tip: To make things easier for the future you can add the following to your .gdbinit file:

set target-async onset confirm offset history saveset mem inaccessible-by-default offtar ext /dev/cu.usbmodemSOMESERIAL1mon versionmon swdp_scan#mon jtag_scan att 1

Note: On Linux the cu.usbmodem device name will be /dev/ttyACM0 instead.

After setting up the .gdbinit file the upload process becomes quite a bit shorter:

arm-none-eabi-gdb blackmagicloadexit

Step 12

Upload the black magic firmware itself. Here you have two options. Either you can use the same process as before using GDB or you can use the now uploaded DFU bootloader to upload the Black Magic Probe firmware payload. Using GDB you would run the following:

arm-none-eabi-gdb blackmagictarget extended_remote /dev/cu.usbmodemSOMESERIAL1monitor swdp_scanattach 1loadexit

Alternatively you can upload the firmware using a DFU script. Before you do that though you should disconnect the genuine Black Magic Probe from your computer as you want to make sure the script flashes the Discovery board and not your BMP. To do that you will need to install python libusb as an additional dependency. But having done that you can then run the following to upload the firmware:

./scripts/stm32_mem.py blackmagic.bin

Step 13

Put everything back together. Now you just have to do four things:

Disconnect your Black Magic Probe and Discovery board from your computer as well as each other.
Remove the solder blobs you have added on the back of the board.
Add solder blobs to where you removed the resistors at the very beginning.
Put the jumpers back to where they were on the front of the Discovery board.

You are pretty much done now. If everything went well you should have your "fixed" discovery board. Follow to the one additional step below to test that.

Step 14

Plug in your Discovery board into your computer. The dual color led next to the USB connector should be solid Green. If it is blinking Green it means the bootloader is running and the board is expecting to be flashed with the firmware. This can happen if you still have the power jumper disconnected that provides power to the "slave" STM32F4 chip. This is actually very useful if you want to upgrade the Black Magic Probe firmware on your discovery board. :D

Additionally if everything went well if you are on Mac OS X a /dev/cu.usbmodemSOMESERIAL1 and /dev/cu.usbmodemSOMESERIAL3 should appear. If you are on linux you should be able to find ttyACM0 and ttyACM1 in the /dev directory.

I hope this write up is useful for you and the future me. :) I am planning to write another blog post on how to build and upload an example firmware onto the slave processor. So hold on to your hats! :)

Cheers,
Esden

P.S. Big thanks to Jack Ziesing for proofreading and introductory paragraph and sparking the work on this article. It is a great help! :)

libopencm3 Discovery

Esden — Mon, 29 Dec 2014 00:00:00 +0000

Hi everyone,

As promised in the previous post. Here is a short write up how to download, compile and upload your first example program using libopencm3 and a STM32F4 discovery board.

Very similar process will apply to any other evaluation boards that employ an STM32 microcontroller and Black Magic Probe JTAG/SWD programmer. Like for example Lisa/M, Lisa/MX, Lisa/S, Apogee and so on.

Step 1

If you did not already do that, download and install GCC ARM Embedded. You might have already done it if you were "fixing" your Discovery board.

You can download the compiler from here: https://launchpad.net/gcc-arm-embedded

Unpack it into your home directory:

cd ~
tar xfvj ~/Downloads/gcc-arm-none-eabi-replace this with the version-mac.tar.bz2

You should add the binary directory of the newly unpacked compiler package to your system. Obviously to do this you add the directory to your PATH environment variable. If you don't know what that is you should learn a bit more about your Unix/Linux basics. :)

export PATH=~/gcc-arm-none-eabi-someversion/bin:$PATH

To make this addition persistent you can also add that to your .profile, .bash_profile or .zprofile depending on the shell and setup you use.

Step 2

Download libopencm3-examples. You can find this repository at https://github.com/libopencm3/libopencm3-examples

git clone git@github.com:libopencm3/libopencm3-examples.git

Step 3

Build the libopencm3 examples. The repository contains libopencm3 as a submodule so you will have to initialize and update the submodule before you can compile the library itself as well as all the different examples.

cd libopencm3-examples
git submodule init
git submodule update
make

This will take a bit as there is a lot of examples included in that repository. In the past the examples were part of the main library itself but there became so many of them that we had to split it off. Otherwise the build and clone process just took too long.

Step 4

Prepare your environment. To make your life easier you should set up your .gdbinit configuration file. This will make the firmware upload and debug process so much easier. Just add the following lines to the .gdbinit file:

set target-async on
set confirm off
set history save
set mem inaccessible-by-default off
tar ext /dev/cu.usbmodemSOMESERIAL1
mon version
mon swdp_scan
#mon jtag_scan
att 1

Note: On linux the cu.usbmodemSOMESERIAL1 becomes ttyACM0.

For reference here is the breakdown of what the commands inside of the .gdbinit file mean:

set target-async on: Enable background execution commands.
set confirm off: This disables the really annoying "are you sure" questions. :)
set history save: This forces GDB to save the command history.
set mem inaccessible-by-default off: This is one of the most important commands here. Very often when you are trying to debug your code on a microcontroller you have to read the content of memory mapped registers. If you don't set this option the debugger will prevent you from doing so as it has no idea that this memory is actually accessible. On a PC having the option on makes total sense but on a microcontroller it is mostly a burden.
tar ext /dev/cu.usbmodemSOMESERIAL1: tell gdb to connect to Black Magic Probe
mon version: Print version of the Black Magic Probe.
mon swdp_scan: Scan for devices using SWD protocol.
att 1: Attach to the first process. On a microcontroller you will have only one process...

Step 4

Upload fancyblink example. The simplest example for the STM32F4 Discovery board is the fancyblink example. It is also very easy to upload. As long as your Discovery board is "fixed" and uses the BMP firmware.

cd examples/stm32/f4/stm32f4-discovery/fancyblink
arm-none-eabi-gdb fancyblink.elf
load
run

Now the LEDs on the Discovery board should be blinking. You can interrupt the execution of the program by pressing -C. You can continue the execution by running cont.

Here is a short reference of GDB commands that you might find useful when playing around with code:

load -> load the binary from the provided elf file. (Note: it detects if the elf file changed on the hard disk and loads a new one if available. So you don't have to quit GDB every time when you recompile your code)
run -> start the execution of your firmware
backtrace -> print the call stack trace of the current line of code being executed
make -> runs make command in the directory you started gdb. Very useful if you want to update the binary you are running really quick.
break filename:lineno -> you can add a breakpoint inside your code. GDB will stop the execution of the program as soon as the line is hit by the firmware.
step -> execute one single line of code and return back to the command line
next -> same as step but it does not enter into the functions called and skips them. Useful if you want to step over functions you know take forever and you are not interested in what they are actually doing. :)
print variablename -> print the content of a variable
print/x variablename -> print the content of a variable as HEX
list -> prints the context of the line being executed at the very moment
kill -> if used in a GDB script it will reset the MCU and exit GDB. Very useful as last command of a GDB script.

I hope this will be helpful for you.

Cheers, Esden

P.S. Big thanks to Jack Ziesing for proofreading and introductory paragraph and sparking the work on this article. It is a great help! :)

Open-Source and Open-Hardware Multicopter platform

Esden — Fri, 24 Jul 2009 00:00:00 +0000

Over the last two weeks many things happened. I found out that there is a really open-source and open-hardware quadrocopter project in the wild. It is called booz and is part of the paparazzi project. Code and schematics just as board layouts are under the GPLv2 or later license. That is really awesome news.

This project is intended for research and universities so the boards are using BGA parts that are difficult to solder for a mere mortal, and there is some lack in documentation. That is why some other people and me started a project called openmulticopter. The basic idea is to create and maintain a completely open-source quadrocopter/multicopter platform for everyone. As a multicopter does not consist only of the control electronics but also contains parts like remote control receiver, brushless motor controllers, a frame, and so on, we tried to combine many open-source parts that are already out there. Just take a look into the wiki for more details.

Some highlights of open-source components that we have chosen so far are:

booz (the core of the platform)
libopenstm32 (firmware library for STM32 microcontrollers)
RCOPEN24 (a 2.4GHz remote control system)
open-bldc (brushless motor controllers)

We also formulated a mission statement that can be found in the openmulticopter wiki.

There is still a lot of work in front of us, but I am really happy with the progress we are making. If you are interested in contributing just drop into the #openmulticopter IRC channel on Freenode, or write an email to the mailing list.