Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Update installation instructions for vagrant

...

  • Compiler: GCC ARM
    • 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. Compilers are powerful and often catch typos, errors, and warnings; they also optimize code for efficiency or size. The compiler flags set these behaviors of the compiler.
  • Build Tools: GNU Make and GNU Linker aka ld
    • 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 Linker are long-standing open source standard build tools used by many developers, although many alternatives do exist.
  • Linter: cpplint (modified)
    • 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: st-link/GDB or OpenOCD
    • 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 version.
  • IDEs: Eclipse or any text editor (Core members like: Vim, Sublime Text and Visual Studio Code)
    • 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. 
  • Source Control: GitHub
    • 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. We are also now using Git Hooks, for now these will be run locally but web hooks may be enforced.

Installation

General Instructions:

Step 1: If you don't already have one, get a GitHub account!Step 2: Join GitHub account, and join our GitHub organization uw-midsun.

Step 3: Download Vagrant and Virtual Box

Step 4: Install the Vagrant image

Step 5: Start the Vagrant box

Code Block
themeConfluence
$ vagrant up 

(this may take a while) and

Code Block
themeConfluence
$ vagrant ssh 

into the box

Step 6: Change directory into the firmware folder 

Code Block
themeConfluence
$ cd ~/env/firmware

Step 7: Run make 

Optional: learn more bash shell commands if you wantNote: 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

Using Git Bash, clone the box repository somewhere

Code Block
languagebash
themeConfluence
git clone https://github.com/uw-midsun/box.git && cd box/

Then start the box using

Code Block
languagebash
themeConfluence
vagrant up && vagrant reload

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

Then, to access the box, ssh in

Code Block
languagebash
themeConfluence
vagrant ssh 

These 3 commands only need to be run the first time you start working with uwmidsun/box.

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

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

Then, ensure that you can build the code using make

Code Block
languagebash
themeConfluence
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

First, make sure git is installed

Code Block
languagebash
themeConfluence
brew install git

Then clone the uw-midsun/box repository somewhere

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

And start the box using

Code Block
themeConfluence
vagrant up && vagrant reload

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

Then, to access the box, ssh in

Code Block
themeConfluence
vagrant ssh

These 3 commands only need to be run the first time you start working with uwmidsun/box.

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

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

Then, ensure that you can build the code using make

Code Block
languagebash
themeConfluence
make build_all

Linux

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

Prerequisites

Make sure git is installed

Code Block
themeConfluence
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.

Code Block
themeConfluence
sudo usermod -a -G vboxusers $USER

Now reboot your machine.

Then clone the uw-midsun/box somewhere

Code Block
languagebash
themeConfluence
git clone https://github.com/uw-midsun/box.git && cd box/

And start the box using

Code Block
languagebash
themeConfluence
vagrant up && vagrant reload

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

Then, to access the box, ssh in

Code Block
languagebash
themeConfluence
vagrant ssh 

These 3 commands only need to be run the first time you start working with uwmidsun/box.

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

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

Then, ensure that you can build the code using make

Code Block
languagebash
themeConfluence
make build_all

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. 

...