Student Setup

The CPM Lab runs on Ubuntu 24.04 with ROS2 Jazzy. Most students, however, work on Windows or macOS laptops. This page shows the setups that are used in our courses, so you can develop and run simulations on your own computer:

Your computer	Recommended setup	Notes
Ubuntu 24.04	Install the Debian packages directly, see Install from Debian Packages.	Best performance, everything works.
Windows	Ubuntu in WSL 2 or an Ubuntu Virtual Machine with the Debian packages.	WSL 2 is faster to set up; a VM is closer to a native installation.
macOS	Docker on macOS with the simulation image and Lichtblick.	RViz is not available, because macOS does not support X11 forwarding.
Any other Linux	The simulation Docker image, see Docker Images.	RViz works through the X server of the host.

All setups are sufficient for simulations and for writing your own motion planner. For experiments with the real vehicles, see Running Your Planner in the Lab. The real lab uses the Zenoh middleware, see Middleware.

Ubuntu Virtual Machine

A virtual machine (VM) runs a complete Ubuntu next to your operating system. Use for example VirtualBox or VMware Workstation on Windows and Linux, and UTM or VMware Fusion on Macs with Apple silicon.

Download the Ubuntu 24.04 Desktop image: amd64 for Intel and AMD computers, arm64 for Macs with Apple silicon.
Create a VM with at least 4 CPU cores, 8 GB RAM and 40 GB disk, and enable 3D acceleration if your software offers it. Install Ubuntu in the VM.
Install the CPM Lab inside the VM as described in Install from Debian Packages.
Start your first simulation, see First Simulation.

Network settings of the VM:

NAT (the default) is sufficient for simulations on your own computer.
Bridged puts the VM directly into the network of your computer. Use it to connect to the lab network, so your motion planner can talk to the lab.

Tip

If RViz shows a black window or crashes in the VM, disable hardware acceleration as described in the Troubleshooting Guide.

Ubuntu in WSL 2

The Windows Subsystem for Linux (WSL 2) runs Ubuntu directly in Windows. With WSLg, graphical applications such as RViz open as normal Windows windows. WSLg requires Windows 11 or Windows 10 build 19044 or newer.

Open PowerShell as administrator and install Ubuntu 24.04:
```
wsl --install -d Ubuntu-24.04
```
Restart Windows if asked, then open Ubuntu 24.04 from the start menu and create your Linux user.
Install the CPM Lab inside Ubuntu as described in Install from Debian Packages.
Start your first simulation, see First Simulation. RViz opens as a Windows window.

Your Windows drives are available under /mnt/c, but keep your ROS2 workspaces in the Linux file system, e.g. ~/planner_ws, which is much faster.

By default, WSL 2 runs in its own virtual network. This is sufficient for simulations. To connect to the lab network, switch WSL 2 to the mirrored networking mode (Windows 11 22H2 or newer). Create or edit the file .wslconfig in your Windows user directory (C:\Users\<user>\.wslconfig):

[wsl2]
networkingMode=mirrored

Then restart WSL in PowerShell with wsl --shutdown.

Docker on macOS

macOS cannot run the CPM Lab natively, and RViz does not work in Docker on macOS because macOS does not support X11 forwarding. Instead, run the CPM Lab in the simulation Docker image and visualize it with Lichtblick, which connects to the container through the Foxglove bridge.

Install Docker Desktop and start it. The images are available for Apple silicon (arm64) and Intel Macs (amd64).
Install the Lichtblick desktop app and the CPM Lab extensions as described in Visualization with Lichtblick (Option A).
Clone the simulation repository and build the image. The first build takes a while:
```
git clone git@git.rwth-aachen.de:CPM/Project/Lab/ros2/docker/simulation.git ~/cpm-simulation
cd ~/cpm-simulation && ./make-image.bash
```
Cloning needs an SSH key in your RWTH GitLab account; HTTP(S) is not supported.

Create a directory for your work and start the simulation image in it. The container publishes the port of the Foxglove bridge, so Lichtblick can connect from macOS, and mounts ~/cpm_lab for your recordings:

mkdir -p ~/cpm_ws ~/cpm_lab && cd ~/cpm_ws
docker run -it --rm --name cpm -p 8765:8765 -v "$PWD:/workspace" -w /workspace \
    -v ~/cpm_lab:/cpm_lab -e CPM_LAB_HOME=/cpm_lab cpm-lab-simulation bash

Inside the container, start the CPM Lab with the Foxglove bridge instead of RViz:
```
export ROS_DOMAIN_ID=21
ros2 launch cpm_lab cpm_lab_foxglove.launch.xml
```
In Lichtblick, open a connection to ws://localhost:8765 and load the CPM Lab layout. Control the lab with the CPM control dashboard panel as described in First Simulation.

A simulation in the Docker image on macOS, controlled and visualized in the Lichtblick desktop app

To open a second terminal in the same container, e.g. for an external motion planner, run in a new macOS terminal. docker exec does not run the image’s entrypoint, so source ROS first:

docker exec -it cpm bash
source /opt/ros/jazzy/setup.bash

The directory ~/cpm_ws on your Mac is mounted as /workspace. Put your own packages into ~/cpm_ws/src and build them inside the container, see Your First Motion Planner. Recordings go to ~/cpm_lab on your Mac. Everything else outside /workspace is lost when the container exits.

Note

Docker Desktop does not share the network of your Mac with the container, so the container cannot communicate with the lab network directly. The Docker setup on macOS is meant for simulations and development; use a lab computer or one of the other setups for experiments with real vehicles.

Which Setup Should I Choose?

You use Ubuntu 24.04: install the Debian packages directly.
You use Windows 11 or a recent Windows 10: start with WSL 2. If you run into graphics or network problems, use a VM.
You use macOS: use Docker with Lichtblick for development and simulations. If you need RViz, use a VM with Ubuntu for arm64 or amd64.
You want to change the CPM Lab itself: build it from source in a native Ubuntu or a VM, see Building from Source.