Setting up Linux for the RSP course

1.1. Setting up Linux for the RSP course#

This course is designed to familiarize you with using Linux, C++ and ROS2. Working through the manuals therefore requires that students have access to a Linux-based operating system (Ubuntu in this course) available on their personal laptops/desktops, and also that they have the required C++ and ROS2 tools installed.

However, we realise it could be too daunting for a student to install Ubuntu natively on their laptops and install a bunch of software, without expecting them to even know the basics of Linux yet. Besides, the course instructors and teaching assistants are not able to act as tech support in case something goes wrong. Hopefully such students will become sufficiently familiar and experiences through this course that they can take on installing Linux later. Another problem is that everybody might use a different version of (Ubuntu) Linux, C++, and ROS2, making it difficult to provide support and help consistent instructions.

To simplify the process of teaching large student cohorts, and ensure everybody has a mostly similar experience which is relatively simple to setup, we have decided on the following setup:

  • If you do not have Linux already installed on your laptop, we provide a Virtual Machine[1] for Ubuntu Linux. The VM allows us to distribute a pre-configured software configuration in an easy to distribute format, which acts as-if you have access to a complete and separate computer running Ubuntu Linux. Using a VM also has the benefit that no invasive changes to your laptops or desktop computer is needed. You should use the provided VM to get support, see Section 1.1.1 for more information.

  • If you do have already have a modern version of Linux installed, e.g. via a “dual-boot”[2], you can keep using your Linux version without the VM. A big benefit of this setup is that it will give you the best performance, especially when working on the more complex ROS2 assignments. Your Linux version does not necessarily have to be Ubuntu, though we will assume you are working with Ubuntu throughout the manual. Again, we provide no instructions or support for setting up dual-boot.

  • We ask you to not install ROS2 on your Linux system, and it is also not installed in the VM we provide. Instead, we will use a different method to provide you with a pre-configured ROS2 setup using a tool called Singularity that you can use within any modern Linux installation (either via our VM or dual-boot). This will be explained in more detailed in Section 1.1.2.

1.1.1. Use the provided VM#

If you have not done so already, be sure to read the Robot Software Practicals - RO47003: Installation and Setup manual and follow the instructions given there.

A separate document is provided which discusses how to install and configure the virtual machine software we use. Refer to the Robot Software Practicals - RO47003: Installation and Setup manual for more information. Please carefully read it and follow the instructions given in it before starting with the exercises and assignments in this manual.

In terms of hardware, you will need a reasonably recent laptop with an x86-64 CPU (i.e. a “normal” Intel or AMD CPU; but NOT the new MacBook Air with M2 chip, NOT a Chromebook, etc. These use different CPU architecture which means that the software we provide will not run! A MacBook with an Intel x86 CPU is fine). A laptop with an Nvidia GPU would make the robot simulations towards the end of this course run even smoother.

Note

all practical sessions of Robot Software Practicals will be run in VMs this academic year. You will use the same VM for the Linux, C++ and ROS labs and the final assignment.

1.1.2. Using ROS with Singularity#

For the ROS exercises, you should not install ROS directly yourself! There are two reasons for this:

  • All exercises in this course require that you are working with ROS version “Humble”. We have provided a Virtual Machine with the correct version of Ubuntu, but on your own laptop you may also have a native Ubuntu installation that may not be that specific version, as this course attracts many students who may already be using different Ubuntu versions on their personal computers.

  • There are special installation requirements for the required Gazebo simulator, which will be used for the final assignment of this lab assignment, and for the final lab assignment of this course.

Instead, we use a tool called Singularity which allows us to share a whole Linux development environment in a single file, which can then be used on any Linux system with Singularity installed. The file containing the packaged environment is called a Singularity image, and we shall provide you with an image which contains an installation of Ubuntu OS plus all the required ROS and simulator tools needed for the assignment (and future lab sessions in the course). In other words, we can provide a unified development environment for everybody, independent of how you setup Linux. The Singularity image enables you to do the exercises as if the correct Ubuntu version with all the required ROS packages was installed on your computer. Therefore, the first step to getting started is to install Singularity tool, if needed, and test how to use it.

This chapter of the manual will help you setup (if still needed) and verify your Singularity installation, and show you how to use it to start a singularity shell from the provided image.

Important

For all exercises after this section, we will assume that any new terminal that you open, you would first use it to open a singularity shell as explained below. Only if you work in the singularity shell will you be able to access the ROS tools.

Note

For a real ROS project where you want to setup ROS on a new computer, you would pick an Ubuntu installation and a corresponding supported ROS version, e.g. Ubuntu 22.04 LTS and ROS Humble. You would then use the Ubuntu package manager to install the required ROS packages.

In case you ever need to install ROS 2 Humble Hawksbill on a new system yourself, you can check its installation instructions in the online documentation. Again, this is not needed for this course.

1.1.2.1. Setup Singularity#

