Real-time programming with ROS 2

This is the repository for the Real-time programming with ROS 2 workshop for ROScon 2023.

Thank you to Shuhao Wu, Jan Staschlat, Stephanie Eng and Oren Bell for putting together the excellent workshop. Slides available here (backup link). Thank you all for attending!

Workshop setup for laptops

To get the most out of the workshop, please complete the setup instructions for your laptop ahead of time. This will take about 10-20 minutes of your time and hopefully will make the workshop go significantly smoother. If you run into any problems, please file an issue in this repository.

System requirements

The workshop code only supports Linux. Officially, we only test Ubuntu 22.04 as the laptop/development operating system. However, with the Docker setup described below, it may be possible to run this on other Linux variants, although this is untested.

A real-time kernel is not necessary, although you may see decreased maximum latency numbers if you have a real-time kernel. For reference, the workshop code is developed on regular Ubuntu kernels.

Docker for Mac and Docker for Windows are not supported. Please try to bring a Linux laptop to the workshop for best results.. It is possible that a virtual machine running on Linux may work for you, although this is also not supported.

Podman is not supported. It might work, but we have not tested the Docker setup below with Podman.

The code is tested on both amd64 and arm64 (via the Raspberry Pi 4). No tests are made against the M1/M2 Macbooks.

Using Docker

The simplest way to run the workshop code is to use the workshop-specific Docker image. To get the Docker image, there are two options: (1) getting the image before the workshop (highly recommended), or (2) getting the image during the workshop (we cannot guarantee this experience will be good due to constraints of networking during a conference).

Before getting the image, you must install Docker Engine on your Linux machine. Please follow the Docker Engine installation instructions. Ensure you do not use Docker Desktop as that is not supported due to its use of a virtual machine. At the end, you should confirm that you see the following output when running the following commands:

$ docker version | grep -A2 Client
Client: Docker Engine - Community
 Version:           24.0.6
 API version:       1.43

$ docker version | grep -A2 Server
Server: Docker Engine - Community
 Engine:
  Version:          24.0.6

The exact version of Docker may be different than the above output.

You must also install Docker such that you can manage docker without root. See the instruction here for details.

Getting the image BEFORE the workshop

1. Download the image file from the latest release. The file is called docker-image.tar.gz.
2. Clone the roscon-2023-realtime-workshop repository with --recursive option: git clone --recursive https://github.com/ros-realtime/roscon-2023-realtime-workshop.git.
3. cd into the roscon-2023-realtime-workshop repository.
4. docker/fetch ~/Downloads/docker-image.tar.gz.

This should import the Docker image with a name of roscon-2023-realtime-workshop.

Note: do NOT use docker import or docker load. Please use the docker/fetch script above.

Starting the Docker container

If you would like to use VS Code and its dev container system, you can skip this section and go directly to Using Visual Studio Code.

After importing the Docker image, you can start the Docker container via the special shell file docker/start:

1. cd into this repository.
2. docker/start

This should start the Docker container and it will mount this repository into the /code directory inside the container. As a result, changes to the repository in the host will be reflected in the container.

This should start the Docker container with all of the appropriate privileges to run real-time-scheduled applications. It also setup the container with everything needed to run GUI programs.

File truncated at 100 lines see the full file