Using ROS with Singularity

1.1. Using ROS with Singularity#

For the exercises of this Robot Software Practicals lab session, 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 have prepared a Singularity 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). With Singularity, we can provide a unified development environment for everybody. 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 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 Jammy Jellyfish 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.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. Then VM has 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.1.1. 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_v7.sif in your Downloads or Documents directory (or perhaps some other directory on your VM).

If you do have the Singularity image file already, you can immediately continue to Section 1.1.1.2.

Warning

After testing the assignments, we have updated the Singularity image to a new version to fix some missing dependencies. Please do not use the old ro47003_humble_v6 image, but download ro47003_humble_v7 instead!

You can do this by opening a browser in your Ubuntu system (if you are using a VM open the Firefox browser on Ubuntu within that VM) and go to the following URL:

https://surfdrive.surf.nl/files/index.php/s/PeR3mwCCXVv0xRT

Download the Singularity image ro47003_humble_v7.sif (~1.2 GB), and make sure you store it in the ~/Downloads folder of your Ubuntu system.

For those who use Ubuntu in a VM, you can alternatively download this .sif file using your normal browser on your “host” OS (Windows or Mac), and then copy it into the VM. Open a file explorer on your host computer, and navigate to where you downloaded the .sif file. In the VM also open a file explorer and navigate to the Downloads directory in your home directory. Select the .sif file in your host’s explorer and press CTRL-C (copy), the click on your VM’s explorer and press CTRL-V (paste). If you get a popup with warnings at this stage, press skip all.

Warning

Do not open the Singularity image with the Disk Image Mounter for Windows, Mac or Linux!

1.1.1.2. 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 3.11.4-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 3.11 or a version 4.x of Singularity.

1.1.2. 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_v7.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_v7.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_v7.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.3. 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.