CHAPTER 2

Software Setup
Before you can get underway with project-related work, you need some software
installed. There are a number of “moving parts” involved. Despite this, the process
should proceed smoothly. Once accomplished, it need not be revisited.

Directory Conventions Used

Throughout this book, I’ll need to refer to different subdirectories of the supplied software.
It is assumed that the top level of your installed software is named “~/stm32f103c8t6.”
So, when I refer to a pathname “~/stm32f103c8t6/libopencm3/README.md,” I’ll assume
that starts from your home (~) directory (wherever that is). I’ll often use this pathname
convention for clarity, even though your current directory may be the correct one for the
file being referenced.

O
 perating Software
I’m also going to assume you have a POSIX (Linux/Unix) environment from which
to run commands. The Linux or Raspberry Pi environments using the bash shell are
perhaps the most natural. Other good environments include FreeBSD and MacOS. From
FreeBSD, I’ll assume that you are using the bash shell.
If you’re using Windows and you haven’t installed it yet, you’ll want to install Cygwin
(https://www.cygwin.com). Some might use MSYS instead. After installing the base
Cygwin system, make sure that you also install make and git. This will give you a Linux-­
like command-line environment from which to build software.

17
© Warren Gay 2018
W. Gay, Beginning STM32, https://doi.org/10.1007/978-1-4842-3624-6_2
Chapter 2 Software Setup

Mac users will need to install git at a minimum. You’ll also need GNU make,
especially if you use FreeBSD (Free Berkeley Software Distribution). Sometimes GNU
make is installed as gmake instead on a BSD (Berkely Software Distribution) system. If
you’re using Mac Homebrew (https://brew.sh), you can install these as follows:

$ brew install make

$ brew install git

If you’re a Mac Ports (https://www.macports.org) user, you’ll need to use that

framework to install make and git.

B
 ook Software
The directory structure for building with libopencm3 and FreeRTOS is available from
github.com. Choose a suitable place from which to create a subdirectory. This book will
assume home directory:

$ cd ~

Use the git command to download and create a subdirectory as follows:

$ git clone https://github.com/ve3wwg/stm32f103c8t6.git

The preceding command will create directory ~/stm32f103c8t6. However, feel free
to rename it to something easier to type, like ~/stm32.

l ibopencm3
Next, we must download the libopencm3 software into the correct place. First, change to
the subdirectory, and then issue the git clone command for libopencm3:

$ cd ~/stm32f103f8t6
$ git clone https://github.com/libopencm3/libopencm3.git

This will populate the directory ~/stm32f103c8t6/libopencm3 with files and

subdirectories.

18
 Chapter 2 Software Setup

F reeRTOS
The next important piece of software is FreeRTOS. Unfortunately, it must be downloaded
and unpacked as a zip file.

1. Go to http://www.freertos.org.

2. Locate “Download Source” at the left.

3. Click the link “2. Click to download the latest official release from
SourceForge.”

Depending on your browser and operating system, a zip file should be downloaded
automatically. It will have a version number in the file name. At the time of writing, the
downloaded file name is FreeRTOSv10.0.1.zip. Change to the ~/stm32f103c8t6/rtos
subdirectory before unpacking the zip file. On my Mac, the download directory is
~/Downloads. Substitute in the unzip command as required for your system:

$ cd ~/stm32f103c8t6/rtos
$ unzip ~/Downloads/FreeRTOSv10.0.1.zip

Once that completes, there should be several files and subdirectories under
~/stm32f103c8t62/rtos/FreeRTOSv10.0.1.

~
 /stm32f103c8t6/rtos/Project.mk
Because the version number of FreeRTOS is included in the subdirectory name, there is
a potential change left. Edit the file Project.mk with your favorite editor (or nano) and
locate the following line near the top of the file:

FREERTOS        ?= FreeRTOSv10.0.1

If your version of FreeRTOS is newer than this, like FreeRTOSv11.0.0, then edit it to
match your version and resave the file:

FREERTOS        ?= FreeRTOSv11.0.0

This will allow the Project.mk make file to work correctly later when you want to
create a new RTOS project.

19
Chapter 2 Software Setup

ARM Cross Compiler

If you don’t yet have an ARM cross compiler installed, it will need to be installed. If
you’re running Linux or Raspberry Pi, you may be able to just use the apt-get command
to install it. Despite that, I recommend that you download and install the toolchain as
outlined next instead because some cross-compiler tools are not well organized and are
sometimes incomplete.
If you’re running Mac or Windows (Cygwin), then definitely use the following
procedure. This procedure is also recommended for Linux and Raspberry Pi if you have
had problems with the installed packages:

1. Go to the site https://developer.arm.com.

2. Click on the link “Linux/Open Source.”

3. Scroll down and click on “ARM GNU Embedded Toolchain.”

4. Scroll down and click on the big button labeled “Downloads.”

5. Scroll down until you find the platform download required.

Windows 32-bit, Linux 64-bit, Mac OS X 64-bit, etc. Click on the
appropriate choice for your platform to download.

6. Create a system directory /opt (if you do not already have one):

$ sudo -i
# mkdir /opt

7. Change to the /opt directory (as root):

# cd /opt

8. From this point, you’ll unpack your compiler download (Mac

example). Be sure to be specific about your home directory:

# tar xjf ~myuserid/Downloads/gcc-arm-none-eabi-6-2017-q2-

update-mac.tar.bz2

Use tar option “j” if the ending of the file is .bz2. Otherwise,
use “z” when the ending is .gz. If you don’t have the GNU tar
command installed on the Mac, then you can install it using
macports (www.macports.org) or Homebrew (https://brew.sh/).

20
 Chapter 2 Software Setup

9. Once the tar file has been extracted, it may produce a large
directory name like gcc-­arm-­none-eabi-6-2017-q2-update. Now
is a good time to shorten that:

# mv gcc-arm-none-eabi-6-2017-q2-update gcc-arm

This will rename the directory /opt/gcc-arm-none-eabi-6-2017-

q2-­update to a more manageable name /opt/gcc-arm.

10. Now, exit root and return to your developer session. In that
session, add the compiler’s bin directory to your PATH:

$ export PATH="/opt/gcc-arm/bin:$PATH"

11. At this point, you should be able to test your cross compiler:

$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors
6-2017-q2-update) 6.3.1 20170620 (release) [ARM/embedded-
6-­branch revision 249437]
Copyright (C) 2016 Free Software Foundation, Inc.
This is free software; see the source for copying
conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

If the compiler doesn’t start and instead gives you a message like this:

$ arm-none-eabi-gcc --version
-bash: arm-none-eabi-gcc: command not found

then your PATH variable is either not set up properly or not exported, or the installed
tools are using a different prefix. Perform the following if necessary (the output has been
abbreviated slightly here):

$ ls -l /opt/gcc-arm/bin
total 75128
-rwxr-xr-x@ 1 root  wheel  1016776 21 Jun 16:11 arm-none-eabi-addr2line
-rwxr-xr-x@ 2 root  wheel  1055248 21 Jun 16:11 arm-none-eabi-ar
-rwxr-xr-x@ 2 root  wheel  1749280 21 Jun 16:11 arm-none-eabi-as

21
Chapter 2 Software Setup

-rwxr-xr-x@ 2 root  wheel  1206868 21 Jun 19:08 arm-none-eabi-c++

-rwxr-xr-x@ 1 root  wheel  1016324 21 Jun 16:11 arm-none-eabi-c++filt
-rwxr-xr-x@ 1 root  wheel  1206788 21 Jun 19:08 arm-none-eabi-cpp
-rwxr-xr-x@ 1 root  wheel    42648 21 Jun 16:11 arm-none-eabi-elfedit
-rwxr-xr-x@ 2 root  wheel  1206868 21 Jun 19:08 arm-none-eabi-g++
-rwxr-xr-x@ 2 root  wheel  1202596 21 Jun 19:08 arm-none-eabi-gcc
...
-rwxr-xr-x@ 2 root  wheel  1035160 21 Jun 16:11 arm-none-eabi-nm
-rwxr-xr-x@ 2 root  wheel  1241716 21 Jun 16:11 arm-none-eabi-objcopy
...

If you obtained your cross compiler from a different source than the one indicated,
you might not have the prefix names. If you see the file name gcc instead of arm-none-­
eabi-gcc, you’ll need to invoke it as simply gcc. But be careful in this case, because your
cross compiler may get confused with your platform compiler. The prefix arm-none-­
eabi- prevents this. When you go to use your cross platform gcc, check that the correct
compiler is being used with the type command:

$ type gcc
arm-none-eabi-gcc is hashed (/opt/gcc-arm/bin/gcc)

If your bash shell is locating gcc from a different directory than the one you installed,
then your PATH is not set correctly.
If you must change the toolchain prefix, then the top-level ~/stm32f103c8t6/
Makefile.incl should be edited:

$ cd ~/stm32f103c8t6
$ nano Makefile.incl

Modify the following line to suit and resave it:

PREFIX          ?= arm-none-eabi

In a normal situation where the cross-platform prefix is used, you should also be able
to make this confirmation:

$ type arm-none-eabi-gcc
arm-none-eabi-gcc is hashed (/opt/gcc-arm/bin/arm-none-eabi-gcc)

22
 Chapter 2 Software Setup

This confirms that the compiler is being run from the installed /opt/gcc-arm directory.

Note The PATH variable will need modification for each new terminal session
to use the cross-compiler toolchain. For convenience, you may want to create a
script, modify your ~/.bashrc file, or create a shell alias command to do this.

Build the Software

At this point, you’ve installed the book software, libopencm3, FreeRTOS, and the ARM
cross-compiler toolchain. With the PATH variable set (as just seen), you should now be
able to change to your stm32f103c8t6 directory and type make (some users might need
to use gmake instead):

$ cd ~/stm32f103c8t6
$ make

This will build ~/stm32f103c8t6/libopencm3 first, followed by all other

subdirectories.
There is always the possibility that a new version of libopencm3 might create build
problems. These are difficult to anticipate, but here are some possibilities and solutions:

1. Something in libopencm3 is flagged as an error by the cross

compiler, where previously it was acceptable. You can:

a. Correct or work around the problem in the libopencm3

sources.

b. Try a later (or prior) version of the cross-compiler toolchain.

Newer toolchains will often correct the issue. For reference,
the toolchain used for this book was “GNU Tools for ARM
Embedded Processors 6-2017-q2-update) 6.3.1 20170620.”

c. Install an older version of libopencm3. All projects tested in

this book used the library with the latest git commit dated
October 12, 2017.

2. Something in the book’s software is busted. Check the git

repository for updates. As issues become known, fixes will be
applied and released there. Also check the top-­level README.md file.
23
Chapter 2 Software Setup

ST-Link Tool
There is one final piece of software that may need installation. If you’ve not already
installed it using your system’s package manager, you’ll need to install it now. Even if you
have it installed already, it may be outdated. Let’s test it to see:

$ st-flash

Look for the following line in the help display:

./st-flash [--debug] [--reset] [--serial <serial>] [--format <format>] \

  [--flash=<fsize>] {read|write} <path> <addr> <size>

If you don’t see the option --flash=<fsize> mentioned, then you may want to
download the latest from github and build it from source code. This is only necessary if
you want to use more than 64K of flash memory. None of the demos in this book go over
that limit.
People have reported that many of the STM32F103C8T6 units support 128K of flash
memory, even though the device reports that it only has 64K. The following command
probes a unit that I own, from eBay, for example:

$ st-info --probe
Found 1 stlink programmers
serial: 493f6f06483f53564554133f
openocd: "\x49\x3f\x6f\x06\x48\x3f\x53\x56\x45\x54\x13\x3f"
  flash: 65536 (pagesize: 1024)
   sram: 20480
chipid: 0x0410
  descr: F1 Medium-density device

The information reported indicates that the device only supports 65536 bytes (64K)
of flash. Yet, I know that I can flash up to 128K and use it (all of mine support 128K).
It has been suggested that both the F103C8 devices and the F103B8 devices use the
same silicon die. I’ll cover using the ST-Link V2 programmer on your device in the next
chapter.
If you don’t have these utilities installed, do so now using apt-get, brew, yum, or
whatever your package manager is. Failing a package install, you can download the latest
source code from github here:

24
 Chapter 2 Software Setup

$ cd ~
$ git clone https://github.com/texane/stlink.git
$ cd ./stlink
$ make
$ cd build/Release
$ sudo make install

If you run into trouble with this, see the following online resources:

• The README.md file at https://github.com/texane/stlink

• https://github.com/texane/stlink/blob/master/doc/compiling.md

• Make sure that you have libusb installed.

• Some Linux distributions may require you to also perform sudo

ldconfig after the install.

S
 ummary
With the software installs out of the way, we can finally approach the hardware and do
something with it. In the next chapter, we’ll look at your power options and then apply
the ST-Link V2 programmer to probe your device.

25