Ansible Playbooks for ROS 2 Setup#

The project has been migrated from shell scripts to Ansible playbooks for all the aspects of robot and dev machine setup.

Directory Structure#

The Ansible playbooks are located in the ansible directory:

ansible/
├── ansible-virtual.cfg          # Configuration for virtual bots
├── ansible.cfg                  # Ansible configuration
├── inventories/                 # Inventory files for different environments
│   ├── localhost.yml            # Local machine inventory
│   ├── real-robots.yml          # Real robot inventory
│   └── virtual-bots.yml         # Docker-based virtual bots inventory
├── playbooks/                   # Playbooks for different tasks
│   ├── 0_start_virtual_bots.yml # Start Docker containers for virtual bots
│   ├── 1_pam_ssh_agent_auth.yml # SSH agent authentication setup
│   ├── 10_install_docker.yml    # Docker installation
│   ├── 20_ros_setup.yml         # Main ROS 2 setup playbook
│   ├── 100_startup_service.yml  # Robot startup service
│   ├── 200_pair_controller.yml  # Controller pairing
│   ├── 9999_stop_virtual_bots.yml # Stop Docker containers for virtual bots
│   ├── group_vars/              # Playbook-specific variables
│   │   └── all.yml              # Configuration variables
│   ├── roles/                   # Individual roles for each component
│   │   ├── basic_prereqs/       # Basic prerequisites
│   │   ├── clang/               # Clang installation
│   │   ├── cmake/               # CMake installation
│   │   ├── colcon_setup/        # Colcon mixin setup
│   │   ├── dev_tools/           # Development tools
│   │   ├── extra_facts/         # System facts gathering
│   │   ├── locale_setup/        # UTF-8 locale setup
│   │   ├── utc_timezone/        # UTC timezone setup
│   │   ├── nodejs/              # Node.js and NPM
│   │   ├── ros_dependencies/    # ROS dependencies (uses known packages)
│   │   ├── ros_install_prebuilt/ # ROS 2 installation from packages
│   │   ├── ros_install_source/  # ROS 2 installation from source
│   │   └── ros_user_setup/      # ROS user creation and setup
│   └── test_ros_dependencies.yml # Test playbook for ROS dependencies
└── README.md                    # Points back to this documentation

Configuration#

Edit ansible/playbooks/group_vars/all.yml to configure:

  • ros_distro: ROS 2 distribution (default: jazzy)

  • source_install: Whether to install ROS 2 from source (default: false)

  • clang_version: Clang version to install (default: 20)

  • ci_mode: Whether running in CI environment (default: false)

Usage#

Quick Start#

To set up a ROS 2 development environment:

cd ansible
./setup-ros.sh

Install ROS 2 from packages (default)#

ansible-playbook playbooks/20_ros_setup.yml

Install ROS 2 from source#

ansible-playbook playbooks/20_ros_setup.yml -e "source_install=true"

Run specific roles only#

ansible-playbook playbooks/20_ros_setup.yml --tags "basic_prereqs,cmake"

Available role tags:

  • extra_facts: System facts gathering (always runs)

  • basic_prereqs: Basic prerequisites

  • locale_setup: UTF-8 locale setup

  • utc_timezone: UTC timezone setup

  • cmake_kitware: CMake installation from Kitware repository

  • cmake_system: CMake installation from system packages

  • dev_tools: Development tools

  • colcon_setup: Colcon mixin setup

  • fish_setup: Fish shell configuration for ROS 2

  • ros_install_prebuilt: ROS 2 installation from packages

  • ros_install_source: ROS 2 installation from source

  • ros_dependencies: ROS dependencies

  • nodejs: Node.js and NPM

  • clang: Clang installation

  • ros_user_setup: ROS user creation and setup

  • xpra_setup: Setup xpra and xpra-html5 with GPU support

Run only the ROS installation part#

For prebuilt packages:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_install_prebuilt"

For source installation:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_install_source" -e "source_install=true"

You can also use the combined tag:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_install"

This will run either ros_install_prebuilt or ros_install_source based on the source_install variable.

Using specific inventory#

For real robots:

ansible-playbook -i inventories/real-robots.yml playbooks/20_ros_setup.yml

For local machine:

ansible-playbook -i inventories/localhost.yml playbooks/20_ros_setup.yml

For Docker-based virtual bots:

# First start the virtual bots
env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook playbooks/0_start_virtual_bots.yml

# Then run the setup playbook
env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook playbooks/20_ros_setup.yml

# When finished, stop the virtual bots
env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook playbooks/9999_stop_virtual_bots.yml

For faster iteration, playbooks can be chained:

env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook \
    playbooks/9999_stop_virtual_bots.yml \
    playbooks/0_start_virtual_bots.yml \
    playbooks/20_ros_setup.yml -vvv