All the instructions on how to setup the software required for the course were explained in Week 0 of the course, if you completed them, you should have everything correctly setup and one of the two following situations applies to you:

  • You are doing these assignments on your own computer in the Virtual Machine provided to you at the beginning of this course, as was discussed in Section 1.1.1. The provided VM already contains an installation of the correct version of Singularity.

  • You have a native Ubuntu (or other Linux) installation. Then you should have installed Singularity yourself, as explained in the Week’s 0 Setup manual.

In both cases please make sure you have downloaded and tested the required image.

1.1.2.2. Download the Singularity image#

By following the Week 0 Setup manual, you should already have downloaded the Singularity image for this course. You can verify this is the case by looking for a file with the name ro47003_humble_v8.sif in your Downloads or Documents directory (or perhaps some other directory on your VM).

If you have downloaded the Singularity image file already, you can immediately continue to Section 1.1.2.3.

Tip

If you don’t have this file already in your Ubuntu installation, please download it now. Use the link in the setup manual on Brightspace to download it.

1.1.2.3. Verify Singularity installation#

To verify the Singularity installation, we can check Singularity’s version with the following command:

$ singularity --version

This should output something like:

singularity-ce version 4.3.1-XXX

If you are not using the VM and have installed a different version of Singularity, this may show a different version string. You should however always be using at least version 4.3.1 (or a version <5.x) of Singularity.

1.1.2.4. Using Singularity#

Now that Singularity is installed and that you have downloaded the image, we can practice how to use it. To invoke a Singularity shell, open a new terminal window and type the following command:

$ singularity shell /path/to/ro47003_humble_v8.sif

Note

  • The last argument should be the path to the Singularity image, so make sure you replace the /path/to/ part by the path where you stored the image, e.g. ~/Downloads/, otherwise singularity will not find the image. If you downloaded the image on your own PC, adjust the path accordingly in the exercises below.

  • If you are using a native or dual-boot Linux installation and have an NVidia video card (with the NVidia proprietary drivers installed), you must add the --nv argument (note that there are two dashes in front of nv) to the singularity shell command. The full command would then read:

    $ singularity shell --nv /path/to/ro47003_humble_v8.sif

    This will allow programs running inside the Singularity session to access your 3D graphics hardware, which will become important when running RViz and Gazebo later.

If the Singularity shell correctly started, you will see that the bash prompt changed, now contains the text Singularity, and ends with a > instead of the normal $.

Now in the singularity shell, enter the following command:

$ gazebo --version

You should see the following output:

Gazebo multi-robot simulator, version 11.10.2
Copyright (C) 2012 Open Source Robotics Foundation.
Released under the Apache 2 License.
http://gazebosim.org

Exercise 1.1

Start a Singularity bash shell by opening a terminal and running (Again: always add the --nv command line argument if appropriate for your computer. See the previous note about this.):

$ singularity shell /path/to/ro47003_humble_v8.sif

Note that you should not run this command with sudo. If the Singularity shell correctly started, you will see that the bash prompt changed, and now contains the text Singularity. All commands you would now execute are run by the virtual OS from within the container. Terminate the Singularity bash shell by either typing exit, or pressing Ctrl+D. You should now be back in your normal Bash shell.

Within the Singularity shell, the Linux file system is changed to that of the virtual OS installed in the image. However, your Home directory remains unaffected.

Exercise 1.2

Before running a Singularity shell again, execute the following command in your terminal: ls /opt Which directories are listed? Do you see any directory with the name ros? Now start the Singularity shell as before (check that the prompt states Singularity), and run ls /opt again. What has changed? Does it have a directory with the name ros?

Exercise 1.3

Open a terminal without running a Singularity shell. Then open another terminal in which you do run the Singularity shell. Keep both terminals open. In both terminals, run ls /opt. Does the fact that Singularity is running in one terminal affect the other terminal in terms of files and directories being accessible?

As you can see, Singularity does not change anything directly on your normal OS install. The virtual OS and its ROS packages are only visible within the terminal that runs Singularity.

Exercise 1.4

Run the following command: ls ~

What files and directories are listed? Now run the Singularity shell again as you did before. Within the container, run ls ~ again. Do you have access to all your files and directories in your home directory?

Exercise 1.5

From the previous exercises, what can you conclude about the visibility of files and directories from within Singularity?

1.1.2.5. Setting up Singularity for use with Terminator#

Close all terminals from the previous exercises. In this terminal, start a Singularity shell (just like you did before).

Within this Singularity shell, run the command terminator -u (note the -u flag). A new Terminator terminal will appear running Bash. You may see an error message about a non-existent configuration file, but you can ignore this.

Exercise 1.6

Note that this terminal is running from within the Singularity container. How can you tell?

A useful feature of terminator is that you can easily start new Bash instances in split windows in separate tabs. From within terminator, try using the keyboard combination Ctrl + Shift + T to open a new tab. All Bash instances started by terminator are its child processes and therefore also running inside the Singularity container! Use this to your advantage when you need multiple terminals within a Singularity shell.

Exercise 1.7

For convenience, you can create a Bash alias run_singularity to start the Singularity shell. Take a look at the Linux manual if you do not remember how to do this. Use this alias to your advantage to avoid retyping the full Singularity command in future exercises and assignments.

Contents