Docker Images for Husarion robots

Welcome. In this section you will find useful information about Docker images for our company's robots. Below is a table presenting in a compact form Docker images enabling quick launch of a given robot. Below the tables, you will also find a chapter Minimal Setup showing the minimum configuration of the container that is needed for proper startup (e.g. in the case of a camera, specify the device port).

If you are not sure how to launch images you can learn it form Examples section.

Hardware

Here's the list of Docker images hosted on Husarion's Docker Hub to be run on the real robots:

Name	Image		Description	Tags	Architectures
Husarion UGV
	husarion/husarion-ugv		Docker image for https://github.com/husarion/husarion_ugv_ros - a ROS 2 driver for Panther and Lynx
				jazzy	arm64
				humble	arm64
ROSbot 3 / XL
	husarion/rosbot		Docker images for ROSbot 2, ROSbot 2R and ROSbot 2 PRO robots.
				jazzy	amd64 arm64
				humble	amd64 arm64

Simulation

Here's the list of Docker images hosted on Husarion's Docker Hub with robot simulations to be run on your computer:

Name	Image		Description	Tags	Architectures
Gazebo: Husarion UGV
	husarion/husarion-ugv-gazebo		Docker image for https://github.com/husarion/husarion_ugv_ros. Gazebo Simulation for Panther na Lynx
				jazzy	amd64
				humble	amd64
Gazebo: ROSbot 3 / XL
	husarion/rosbot-gazebo		Gazebo simulation of ROSbot 2R / 2 PRO
				jazzy	amd64
				humble	amd64

Minimal setup

In this section you can find minimal setup for running the container on a specific robot.

Husarion UGV

Physical Robot

warning

This Docker image is intended to be run on the Built-in Computer. DO NOT run it on the User Computer (the one located in the User Shelf).

Also note that in the production setup in Panther, the ROS node is already launched!

compose.yaml

x-common-config: &common-config
  network_mode: host
  ipc: host
  restart: always
  env_file:
    - /home/husarion/config/common/.env # env configuration including namespace, domain id, DDS, etc.

services:
  husarion_ugv_ros:
    image: husarion/husarion-ugv:jazzy-2.3.1-20250701
    container_name: husarion_ugv_ros
    <<: *common-config
    security_opt:
      - apparmor:unconfined # allow for dbus PowerOff
    devices:
      - /dev/bus/usb
      - /dev/gpiochip0
      - /dev/spiled-channel1
      - /dev/spiled-channel2
      - /dev/input/js0
    device_cgroup_rules:
      - 'c 189:* rmw' # USB devices
      - 'c 254:0 rmw' # gpiochip0
      - 'c 153:* rmw' # spiled-channel1, spiled-channel2
      - 'c 13:0 rmw' # gamepad
    volumes:
      - /run/husarion/robot_config.env:/run/husarion/robot_config.env
      - /run/husarion/robot_config.yaml:/run/husarion/robot_config.yaml
      - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket
      - /sys/bus/iio/devices:/sys/bus/iio/devices:ro # Read-only access to IIO devices
      - ~/.ssh/id_rsa:/root/.ssh/id_rsa
      - /home/husarion/config:/config
    # Realtime hardware (https://control.ros.org/master/doc/ros2_control/controller_manager/doc/userdoc.html#determinism)
    ulimits:
      rtprio:
        soft: 99
        hard: 99
      memlock:
        soft: -1
        hard: -1
    command: >
      ros2 launch husarion_ugv_bringup bringup.launch.py
        common_dir_path:=/config
        launch_gamepad:=true

Simulation

compose.yaml

x-common-config: &common-config
  network_mode: host
  ipc: host
  environment:
    - RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
    - ROBOT_MODEL_NAME=${ROBOT_MODEL_NAME:-panther}
    - ROBOT_NAMESPACE=${ROBOT_NAMESPACE:-${ROBOT_MODEL_NAME:-panther}}
    - ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-0}

x-cpu-config: &cpu-config
  env_file: .env.cpu

x-gpu-config: &gpu-config
  runtime: nvidia
  env_file: .env.gpu

services:
  husarion_ugv_gazebo:
    image: husarion/husarion-ugv-gazebo:jazzy-2.3.1-20250701
    container_name: husarion_ugv_gazebo
    <<:
      - *common-config
      - *gpu-config
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
    command: >
      ros2 launch husarion_ugv_gazebo simulation.launch.py

ROSbot 3 / XL

ROSbot 3

compose.yaml

x-common-config:
  &common-config
  restart: unless-stopped
  network_mode: host
  ipc: host

services:
  rosbot:
    image: husarion/rosbot:jazzy
    <<: *common-config
    devices:
      - /dev/ttySERIAL # MCU communication port
      - /dev/gpiomem
      - /dev/gpiochip4 # For RPi 4 or ThinkerBoard set to /dev/gpiochip0
      - /dev/input # Joystick
      - /dev/bus/usb # FTDI
    environment:
      - RMW_IMPLEMENTATION=rmw_fastrtps_cpp
      - FASTRTPS_DEFAULT_PROFILES_FILE=/ros2_ws/src/rosbot_ros/docker/dds-config-udp.xml
    command: >
      ros2 launch rosbot_bringup rosbot.yaml

info

Before running this compose.yaml, make sure you have the proper version of the firmware installed on the microcontroller. To do so:

docker run --rm -it --privileged <docker_image> \
ros2 run rosbot_utils flash_firmware --robot-model rosbot

ROSbot XL

compose.yaml

x-common-config:
  &common-config
  restart: unless-stopped
  network_mode: host
  ipc: host

services:
  rosbot:
    image: husarion/rosbot:jazzy
    <<: *common-config
    devices:
      - /dev/input # Joystick
      - /dev/manipulator # Manipulator
      - /dev/rosbot # MCU
      - /dev/bus/usb # FTDI
      - /dev/snd # Sound
    environment:
      - RMW_IMPLEMENTATION=rmw_fastrtps_cpp
      - FASTRTPS_DEFAULT_PROFILES_FILE=/ros2_ws/src/rosbot_ros/docker/dds-config-udp.xml
    command: >
      ros2 launch rosbot_bringup rosbot_xl.yaml
        configuration:=basic

info

Before running this compose.yaml, make sure you have the proper version of the firmware installed on the microcontroller. To do so:

docker run --rm -it --privileged <docker_image> \
ros2 run rosbot_utils flash_firmware --robot-model rosbot_xl

Simulation

compose.yaml

# Run `xhost +local:docker` before starting the container to allow GUI applications to connect to the X server.

x-common-config:
  &common-config
  network_mode: host
  ipc: host

services:
  rosbot:
    image: husarion/rosbot-gazebo:jazzy
    <<: [ *common-config]
    runtime: nvidia # Remove if do not have NVIDIA GPU
    devices:
      - /dev/dri:/dev/dri
      - /dev/input:/dev/input:ro # Joystick
    environment:
      - RMW_IMPLEMENTATION=rmw_fastrtps_cpp
      - FASTRTPS_DEFAULT_PROFILES_FILE=/ros2_ws/src/rosbot_ros/docker/dds-config-udp.xml
      - DISPLAY=${DISPLAY:?[Error] No display found.}
      - QT_X11_NO_MITSHM=1
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
    command: >
      ros2 launch rosbot_gazebo simulation.yaml
        robot_model:=${ROBOT_MODEL:?[Error] Specify robot model}