Docker Images

Instead of installing ROS2 and the CPM Lab on your computer, you can use one of the Docker images. You build them on your computer from their repositories; they are not published in a registry. They contain ROS2 Jazzy, Lanelet2 and the CPM Lab Debian packages, and build on amd64 and arm64 hosts. The simulation image uses CycloneDDS, which is enough for simulations; the desktop image uses Zenoh like the muCars, see Middleware.

Image	Content	Use case
Simulation	ROS2 desktop, Lanelet2 and the CPM Lab packages	Simulations and developing your own motion planner on your computer, without lab hardware.
Desktop	Everything of the simulation image, plus the indoor positioning system, `cpm_calibrate` and the Basler pylon SDK	Running the physical lab, e.g. for demonstrations on the central workstation, with access to the IPS camera and other USB devices.

Note

The images are meant for Linux hosts. The helper scripts pass the X server of the host into the container for RViz and the other GUI tools. On macOS, use the image with Lichtblick instead of RViz; on Windows, use WSL 2. See Student Setup.

Prerequisites

Docker Engine on a Linux host. Add your user to the docker group, so you can run Docker without sudo.
git to clone the image repository, which contains the Dockerfile and the helper scripts, and an SSH key in your RWTH GitLab account. The repositories are cloned via SSH only.
An X server for GUI tools, i.e. a Linux desktop session.

Simulation Image

Clone the repository with the helper scripts:

git clone git@git.rwth-aachen.de:CPM/Project/Lab/ros2/docker/simulation.git
cd simulation

Build the image and open a terminal in it. The first build takes a while:
```
./make-image.bash
./run-terminal.bash
```

Inside the container, start the lab as described in First Simulation:

export ROS_DOMAIN_ID=21
ros2 launch cpm_lab cpm_lab_rviz.launch.xml

run-terminal.bash starts the container as follows:

Workspace: the cloned repository is mounted as /workspace. Put your own packages into /workspace/src and build them with colcon build inside the container; build/, install/ and log/ are ignored by git.
User data: ~/cpm_lab of the host, or $CPM_LAB_HOME if it is set, is mounted as /cpm_lab and CPM_LAB_HOME points to it. Experiment recordings, calibrations and your own maps and IPS configurations are therefore kept on the host, see Recording and Evaluating Experiments. Everything else outside /workspace is lost when the container exits.
User: the container runs as your host user, so files in /workspace belong to you.
Network: the container uses the host network and IPC namespace, so ROS2 nodes in the container talk to nodes on the host and in the lab network.
Graphics: the X server and /dev/dri of the host are passed through for hardware-accelerated rendering.

Open as many terminals as you need by running run-terminal.bash again, e.g. one for the lab and one for your external motion planner, see Your First Motion Planner.

Tip

Source your workspace in every terminal before starting the lab, so the control flow lists your planner:

cd /workspace
colcon build --symlink-install
source install/setup.bash

Desktop Image

The desktop image is used on the computer that runs the physical lab, usually the central workstation. Set up the central workstation and the IPS camera first, see Central Workstation and Indoor Positioning System.

Basler USB 3 cameras need a larger USB buffer than the Linux default. Set it on the host once until the next reboot, or permanently with the kernel parameter usbcore.usbfs_memory_mb=1000:
```
echo 1000 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb
```

Clone the repository with the helper scripts:

git clone git@git.rwth-aachen.de:CPM/Project/Lab/ros2/docker/desktop.git
cd desktop

Build the image and open a terminal in it:
```
./make-image.bash
./run-terminal.bash
```

Check that the IPS camera is visible in the container:

lsusb | grep -i basler
/opt/pylon/bin/pylonviewer

Start the Zenoh router, unless it already runs on the workstation, then the lab, and follow the checklist in Experiments with Real Vehicles:
```
ros2 run rmw_zenoh_cpp rmw_zenohd &
export ROS_DOMAIN_ID=21
ros2 launch cpm_lab cpm_lab_rviz.launch.xml
```
In the Control Center, start the IPS with the configuration of your lab.

run-terminal.bash of the desktop image differs from the simulation image:

Privileged and root: the container runs privileged and as root, and /dev of the host is mounted. The IPS camera and other USB devices are accessible, also when they are connected after the container started. Files created in /workspace belong to root.
User data: ~/cpm_lab of the host, or $CPM_LAB_HOME if it is set, is mounted as /root/cpm_lab. The experiment recordings, IPS calibrations and your own maps and IPS configurations are therefore kept on the host, see Recording and Evaluating Experiments.
Middleware: Zenoh (rmw_zenoh_cpp) instead of CycloneDDS, as on the muCars.

Calibrate the IPS camera inside the container with cpm_calibrate, see IPS Camera Calibration. The results are written to ~/cpm_lab/calibrations on the host.

Warning

A privileged container has full access to the host’s devices. Only use the desktop image on the lab computers and only with images built from the CPM Lab desktop repository.

Image Versions

make-image.bash builds the image of the checked-out commit with the newest CPM Lab packages from the CPM apt server. To update an image, pull the repository and build it again:

git pull
./make-image.bash

To reproduce the software of an experiment, build the image of a release and pin the CPM Lab packages to it:

git checkout 0.3.0
./make-image.bash --build-arg CPM_LAB_VERSION=0.3.0

To change an image, edit the Dockerfile in its repository and build it with make-image.bash.

Note

The images contain the released CPM Lab packages. To develop the CPM Lab itself in Docker, use the make targets or the VS Code dev container of the workspace repository instead, see its README.md and Command Reference.