• Prerequisites
• Overview
• Low-level programming
• High-level programming
  • Download VSC and Docker
  • VSC setup
  • How to run it
  • USB devices in dev container
    • Windows USB setup
    • Linux USB setup
  • How to get a working VM
• What is all this stuff?
  • Why Linux
  • Why containers
  • Why git

You will need

• A personal computer (preferably a laptop so it is physically portable)
• A bit of storage space (a few GB)
  • You can purchase an external hard drive with 2 TB of space for under $50 if needed

Note: you may, at some point, need a terminal that is not embedded in VSCode. Git Bash is a common choice. Additionally, a Linux VM may come in handy, so those instructions remain on this page as optional.

The goal is to set you up to be able to write and run code using our software stack. It is divided into high-level programming and low-level programming.

For our low-level programming, all you need is an IDE to put code on a microcontroller.

For our high-level programming, rather than installing a virtual machine and each dependency manually, you only need

• an IDE (place for you to write code)
• Docker Desktop (a tool that lets you run that code as if you had a different computer) (Install this on your actually PC not the VM)
• The current Astrobotics repository (our codebase)

Note: this is the most basic software documentation. The intent is for anyone to be able to read it, use it, and learn from it. If that is not the case, we've failed. Please reach out to someone for help setting up, and then come back here to improve this page for the next person.

Download Visual Studio Code and download Docker Desktop for Mac, Windows, or Linux (Install these on your actually PC not the VM)

• Install remote development extension pack
  • Go to the extension manager (Ctrl + Shift + X)
  • Type "remote development"
  • Select the Microsoft one (ID ms-vscode-remote.vscode-remote-extensionpack)
  • Select install
• Clone repository in container volume
  • Open the command palette (Ctrl + Shift + P)
  • Type "clone repository in container volume" and select the Dev Containers one
  • Select the GitHub icon to search for "VTAstrobotics/" and the name of the repository, such as PHOENIX
  • Choose the main branch. You can (and should) switch branches later (in the container itself)
  • Wait.

Note: if the Docker daemon is not running, launch Docker Desktop and wait a few moments

After you've cloned, you'll be in a running container. Next time though, launch Docker Desktop and run the container. Now, in VSC, select Attach to Running Containers.

• Open the command palette (Ctrl + Shift + P)
• Type "Attach to Running Containers"

Important: Once you've finished, close VSCode to stop the container. Additionally, you must shut down Docker Engine through Docker Desktop (click the power button icon in the bottom-left corner) to reclaim your RAM. Otherwise, you are wasting resources and your computer will be slow!!

Windows sucks.

Now that we've established that basic fact of life, open PowerShell in Administrator mode by pressing Super + X and selecting "Windows Powershell (Admin)"

Type wsl --install to install WSL2. You will be prompted to create a username and password.

Now, follow these instructions to set up your WSL with a 3rd party app that allows Window's terrible software to actually use USB. I'll reproduce the steps basic steps below.

1. Download the .msi here.
2. Install it.
3. Connect a USB device, such as an Xbox controller.
4. In an administrator PS run usbipd list. You should see your device listed.
5. Run usbipd bind --busid followed by the bus id associated with your device listed previously. Mine was 1-2. You may need to add --force after your bus id.
6. Launch the dev container.
7. Finally, run usbipd attach --wsl --busid followed by the same bus id. You may need to unplug and replug your USB.
8. Verify the dev container has access to this device (you may try lsusb or similar).

Note: You will have to repeat steps 4, 6, 7 each time you reconnect a usb device, as it will have a unique bus id. For a new usb device, you'll have to repeat step 5 as well.

If you have a Linux host, you don't need to do anything. The devcontainer.json file should start the container with the appropriate flags to share USB devices.

Optional: This software lets you run other operating systems on top of your current one and tricks them into thinking they're a real computer.

• Download VMWare or a virtual machine platform of your choice.
  • Create a Broadcom account. https://support.broadcom.com/
  • Go to the VMWare download link above and click on download workstation. And sign in to your Broadcom account.
  • Click on the software menu or search for VMware Cloud Foundation on the My dashboard menu on your Broadcom account.
  • Click on VMware Workstation Pro from the right side.
  • Click the “VMware Workstation Pro 17.0 for Personal Use (Windows)” option.
  • Click the latest version available, for example, 17.5.2.
  • Check the “I agree” option to make the installer downloadable.
  • Click the Download button.
  • Click the download file of the VMWare workstation and give it some time to download.
  • Click the Next button. And click the Install button.
  • Click the Finish button.
  • Click the Yes button to restart the computer.
  • Choose the “Use VMware Workstation 17 for Personal Use” option.
  • Download.
