...

TL;DR: Installation Instructions

Note: Ensure that before proceeding with the installation process that the STLink and USB device is disconnected, otherwise the USB filter will not pass the USB device through to the VM.

Windows

First make sure all these prerequisites are installed. The installation steps will fail if these are not installed.

Note: If any of the vagrant commands gives an error, you might need to have VT-x/AMD-v enabled. This can be done through your BIOS settings (the setting is probably called Intel(R) Virtualization Technology, or something).

Prerequisites

• Vagrant on Windows
• Git Bash
• VirtualBox platform packages
• VirtualBox Oracle VM VirtualBox Extension Pack

Using Git Bash, clone the box repository somewhere

git clone https://github.com/uw-midsun/box.git && cd box/

Then start the box using

vagrant up && vagrant reload

This will download the Vagrant box, which might take a while.

Then, to access the box, ssh in

vagrant ssh 

These 3 commands only need to be run the first time you start working with uwmidsun/box. More details can be found in the README.md file.

The shared/ directory will be shared between your host operating system and the virtual environmnent (/home/vagrant/shared/). You can clone the uw-midsun/firmware repo here from the ssh session, and then use your editor of choice from your host operating system

cd ~/shared/
git clone https://github.com/uw-midsun/firmware.git && cd firmware

Then, ensure that you can build the code using make

make build_all

macOS

First make sure all these prerequisites are installed. The installation steps will fail if these are not installed.

Note: There's a regression in VirtualBox that prevents USB passthrough from working correctly with STLink/JTag. On a Mac, ensure that you install VirtualBox 5.0.8, and the 5.0.8 Extension Pack.

Prerequisites

• brew
• VirtualBox 5.0.8
• VirtualBox 5.0.8 Extension Pack

First, make sure git is installed

brew install git

Then clone the uw-midsun/box repository somewhere

git clone https://github.com/uw-midsun/box.git && cd box/

And start the box using

vagrant up && vagrant reload

This will download the Vagrant box, which might take a while.

Then, to access the box, ssh in

vagrant ssh

These 3 commands only need to be run the first time you start working with uwmidsun/box. More details can be found in the README.md file.

The shared/ directory will be shared between your host operating system and the virtual environment (/home/vagrant/shared/). You can clone the uw-midsun/firmware repo here from the ssh session, and then use your editor of choice from your host operating system

cd ~/shared/
git clone https://github.com/uw-midsun/firmware.git && cd firmware

Then, ensure that you can build the code using make

make build_all

Linux

These commands are for a Debian-based distribution (like Ubuntu).

Prerequisites

• VirtualBox
• VirtualBox Oracle VM VirtualBox Extension Pack

Make sure git is installed

sudo apt-get install git

After installing VirtualBox, you'll have to add your user to the vboxusers group, so that the virtual machine can access your USB devices.

sudo usermod -a -G vboxusers $USER

Now reboot your machine.

Then clone the uw-midsun/box somewhere

git clone https://github.com/uw-midsun/box.git && cd box/

And start the box using

vagrant up && vagrant reload

This will download the Vagrant box, which might take a while.

Then, to access the box, ssh in

vagrant ssh 

These 3 commands only need to be run the first time you start working with uwmidsun/box. More details can be found in the README.md file.

The shared/ directory will be shared between your host operating system and the virtual environmnent (/home/vagrant/shared/). You can clone the uw-midsun/firmware repo here from the ssh session, and then use your editor of choice from your host operating system

cd ~/shared/
git clone https://github.com/uw-midsun/firmware.git && cd firmware

Then, ensure that you can build the code using make

make build_all

Background Information

You can refrain from downloading anything on the linked websites unless it is in the Installation section, —we have set up a template package that already contains most of the libraries and it should be straightforward to get set up on the rest of the development environmentVagrant box that packages the development environment for you. This guide is meant to help you understand the layout of the template and understand the toolchain required for developing embedded software for the solar car. It aims to be a comprehensive guide to getting you to the point where you can start developing as soon as you feel comfortable with the C paradigms for embedded programming. 

...

Prerequisites

Before we get started if you have not yet done so, please read up on Software in particular, the Coding Standards! These will be necessary to actually do any development on the car. It is also recommended that you spend some time working with the MSP430 launchpads which were part of the architecture from the previous vehicle MSXI and will provide a good basis for getting started. 

Architecture and Libraries

