To program the CPU on the Dash you'll need to setup a toolchain that can compile code for the Dash's ARM Cortex M3 processor.  The GNU compiler collection (GCC) is a great opensource toolchain with excellent ARM CPU support.  This page will walk through setting up a Linux-based virtual machine (VM) that uses GCC to compile code for the Dash.

Why use a VM for the toolchain?  The reason is that setting up a compiler for a different CPU architecture, AKA a cross compiler, can be quite challenging.  Each platform like Windows, OSX, etc. has a different process for installing and setting up the software so there's no single set of instructions that will work for everyone.  Using a VM for the toolchain makes it easy to follow one set of steps regardless of your operating system, and isolates the toolchain from conflicting with any other tools on your system.

This guide uses Vagrant and VirtualBox to manage and run the VM.  Both are excellent pieces of open source software that you can use for free to easily create VMs from the command line.  With just a few commands you'll have an entire toolchain provisioned and setup.

Dependencies

Before you get started you'll want to make sure you have the following software installed:

• VirtualBox - This guide was written using the 5.0 release.
• Vagrant - This guide was written using the 1.7.4 release.
• VirtualBox Extension Pack - Download and install the version that matches your version of VirtualBox.  To install on Windows just double click the downloaded .vbox-extpack file, or on Linux & Mac OSX run in a command terminal: VBoxManage extpack install /path/to/downloaded/vbox-extpack
• Git source control system - On Windows you should install the command line version of Git as you can use its shell to access the VM without having to install and use a separate SSH client.  On Linux or Mac OSX install git using your appropriate package manager, Homebrew, etc.

In addition you'll need around 5-10 gigabytes of free space for the VM's virtual hard disk.

On Windows ensure you have the STLink V2 USB driver installed.

On Linux you need to add your user to the vboxusers group so that VirtualBox can access USB devices on your computer.  In a terminal run the following command:

Toolchain Setup

Once you have the software installed open a command line terminal (in Windows open a 'Git Bash' terminal), navigate to where you'd like the toolchain to be created, and run the following command to clone its repository:

After a few moments the repository will be cloned, then run the following command to navigate inside the cloned directory and start up the VM:

Note that the very first time you start the VM it will take around 10-30 minutes to download an OS image and provision itself.  Future startups will just take a few seconds.

Whenever you want to control the VM, like starting it with the up command, you'll need to make sure you're inside the ARM-toolchain-vagrant directory that contains the Vagrantfile VM configuration.

After the VM starts run the following command to connect to it with SSH:

You should see welcome text and your terminal change to indicate you're logged in with user vagrant on the vagrant-ubuntu-trusty-64 VM:

Congrats, you're connected to the VM and ready to use the toolchain!

However if you see an error or Vagrant fails to start the VM, make sure you have all the required software installed.  In particular Vagrant is very sensitive about the version of VirtualBox that's installed so you might need to update both VirtualBox and Vagrant to ensure they're at the latest versions and then try again.  Don't forget you need the VirtualBox Extension Pack installed too.

For reference, to exit the VM and turn it off run the following command to leave the SSH session:

Then run the following command to shut off the VM:

Remember the virtual machine will always be running even after you log out of its SSH session.  You need to run the halt command to explicitly stop the VM.

Finally if you ever wish to completely remove the VM or even start back from scratch provisioning again, run the following command to destroy the VM image:

Installed Tools

With the VM running and a connection to it open with SSH you can examine the tools that are available. 

The GCC ARM compiler toolchain is installed and available in the system path under the arm-none-eabi-* names.  For example to see the version of the C compiler you can run:

Which will show output similar to:

In addition to GCC a few tools are installed for interacting with a STM32 processor using the STLink V2 programmer.  The first tool is OpenOCD and it's a very flexible debugger with support for the STLink and other programmers.  You can see its version by running:

Which will respond with something like:

The second tool is the Linux stlink command line tool which is a little simpler than OpenOCD but only works with the STLink programmer.  This tool is available in the system path under the st-util and st-flash programs.

Finally the VM is automatically configured to pass through the STLink V2 programmer from your host computer to the VM.  This means you can program and flash chips directly from the VM instead of having to copy out firmware files and flash from your main operating system.  To check that the VM can see your STLink V2 programmer connect it to the computer hosting the VM and then after a few seconds run the following command in the VM:

You should see a ST-LINK/V2 device listed like below:

Syncing Files

The general workflow is to use the VM to compile and flash code to a chip and your host operating system to edit the code with your preferred code editor.  To facilitate this workflow you can use Vagrant's synced folders to automatically transfer files between the VM and your operating system.

By default the VM is setup to sync anything in its /vagrant folder with the directory where the VM was created on the host computer (the ARM-toolchain-vagrant folder).  Try creating a text file in the ARM-toolchain-vagrant folder, then run the following commands in the VM to move to the synced folder and list the files:

You should see listed all the files that are in the ARM-toolchain-vagrant folder on your host computer, including the file you created.  Any files creat or modify here will be kept in sync between the VM and host computer.

Once you've setup the toolchain VM continue on to learn how to program the Dash CPU with example code.