• Download the 22.04 version of Ubuntu Desktop.
  • This is just like downloading Windows or MacOS. You are downloading an entire operating system, which can take a bit of time and space.
• Create a new VM using VMWare and select your operating system disk image (.iso)
• Click next until you hit install
  • Default settings are usually fine, but there may be some minor settings you have to change. Luckily, you can always change settings later.
  • If VMware is having trouble loading Ubuntu try disabling 3D graphics acceleration.
    • Settings can be changed by unchecking the 1. Accelerate 3D graphics box in Display option in settings.
  • NAT Adapter should be bridged and check the replicate box.
    • In case of Wi-Fi troubles. You can change the NAT adapter settings per this post (Edit->Virtual Network Editor, select Change Settings, select Yes, on VMnet0 select Automatic Settings... and deselect unnecessary adapters that may confuse your VM.

You should now have a fully functioning virtual machine!

Note: we don't recommend installing Docker Desktop because it doesn't play nicely with VMs. It's mostly just a GUI, but the CLI is plenty.

Note: you may find this Docker cheat sheet useful.

You then may choose to complete these steps in your VM. If you do, please follow the post-install Docker steps. That is, after you install Docker Engine (Docker Desktop has DE), run

sudo usermod -aG docker $USER

sudo chown "$USER":"$USER" /home/"$USER"/.docker -R

sudo chmod g+rwx "/home/$USER/.docker" -R

The goal of this section is to provide an intuition for this setup and to explain the need for all the software in this document.

As things get more complicated though, we need abstraction. That is the role of ROS: to help us live at a higher level of abstraction.

ROS (Robot Operating System) is just like Windows or MacOS for a robot. Like your OS, ROS is a management tool. It manages when a script ("node") runs ("spins") and facilitates inter-node communication.

To use ROS, we need to use a Linux distribution called Ubuntu. Technically, now they have a Windows-compatible version, but it's not viable. Linux has a steep learning curve, but it is worth it. Linux is an OS like Windows or Mac designed for programmers. It makes work as a programmer much faster and easier. Once you get used to it you won't want to go back.

To use Linux, your options are

1. Replace your OS with Ubuntu
2. Install Ubuntu on top of your OS (virtualization)

Unless you have multiple computers or are already experienced with Linux and have no need for Windows or MacOS-specific applications, the first option is not suitable. It will do more harm than good.

So we need to virtualize, either via a VM or a container.

A container is kind of like a virtual machine except it only virtualizes the software (OS and up). So your VM has pretend USB ports (to which your real USB port data can be forwarded), but a container just needs permission to use your real USB ports.

Containers are the better choice here because they are faster, use much less space, are more portable (meaning they can run on almost any device), and accelerate development.

For example, let's say after the software subteam is set up I create a feature that uses some new libraries and updates the versions of some current libraries. Then, I share my code with the rest of the software subteam.

Now nobody besides me can compile anymore because nobody else has those updated dependencies. Now the whole subteam has to figure out which libraries—and which versions—I used, then download and install them on top of figuring out the correct versions of their existing libraries.

There must be a solution to this. What if we all used the same machine? That way, when I share my code with you, I share the library updates I made, too.

We do this by putting the entire codebase in a container. You always have whatever dependencies you need because my updated code gave you my container, my machine.

So containers make the setup process infinitely quicker and easier on top of saving you from headaches in the long run.

Note: we actually need containers because the Jetson Nano, our main onboard computer, can't run any version of Ubuntu compatible with ROS2, but Docker allows us to containerize and run whatever version of Ubuntu we want. I don't fully understand why that works but running the same version of Ubuntu on the Jetson Nano doesn't. It's magic.

This is great, but how do you get the codebase with the container? And then how do you stay updated? How do you share your changes with the rest of the team?

Git is a version control software. Why re-explain the wheel? Read this short article on why version control is great.

Since it's so short, it doesn't get into branching, but it's critical for teamwork. This is how multiple people can edit the same file simultaneously without overwriting each other.

A branch gives you your own version of the codebase that you can change without affecting anyone else. Often, you'll make a branch for a specific feature, and when it's done, you'll merge and delete your branch. Everyone gets your changes once you've merged and they've pulled.

Of course, if you and I both change the same line of code in different branches, and then I merge my change to main, when you try to merge we will have two differing ideas on what that line should be. That's okay. We can resolve what's called merge conflicts.