Computer Setup

Owned by Orson Marmon
Last updated: Jan 21, 2023 by Keyon Jerome
8 min read

Ubuntu 20.04 Install (Preferred)

On the software team, the operating system we use is Ubuntu 20.04. Ubuntu is a popular Linux distribution that supports ROS2, a robotics framework that is at the core of our architecture. There is also the option of using ROS on WSL (Windows Subsystem for Linux) without any gui compatibility(rviz, rqt, etc). We will not provide any support to you using ROS2 on anything other than an Ubuntu 20.04 installation (maybe windows).

Ubuntu can be installed in one of two ways: Dual Booting, or Virtual Machine. Dual Booting involves adding a partition to your computer’s hard drive and installing Ubuntu on the new partition. This allows you to run both your original OS and Ubuntu on your computer natively and can take advantage of your full laptop hardware (CPU cores, GPU, ports, etc). This is the strongly preferred method, but the process of dual booting has some risks associated with it (a mistake could wipe your main OS). Be sure to backup all your important files before proceeding with a dual-boot setup. A Virtual Machine involves running a guest OS, such as Ubuntu, virtually within a host OS, such as Windows or Mac. This is risk-free, but VM’s often suffer from poor performance, especially when using ROS. VM’s typically cannot take advantage of your GPU, and external ports and interfaces do not always work properly. Additionally, we have found that some computers refuse to cooperate with VM’s. 

Assuming that you can get a VM set up, this training is equally doable on either a dual-booted PC or in a VM. However, due to the drawbacks of VM’s, it is preferred that all members who are committed to working on the team use dual boot, as it will help productivity in the long run. You can still get tasks using a VM, but the tasks we can give you will be limited.

Dual boot Setup (Preferred)

There are many tutorials online on how to dual boot a Windows PC with Ubuntu. The general procedure involves partitioning your hard drive, creating a bootable USB stick with a Ubuntu image, then rebooting into that USB stick and following the installation instructions. Here is a generic tutorial covering the process for Windows, although it may help to find a tutorial for your specific PC model:

The process for Mac computers is slightly more complicated, but still doable, as it requires installing a new boot manager as well. Here is a Mac tutorial:

https://www.lifewire.com/dual-boot-linux-and-mac-os-4125733

Some computer models won’t work perfectly right away (especially graphics cards) so you may have to do some extra setup. Below are some common models with special setup instructions

VM Setup (Alright, Probably Slow)