The architecture we will be using on MSXII is the stm32f0xx variant of the ARM Cortex M0 MCU. This architecture is supported by both the CMSIS ARM Core M0 Library and STM Peripherals Library. Specific documentation for these libraries can be found on the Software Resources page of confluence. 

Supported Development Toolchain

Compiler

...

A compiler builds human readable source code into a machine readable target language, usually a machine executable or binary for a specific architecture. GCC ARM compiles C code into machine readable .elf, .hex or .bin files which can be flashed onto the MCU. GCC ARM

...

 is the standard open source compiler for ARM architecture, which is also what we're using. Compilers are powerful and often catch typos, errors, and warnings; they also optimize code for efficiency or size. The compiler flags set these

...

behaviours of the compiler.

Build Tools

...

Build tools usually instruct the compiler on where the source files it is building are located and which files to look at in order to build the target program. Often a Linker will be used with a Makefile to build a collection of C and header files into a standard library which can be included in your program. GNU Make

...

 and GNU Linker (aka ld) are long-standing open source standard build tools used by many developers (including us!), although many alternatives do exist.

Linter

...

A linter is a program that checks the style of source code for errors. Some linters also

...

perform static analysis, ours does not, which look to catch programming errors before the code is executed. cpplint

...

 is Google's open source linter for C/C++ programs, note that our Coding Standards closely follow Google's and as a result, this linter works well for us. The linter has been modified to support some slightly different standards and will be less pedantic.

Flasher

...

A flasher will transfer firmware (our compiled program) onto the MCU. Typically, this is done with a special cable or by a chip on the PCB and requires flashing software to transfer the contents of the source code into the memory of the MCU. For our purposes, we will be using st-link

...

 with GDB

...

 for debug which is the chip manufacturer supported method, or OpenOCD

...

, the open source

...

equivalent.

...

• Anyone just starting out and especially those using Windows are strongly encouraged to use the Eclipse IDE which is one of the few ways to get a working Toolchain on a Windows machine. Note that we will not be supporting any issues you may encounter using other methods on Windows although, we will also support Linux if you want a VM or dual boot but you will need to figure out the install on your own. 

...

IDE

Just about any text editor is supported, since you can perform builds and flashing via the Vagrant box, using the shared/ directory between your host operating system and the Vagrant image.

Some recommendations that core members like include Vim, Sublime Text and Visual Studio Code.

Source Control

We use GitHub for our source and versioning control. In order to contribute to the codebase, you will also need to start using GitHub. If you are new to GitHub you may want to check out

...

these guides. We have tight controls on out git repositories and require all commits to come from pull requests and that they are squashed prior to submitting

...

.

Installation

General Instructions:

Step 1: If you don't already have one, get a GitHub account!

Step 2: Join our GitHub organization uw-midsun

Step 3: Follow your system specific instructions below

Windows:

Word of Warning: This install is probably the most painful and likely to break/not work do your best and if you get stuck just ask

Step 1: Download and install Eclipse this will require at minimum a JRE or JDK version 1.7.0 or higher. I had issues with the x86 or 64 bit install so you may want to consider something just installing the x64 or 32 bit version first. Also note: when you get to the Eclipse installer you only need the C/C++ version of Eclipse.

Step 2: Follow this guide to install the correct build tools and the GCC ARM compiler and set them up in your environment. 

Step 3: Install Python version 2.7 you will need to add it to your environment path so that the Makefile runs the lint correctly.

Step 4: In theory that should be everything. Try it by cloning a copy of the template from here and building it in Eclipse. If you can't build then you may have to use bash for Windows 10 to build (goto step 6).

If building in Eclipse works for you then you can stop here. Note that linting may require you to use Powershell of bash for Windows and run the command "python cpplint.py <path to file(s)>" in the project-template directory.

Step 5: Follow this guide to set up bash for Windows 10. If you don't have Windows 10 I suggest getting a Linux VM at this point.

Step 6: Goto step 1 of the Linux guide and follow it (I only needed to install gcc-arm-none-eabi and make). You can skip step 4 as Bash for Windows does not support usb interfaces. You will have to debug from Eclipse. 

Step 7: Run make and watch success happen (I almost guarantee this will work).

Congrats if you made it this far without actually dual-booting or getting a Linux VM!

Linux:

