Setup Real-Time Kernel (Debian, prebuilt package)

This guide describes the recommended and simplest way to set up a real-time (PREEMPT_RT) PC and prepare it for ROS 2 development using RTW.

We’re using a pre-build binary on Linux Debian distribution and a docker container with Ubuntu 24.04 with real-time permissions.

Note

This is the Debian alternative to compiling a PREEMPT_RT kernel from source on Ubuntu. Debian ships prebuilt -rt-amd64 kernel packages, so no compilation is needed here — ROS itself still runs inside an Ubuntu 24.04 docker container.

Operating System Installation

  1. Download the newest Debian stable version.

    It is recommended to use the complete installation image from: https://www.debian.org/CD/

  2. Create a bootable USB (e.g., using dd on Linux).

  3. Boot from the USB and select Graphical Installer.

  4. Follow installation steps:

    • Be aware Debian uses a separate root user. Don’t get confused with two passwords. The root user has no name; access it with the su - command.

    • Install ssh during setup

    • Choose your preferred window manager (recommended: Plasma)

  5. Configure networking:

    • Main network according to your company requirements

  6. Login to the PC after installation (recommended: Plasma on X11):

    • Set up a networking - usually your company network and dedicated RT ethernet interface for your robot with a static IP.

Initial System Setup

  1. Connect via SSH from engineering PC.

  2. Add your user to sudo:

su -
usermod -a -G sudo <user_name>
exit

  1. Re-login and verify sudo access.

  2. Update system:

sudo apt update

PREEMPT_RT Kernel Installation

  1. Check current kernel:

uname -r

  1. Install matching RT kernel:

Check the current kernel version with uname -r, e.g., 6.12.74+deb13+1-amd64. Then, install the exact same version of kernel with PREEMPT_RT flag

sudo apt install linux-image-<version>-rt-amd64

  1. Reboot:

sudo reboot

  1. Verify RT kernel:

uname -a

# should contain PREEMPT_RT

Realtime Permissions Setup

  1. Install Docker (APT method):

See general info on docker installation (Debian’s official apt repo).

  1. Configure realtime and docker groups and configure limits:

sudo usermod -aG docker $USER
sudo addgroup realtime
sudo usermod -aG realtime $USER

sudo tee -a /etc/security/limits.conf <<EOF
@realtime soft rtprio 99
@realtime soft priority 99
@realtime soft memlock unlimited
@realtime hard rtprio 99
@realtime hard priority 99
@realtime hard memlock unlimited
EOF

  1. Logout/login and verify:

You should see docker and realtime groups in the output.

groups

RTW and ROS Workspace Setup

  1. Install RTW:

  1. Create RT-enabled workspace:

rtw workspace create \
   --ws-folder <my-ws-name> \
   --ros-distro <my-distro> \
   --docker \
   --disable-nvidia \
   --repos-containing-repository-url \
      https://<repo-url>.git \
   --repos-branch master \
   --apt_packages <additional-pkg-1>  \
                 <additional-pkg-2>... \
   --enable-realtime

  1. Exit container and source workspace:

Exiting the container saves the workspace configuration in RTW.

rtw ws <my-ws-name>

  1. Enter container:

rtw docker enter

Verification and Testing

  1. Verify RT kernel inside container:

uname -a

# should contain PREEMPT_RT