Generating ROS Dependencies#

The project includes a script to generate ROS dependencies based on your project:

./scripts/ros-dep-gen-ansible.sh

This script:

  1. Analyzes the project’s ROS dependencies using rosdep

  2. Generates a variables file in ansible/playbooks/roles/ros_dependencies/vars/known_ros_dependencies.yml

  3. The generated variables (ros_dependencies_known_packages) are automatically used by the ros_dependencies role

To run only the ROS dependencies role:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_dependencies"

Alternatively, you can use the dedicated test playbook:

ansible-playbook playbooks/test_ros_dependencies.yml

Requirements#

  • Ubuntu 22.04 or newer

  • Ansible 2.9 or newer

  • Required Ansible collections:

    ansible-galaxy collection install community.general

Post-Installation Notes#

After installation, you may need to add Clang to your PATH:

For fish (in ~/.config/fish/config.fish):

set -gx PATH /usr/lib/llvm-20/bin $PATH

For bash (in ~/.bashrc):

export PATH="/usr/lib/llvm-20/bin:$PATH"

For dockerfile:

ENV PATH="/usr/lib/llvm-20/bin:$PATH"

Docker Integration#

The project includes Ansible playbooks for Docker integration:

Installing Docker#

To install Docker on robots:

ansible-playbook -i inventories/real-robots.yml playbooks/10_install_docker.yml

This playbook:

  • Installs Docker Engine and related tools

  • Configures Docker daemon with proper logging settings

  • Adds the user to the Docker group for non-root access

Robot Startup Service#

The project includes a playbook to set up a systemd service that runs ROS nodes in Docker containers:

ansible-playbook -i inventories/real-robots.yml playbooks/100_startup_service.yml

This playbook:

  • Pulls the latest Docker image from GitHub Container Registry

  • Creates two systemd services:

    • drqp-control-service: Runs the main control nodes

    • drqp-joystick-service: Runs the joystick node with hot-plugging support

  • Creates a post-start cleanup service:

    • drqp-docker-prune-service: Waits until the startup services are active and then runs docker system prune -a -f once to reclaim disk space by pruning unused Docker images, stopped containers, unused networks, and build cache

SSH Agent Authentication#

To enable passwordless sudo using SSH agent authentication:

ansible-playbook -i inventories/real-robots.yml playbooks/1_pam_ssh_agent_auth.yml

This playbook:

  • Installs libpam-ssh-agent-auth package

  • Configures PAM to allow sudo authentication via SSH agent

  • Adds your SSH public key to the authorized keys file

Controller Pairing#

To pair a DualSense wireless controller with a robot:

ansible-playbook -i inventories/real-robots.yml playbooks/200_pair_controller.yml -e "controller_name=DualSense"

or

ansible-playbook -i inventories/real-robots.yml playbooks/200_pair_controller.yml -e "controller_mac=XX:XX:XX:XX:XX:XX"

Putting a PS5 Dualsense Controller into Pairing Mode#

To put a PS5 Dualsense controller into pairing mode, press and hold the PS button and the Create (or Share) button simultaneously until the light bar starts flashing. This indicates that the controller is discoverable for pairing with other devices, such as a PC or a smartphone.

Here’s a more detailed breakdown:

  1. Ensure the controller is off: If the controller is already on, hold the PS button until it turns off.

  2. Initiate pairing mode: Press and hold both the PS button and the Create (or Share) button at the same time.

  3. Observe the light bar: The light bar on the controller will start flashing, indicating that it’s in pairing mode.

Migration from Shell Scripts#

The Ansible playbooks replaced the following shell scripts:

  • scripts/ros/ros-2-prep.sh → ansible/playbooks/20_ros_setup.yml

  • scripts/ros/ros-2-src-build.sh → ansible/playbooks/roles/ros_install_source

  • scripts/ros/__gen_install_ros_dependencies.sh → ansible/playbooks/roles/ros_dependencies with known packages

  • scripts/install_docker.sh → ansible/playbooks/10_install_docker.yml

  • scripts/ros/desktop/ros-desktop.dockerfile (user setup) → ansible/playbooks/roles/ros_user_setup

  • scripts/ros/fish/setup.fish → ansible/playbooks/roles/fish_setup

  • scripts/ros/colcon-mixin.sh → ansible/playbooks/roles/colcon_setup

  • scripts/ros/rosdep-update.sh → ansible/playbooks/roles/colcon_setup

Benefits

The Ansible playbooks provide several advantages:

  • Better organization with roles for each component

  • Idempotency (can be run multiple times without issues)

  • Selective execution with tags

  • Better error handling

  • Configurable variables

  • Better documentation

  • Docker integration for containerized deployment

  • Support for virtual bots for testing

  • Improved SSH authentication

  • Controller pairing automation