Prerequisites

To set up the development environment, you need to install the following tools.

Vagrant: a tool for managing and configuring Virtual Machines. Download the latest distro of Vagrant here
VirtualBox: Download VirtualBox 7.0. You need both the main application and the "Oracle VM VirtualBox Extension Pack", available here. Check that the versions are the same 😉
Git: make sure to go on Github and create an account.

Installation

The idea is that Vagrant uses VirtualBox to provision a virtual machine for our pre-configured image, box. This virtual machine contains a fully integrated development environment, including everything you'll need to develop software for our team. Now open up a Git Bash window (on Windows) or a terminal window (on Mac), and run the following commands:

First, clone the repo:

# Clone the repo
git clone https://github.com/uw-midsun/box.git && cd box

Then, you will have to download our vagrant box:

# Download and load the vagrant box
vagrant up && vagrant reload

Now ssh into the box.

# Access the box
vagrant ssh

Be sure you have the prerequisites installed! Each link should bring you directly to the proper download page.

Congratulations! If you're now at a prompt that says something along the lines of vagrant@midsunbox, you're in our development environment.

We expose a shared folder between your host operating system and the virtual environment, located at box/shared to allow you to use your favorite text editor from your host operating system.

# You should still be ssh'd into the box
# Check with whoami - it should say "vagrant"
whoami
# Access the shared folder - found at box/shared
cd ~/shared
# Clone the firmware repo
git clone https://github.com/uw-midsun/fwxv.git && cd fwxv
# Try to build the firmware (if you are on Apple Silicon, ignore this) 
scons

Note: You will need to setup an ssh key to access github with your account.

If you have already performed git clone with https, you can alternatively set up a token to be able to push any changes to our repo and you will need to enter this token in replacement of your password each time you push.

If you are setting up fresh, you need to use an ssh key to link your account. To learn how to add an ssh key you can run run the following commands in vagrant. Then, make sure to link it to your Github account.

# Create an ssh key
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press enter to save at default location, and enter again to use no passphrase

# Add your ssh key to the ssh agent
eval "$(ssh-agent -s)"

# Add all keys to the ssh agent
ssh-add

Also, if you have already performed git clone with https, you can switch to ssh by performing the command below. If you don't, you will constantly be prompted for your user/token still even if you've already added your ssh key and linked it to your Github account.

# Make sure you are in the git repo
cd fwxv

# Switch from https to ssh
git remote set-url origin git@github.com:uw-midsun/fwxv.git

While we're at it, let's configure some settings (while still in our vagrant box):

# Configure git
git config --global user.name "Your Name"
git config --global user.email youremail@example.com

git config --global push.default simple
git config --global core.autocrlf input

# Make sure that pylint is up to date so that the hooks don't fail, and install autopep8 for Python formatting
pip3 install pylint autopep8

# Make sure virtualenv is installed so Python dependencies get properly installed
sudo pip3 install virtualenv

Please use the email that's associated with your GitHub account.

YOU ARE FINISHED HERE

Update existing box

Only worry about this if you had the old box previously

to update existing boxes to ubuntu-20.04, navigate to your box folder

get the new box from the ubuntu-20.04 branch

git fetch && git checkout ubuntu-20.04

you might also need to destroy the old box

vagrant halt
vagrant destroy
vagrant up

after you ssh into the new box, you should see this message

Welcome to Ubuntu 20.04.3 LTS

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

 * Super-optimized for small spaces - read how we shrank the memory
   footprint of MicroK8s to make it the smallest full K8s around.

   https://ubuntu.com/blog/microk8s-memory-optimisation

if your message lists a ubuntu version other than 20.04, I don't know what happened, message ShiCheng on slack and we'll figure it out.

After updating the box, you may need to reconfigure your git configurations, follow the steps above.

Usage

# Bring up the virtual machine
# This step is only necessary after a reboot
vagrant up
# Access the box
vagrant ssh
# Move to the fwxv folder
cd shared/fwxv
# See https://github.com/uw-midsun/fwxv #usage for some common commands
make [cmd] ...

# To exit the virtual machine press CTRL + D
# Stop the virtual machine
vagrant halt

You're done! From now on, we'll assume you're using our development environment.

Now at this point you are ready to move onto the Firmware Tutorial!

FAQ

Q: I've cloned the firmware repo and I'm in the directory, but I can't build it.

A: Are you sure you've actually entered Vagrant's virtual machine? Running whoami should print vagrant if you're in our development environment. Remember that all Vagrant just provisions a virtual machine, and you still need to ssh into it to actually access it! Treat it like another computer on the network.

Q: How do I use vagrant? When do I use it?

A: Since vagrant is actually just a virtual machine (in this case, running Ubuntu), it's no different than sshing into a Linux computer on the network. vagrant up just launches the VM and vagrant ssh just connects you to it. Whenever you're developing firmware, you should be sshed into the vagrant box.

Q: What is make? Is it related to vagrant?

A: Make is actually a standard GNU tool for designing build systems! It parses our Makefile so it knows what to do when you run commands such as make build_all or make lint. Vagrant just allows us to provide a pre-configured virtual machine with all the dependencies our build system needs, Make included.

Q: The VM takes forever to load then gives a timeout error.

A: Try going in to your computer’s BIOS, ensure the virtualization is enabled, then run vagrant destroy and vagrant up again (Credit to Micah Black).

Q: How do I edit code? can I use an IDE or do I have to use vim?

A: Don't worry, you don't have to use vim unless you really want to! Since we use a shared folder, both the box and your computer can access its contents. As long as you keep your code in there like in the instructions, you're able to access that folder from your computer and use whatever text editor / code editor / IDE you want.

Q: I upgraded to Big Sur after installing, and it doesn't work! Does this not work for Big Sur? (Likely applies to future MacOS updates, Big Sur is currently the latest as of writing this)

A: It works for Big Sur! Upgrading operating systems for Mac doesn't seem to transfer the permissions for VirtualBox properly, so you may need to re-install VirtualBox in order to gain the prompt to come up in System Preferences > Security & Privacy. Once installed, you will need to click "Allow" to give Oracle Virtual Box the proper permissions. Note: to uninstall VirtualBox and Vagrant, just download the latest version (see the links at the top of the page), and it should come with an uninstall tool.

Browser not supported