To install Ubuntu as a Virtual Machine, first install a Virtual Machine software. We recommend Virtual Box (https://www.virtualbox.org/wiki/Downloads) as it is free and works on all common OS’s. Once installed, download the Ubuntu 20.04 image from https://ubuntu.com/download/desktop and install it by following a tutorial for your VM software.

Once installed, ensure that your VM is working well (e.g. can connect to the internet, not too slow, etc). If the VM’s performance is very laggy, you may have to increase the RAM and number of cores dedicated to the VM (https://www.techrepublic.com/article/how-to-improve-virtualbox-guest-performance-in-five-steps/ , section 2)

Docker Setup (Windows 10/11, non-Ubuntu 20.04 Linux, MacOS) (Good)
 

Alternatively, you can also set up ROS2 using a virtualized system on your Windows, Linux, or MacOS machine. This is less risky than setting up dual boot, but slower than a dual boot, but much faster than a VM.

What is Docker?

Docker is an open source platform that enables developers to build, deploy, run, update and manage containers—standardized, executable components that combine application source code with the operating system libraries and dependencies required to run that code in any environment.

TL;DR: Docker lets you build images for your programs exactly the way you want them to be setup. You tell it what base image to use to create your image from (e.g: we want to use Ubuntu 20.04, so we might take the Ubuntu 20.04 image), and then inside a "Dockerfile", we'll pull in that image, and then install whatever we need to run our program via the traditional Linux commands. In our case, that's ROS2. These Dockerfiles are code files that describe which image to pull down to use, and then what commands to use to install whatever is needed for your program.

Then you build the Dockerfile into a new image with all the dependencies for your program. Next, you open up the image and run your code-- now that we're using the image, we'll call it a container. You interact with the container via a terminal on your laptop, just like you're SSHing into another computer.

These Docker containers traditionally don't allow GUI applications, but through a bit of work, we can get those going too :].

Windows for Docker Setup Instructions

  1. Install WSL2 on your computer. This is Windows Subsystem for Linux, which allows developers to run a Linux environment without a separate virtual machine or dual booting. It's used by Docker to run its backend. If you're on Windows 10 version 2004 and higher (Build 19041 and higher), visit this page; all you have to do is run one command in Windows Powershell! If you're on an older build, see these manual steps. 
  2. Install Docker Desktop via the instructions.
  3. Install VcXsrv, an application for the X Window System Display server. The X Window System Display server used by various operating systems for running their graphical applications. We'll VcXserv on Windows, and then we'll send all the graphical application traffic from our Docker container to our X server running on Windows, allowing us to run our graphical applications straight out of the box.
  4. We'll need to change the display number on VcXsrv to 0 so Docker knows where to find our server. Navigate to `C:\Program Files\VcXsrv`, or wherever you installed VcXsrv, and launch xlaunch.exe. In the display settings window, navigate to the bottom and change Display Number from -1 to 0, and hit next until you can close xlaunch.
  5. Make sure Docker Desktop is running before we continue. It usually runs in the background, so check your hidden icons (the up arrow in the bottom right of the Windows taskbar) to make sure you see the Docker icon in there. 
  6. From here, we're going to migrate to VSCode so you can develop properly. If you haven't already, install VSCode, then install the Dev Containers Extension.
  7. Create a folder on your computer for your UW Robotics team development–doesn't matter where it is, as long as you can access it quickly.
  8. Open up that folder in VSCode. Download and add our "Dockerfile.dev" file to that folder.
  9. Now, use Ctrl+Shift+P to open the Command Palette. In the Command Palette, search for and run "Dev Containers: Open Folder in Container". 
  10. VSCode will then ask you to open a folder–open the folder you created earlier for your UW Robotics team development. Then, it will ask you which Dockerfile you'd like to use for the container–choose the Dockerfile.dev file you downloaded before, which is in that folder.
  11. It will then create a "devcontainer.json" for you inside a ".devcontainer" folder, as well as build and open the container. The devcontainer.json file tells Docker how to build and run your container.
  12. We need to add a specific line to your newly created devcontainer.json. On the next available line, add the following data. Make sure to add any commas required (before or after the data) so the JSON is valid. 
        "containerEnv": { "DISPLAY": "host.docker.internal:0.0" }       
  13. Here is a completed devcontainer.json. 
  14. You'll need to save the file and restart your container for the change to your devcontainer.json. You can close the container by going in the bottom left in VSCode to the green icons/text, and clicking Close Remote Session. Then, do the same, but Rebuild Container.
  15. You are officially done! Let's go ahead and recap the instructions anytime you want to start coding in your container:
    1. Open Docker Desktop.
    2. Open VcXsrv (you may want to add the C:\Program Files\VcXsrv\xlaunch.exe file as a shortcut to your Start Menu or Desktop). 
    3. Once you've opened VcXsrv's Xlasunch, change the display number to 0, then hit next until you see Finish, and click that.
    4. Open VSCode.
    5. Use Ctrl+Shift+P to open the VSCode Command Palette.
    6. In the Command Palette, search for and run "Dev Containers: Open Folder in Container". 
    7. When prompted, open your UW Robotics team development folder.
    8. When prompted, use Dockerfile.dev as your development container. This container contains ROS2 Galactic running on Ubuntu 20.04!
    9. Done! When you want to run commands in your container, use Ctrl+` to open a terminal to your container. Anything you do inside the container will be reflected in your folder on your local machine.


Alternative Docker commands (kept for historical reasons).

  1. After step 5. Fantastic, you've installed everything you need to run Docker graphically! Next up, open Windows Powershell (as an administrator should help). Next, we're going to pull down and show you how to use a pre-built Ubuntu 20.04 image with ROS2 Foxy installed, so you can get going with the rest of the software training.
    1. Run docker pull osrf/ros:foxy-desktop in Powershell. This will download the image, straight from the Open Source Robotics Foundation (the people behind ROS). If you need ROS2 Galactic for post-training dev work, use osrf/ros-galactic-desktop.
    2. Next, we'll go ahead and run this image. Before we do this, we'll need to pass a lot of flags to the docker run command, so I'll explain them here:
      1. -v C:\Users\path\to\folder:/code/dev_ws the -v flag shares a folder from your host machine (your Windows computer) to the Docker container. In this example, we're mapping C:\Users\path\to\folder to /code/dev_ws in the container. Any changes made in the Docker container will be reflected on your folder on Windows, and any changes made to your folder on Windows will be reflected in the Docker container. This is incredibly useful, because now we can code on Windows but run and test on the container in Linux.
      2. -it runs the container with an interactive shell. If you didn't pass -it, the container would run in the background and you would have no way of interacting with it (unless you used docker exec later).
      3. -e sets an environment variable inside the Docker container. We'll be using this to tell the Ubuntu container where to send the graphical traffic via the DISPLAY environment variable.
      4. --name sets a name for the Docker container for use later. We'll call our Docker container uwrt_dev_container.
    3. Now, the actual docker run command you'll be using; please change the first path of the -v flag to an absolute path of wherever you plan on storing your ROS2 workspace. In this example, we're sharing our entire C:\Users\Owner\Documents\Code folder to the container:
      1.  docker run --name uwrt_dev_container -e DISPLAY=host.docker.internal:0.0 -it -v C:\Users\Owner\Documents\code:/code/dev_ws osrf/ros:foxy-desktop
    4. You should now be inside the Docker container! Feel free to look around by running any typical Linux commands. ROS2 Foxy (or Galactic, whichever you chose) is pre-installed in this container.
  2. Useful Docker commands from here out:
    1. Stopping the container: `docker stop container-name`
    2. Restarting the container after stopping: docker start container-name
    3. Pausing the container: docker pause container-name
    4. Unpausing the container: `docker pause container--name`
    5. Opening a new shell for the container: `docker exec -it <mycontainer> bash`


Windows Setup (Not Preferred)

With the upcoming development of ROS2 on windows, you are able to run ROS2 on windows. Although this method of setup is discouraged it can still be used. 

This link https://docs.ros.org/en/foxy/Installation/Windows-Install-Binary.html describes how to install ROS2 for windows. If you run into any issues Google is your best bet.