View source for Arm compiler environment

The arm compiler environment for the ST microcontrollers used in the [[3D localization]] project contains a number of software packages, which ones are needed depends on the users demands to debugging.
It consists of an arm compiler including accessory binaries, openOCD for SWD usage (programming & debugging through GDB) and DFU-util for programming through USB.

==Compiler setup - Linux==

The following steps were performed on Linux Mint (Procedure is the same for Linux Ubuntu, but please adjust them accordingly for other distributions):

since the toolchain executables are 32-bits apps, when running on 64-bits machines, be sure you install the following 32-bits libraries (for different versions check the toolchain README for the actual list):

 $ sudo apt-get -y install lib32z1 lib32ncurses5 lib32bz2-1.0
on Mint 17.3 / Ubuntu 15.04 the following libraries are required:

 $ sudo apt-get -y install lib32ncurses5
on Ubuntu 12 LTSx64 all 32-bits libraries were packed in ia32-libs, so you can also use, but be prepared to get a lot of useless libraries:

 $ sudo apt-get -y install ia32-libs
download the latest Linux install tarball file from [https://launchpad.net/gcc-arm-embedded/+download Launchpad] (currently gcc-arm-none-eabi-5_3-2016q1-20160330-linux.tar.bz2, more than 60 MB)

Note: DO NOT install the ARM GCC package that comes with your distribution, especially if it is newer than the one provided by Launchpad, since generally it is not supported, and debugging sessions might fail.

locate the file (usually in the $HOME/Downloads/  folder)
decide on a location to install the toolchain; the recommended folder is /usr/local/ or /opt/
unpack the archive in the destination folder

 $ cd /opt
 $ sudo tar xjf ~/Downloads/gcc-arm-none-eabi-5_3-2016q1-20160330-linux.tar.bz2
the result should be a folder like /opt/gcc-arm-none-eabi-5_3-2016q1
test if the compiler is functional; use the actual install path:

 $ /opt/gcc-arm-none-eabi-5_3-2016q1/bin/arm-none-eabi-gcc --version
 arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 5.3 20160330 (release) [ARM/embedded-5-branch revision 234589]

In order to let the system know where to find the compiler binaries, there are three options:

# Add the extracted folder to your environment variables ($PATH for linux) '''(Not recommended for linux)'''
#; This can be done on linux by adding the following to '''<code>~/.profile</code>''': <code>export PATH=$PATH:/opt/gcc-arm-none-eabi-5_3-2016q1/bin/</code>
# Add a symbolic link of all the binaries for the compiler to your '''<code>/usr/bin/</code>'''
#; This can be done by issuing the following command with root privileges ('''NOTE''' You have to add all the binary files in the bin folder): <code>ln -s /opt/gcc-arm-none-eabi-5_3-2016q1/bin/<binary name> /usr/bin/</code>
# The third and last option is to alter the Makefile of the project to contain the absolute path to the compiler binaries '''(Also NOT recommended)'''
#; This can be done by changing the line in the Makefile containing the path to compiler binary folder

<br />
If you’ll ever need to remove the toolchain, just remove the /opt/gcc-arm-none-eabi-5_3-2016q1, there are no other components stored in system folders.

==OpenOCD setup==

In order to program the devices through SWD, a hardware programmer and some software are needed.

====ST-Link/V2====

The hardware used is ST's own ST-Link/V2 programmer, that can be acquired either in a proprietary version from ST, or in a cheap China version from eg. [www.ebay.de ebay] (I have only personally tested the cheap China version, which works to perfection).

====Installing OpenOCD====

The GNU/Linux versions of GNU ARM Eclipse OpenOCD are packed as TGZ archives. Go to the [https://github.com/gnuarmeclipse/openocd/releases GitHub Releases] page and download the latest version named like:

 [https://github.com/gnuarmeclipse/openocd/releases/download/gae-0.9.0-20150519/gnuarmeclipse-openocd-debian64-0.9.0-201505190955.tgz gnuarmeclipse-openocd-debian64-0.9.0-201505190955.tgz]
 [https://github.com/gnuarmeclipse/openocd/releases/download/gae-0.9.0-20150519/gnuarmeclipse-openocd-debian32-0.9.0-201505190955.tgz gnuarmeclipse-openocd-debian32-0.9.0-201505190955.tgz]

As the name implies, these are Debian tar.gz archives, but can be executed on most recent GNU/Linux distributions (they were tested on Debian, Ubuntu, Manjaro, SuSE and Fedora). Select the -debian64- file for 64-bit machines and the -debian32- file for 32-bit machines.

In case you use an older distribution and encounter difficulties to run GNU ARM Eclipse OpenOCD, you can also try to build it from sources on your machine. As a last resort, if your distribution includes an OpenOCD package, you can install it using the specific tools.

To install this package, unpack the archive and copy it to where you install binaries, eg. '''/opt/gnuarmeclipse/openocd/${version}''' or '''/usr/local/gnuarmeclipse/openocd/${version}'''

 sudo mkdir -p /opt/gnuarmeclipse
 cd /opt/gnuarmeclipse
 sudo tar xvf ~/Downloads/gnuarmeclipse-openocd-debian64-0.9.0-201505190955.tgz
Note: although perfectly possible to install it in any location, it is recommended to use either of the two above locations

To check if OpenOCD starts and is recent, use:

 $ /opt/gnuarmeclipse/openocd/0.9.0-201505190955/bin/openocd --version   GNU ARM Eclipse 64-bits Open On-Chip Debugger ....


====UDEV Rules====

For the JTAG probes implemented as USB devices (actually most of them), the last installation step on GNU/Linux is to configure the UDEV subsystem. OpenOCD provides an UDEV rules file defining all the supported IDs; to install it, just copy the file to '''/etc/udev/rules.d''' and eventually notify the daemon:

 $ sudo cp /opt/gnuarmeclipse/openocd/0.9.0-201505190955/contrib/99-openocd.rules /etc/udev/rules.d/
 $ sudo udevadm control --reload-rules
Note: If you previously installed the J-Link binaries, the USB IDs were already added to UDEV. The above OpenOCD rules file also defines the J-Link ID. Apparently UDEV does not complain; if you encounter problems, just comment out the definition in the OpenOCD file.

==DFU-Util setup==

'''OBS: Only the anchors, with their Cortex-M0 processor, supports programming through USB (DFU protocol).'''

The host-side tool used for programming the devices through USB, is called DFU-Util. <br />
The tool can be downloaded at [http://dfu-util.sourceforge.net/releases/ http://dfu-util.sourceforge.net/releases/], and is ready to be used out of the box. 

Extract the tool where you usually install programs (for linux this is usually /opt/ or /usr/local/), and choose one of the following three:

# Add the extracted folder to your environment variables ($PATH for linux) '''(Not recommended for linux)'''
#; This can be done on linux by adding the following to '''<code>~/.profile</code>''': <code>export PATH=$PATH:/path/to/DFU-Util/binary_folder/</code>
# Add a symbolic link of the DFU-Util binaries to your '''<code>/usr/bin/</code>'''
#; This can be done by issuing the following command with root privileges: <code>ln -s /path/to/DFU-Util/binary /usr/bin/</code>
# The third and last option is to alter the Makefile of the project to contain the absolute path to the DFU-Util binaries '''(Also NOT recommended)'''
#; This can be done by changing the line in the Makefile containing the path to DFU-Util

<br />

The DFU-util also comes in a Python version, which is included in the Scripts folder for convenience.

More info about the DFU-Util can be found at [http://dfu-util.sourceforge.net/ http://dfu-util.sourceforge.net/].