In theory, this is the easiest install method. For that reason, those interested in running a VM or dual-booting their machine to get Linux are welcome to do so. Although, we don't explicitly support either we can probably provide guidance if you get really stuck. However, if you break anything doing it we are not liable!

This step by step is currently for Ubuntu adjust to your system as needed

Step 1: Install 32 bit C libraries and some of the build tools if you don't have them. There may be more if you aren't on Ubuntu (if you are on Arch you many need all of multilib :'( )

$ sudo apt-get -y install lib32ncurses5 gdb python2 gcc-arm-none-eabi

Python may be called python or python2 or python2.7 depending on your distro.

Step 2: If you weren't able to download the gcc toolchain download, unpack and install the GCC ARM Linux tarball from here. Add Python 2.7 to your ~/.bashrc or ~/.bash_profile if is isn't already in your PATH. Also give is the bash alias python2 if it isn't already accessible under that name.

Step 4: Install st-link or OpenOCD, they may be in your package repository but you can always build from source. 

Step 5: In theory that is everything, assuming your distribution is sane and already has make installed. Grab an IDE or text editor if you don't already have one you like. The link in step 2 of the Windows guide has a tutorial for setting up Eclipse if that is your preferred IDE.

Step 6: Try cloning a copy of the template from here and building it by navigating to the directory and typing 

$ make

If it compiles you did everything right (except perhaps the linter (check this by running make lint) if not you need to fix or add something. You should produce a file called main.elf.

Mac OS X:

All this has been tested on a Virtual Machine running El Capitan.

Step 1: Follow the commands on this site to install brew.

Step 2: Install gcc-arm-embedded using brew

brew cask install gcc-arm-embedded

Step 3: If you have Python 3 installed (or Python 2 is called via python), alias python2.7 to python2.

alias python2='/usr/bin/python2.7'

You should probably add this to your ~/.bash_profile or ~/.bashrc, depending on how you configure your bash variables.

Step 4: Try cloning a copy of the template from here and building it by navigating to the directory and typing 

$ make

If it compiles, you did everything right (except perhaps the linter (check this by running make lint) if not you need to fix or add something. You should produce a file called main.elf.

Project Template

The package template contains seven directories, a Makefile, a linter and a README. Use this for starting new projects only. Existing projects will have their own repositories which will share a copy of libraries, linker, and extra. 

Linting

As mentioned linting checks to ensure code meets our style guides. A custom version of cpplint.py is included in the package template it has been altered to support our styleguide. Calder Kitagawa is the maintainer so if you think there is a bug or style violation it is too pedantic/permissive reach out and ask. A Git hook will prevent you from pushing any code with errors so lint often you don't want to rewrite a whole file just because you messed up on style! The Git Hook in the hooks directory should be copied into .git/hooks directory so that you auto-lint when you submit code.

$ make lint
OR
$ python cpplint.py <file(s)>
OR
$ python2 cpplint.py <file(s)>

Running make lint executes cpplint on all files in src and inc. If you want to just lint specific files use python cpplint. Note the cpplint will accept wildcards in the file definitions.

Makefile

As mentioned, a Makefile tells the compiler what to build and where to find those items. This Makefile is no different, it automatically links and builds a file called main.elf and the STM Peripheral library (THIS LIBRAY FEATURES A HAL DO NOT USE IT WE ARE MAKING OUR OWN) which is located in the libraries directory. The libraries can be included without needing a relative path as can any header files you write and place in the inc directory. The linker directory contains the linker files to build the libraries. The extra folder contains configuration options for making an OpenOCD binary. Any program files you create should go in the src directory and any drivers should go into inc. The README will contain more detailed information and the Makefile does have options for selecting source files.

Usage (Linux and OSX)

$ make

Builds the package assuming it isn't built already or modified

$ make all

Same as make

$ make clean

Removes the .elf, .map and .bin files from the bin folder of the package

$ make reallyclean

In addition to doing what make clean does it also cleans the library from the /libraries driectory

$ make program

...

Dependencies

These are dependencies installed on our current VM: https://app.vagrantup.com/uwmidsun/boxes/box

• GCC ARM Embedded version (6.3.1 20170620)
• GNU Make 4.0 or above
• Unity-Throw the Switch: C Testing Framework
• Clang/LLVM Toolchain
  
• Bear (Build EAR)
• Golang
• OpenOCD
• Ruby
• Tmux
• Git
• Yarn
• Typescript
• Node
  
• Sass