ROS 2 Humble Installation Guide

2025-11-26

This document is intended for developers, system integrators, and field deployment teams building custom ROS 2 Humble runtime on PI-SG565D platforms or similar Debian 13 (Trixie) environments. It covers the complete workflow from source synchronization, dependency preparation, compilation troubleshooting, to environment variable configuration and communication testing. Through this guide, you can:

Obtain an installation process optimized for industrial/robotics scenarios, quickly establishing a customizable ROS 2 Humble development environment;
Understand common issues and solutions when handling dependency conflicts and avoiding commercial middleware like Fast DDS/Connext on clean Debian systems;
Build a reproducible workspace structure, providing a unified template for CI, automated deployment, or multi-device synchronization;
Verify C++/Python node interoperability based on included example tests, ensuring the environment is ready for subsequent application development.

Prerequisites

Operating System: Debian 13 (Trixie)
Network: Stable internet connection for downloading dependencies and source code
Storage and Time: At least 10GB free space, 1-3 hours (depending on performance and network)
Python: Python 3.10/3.11 recommended (3.12+ may have compatibility issues)
Other Recommendations: Update the system in advance: sudo apt-get update && sudo apt-get full-upgrade

Installation Steps

Install basic dependency packages

    sudo apt-get update && sudo apt-get full-upgrade
    sudo apt-get install -y \
    python3-flake8-blind-except \
    python3-flake8-class-newline \
    python3-flake8-deprecated \
    python3-mypy \
    python3-pip \
    python3-pytest \
    python3-pytest-cov \
    python3-pytest-mock \
    python3-pytest-repeat \
    python3-pytest-rerunfailures \
    python3-pytest-runner \
    python3-pytest-timeout \
    python3-rosdep2 \
    python3-colcon-core \
    vcstool \
    build-essential \
    git

Create ROS 2 workspace

mkdir -p ~/ros2_humble
cd ~/ros2_humble

Get ROS 2 Humble source code

cd ~/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos

Install system dependencies
```
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"
```
- Skipped packages explanation
  - fastcdr, rti-connext-dds-6.0.1: Commercial/optional dependencies
  - urdfdom_headers, python3-vcstool: May have been installed through other means
  - ignition-math6, ignition-cmake2, ignition-common3, ignition-transport8: Not available in Debian 13 (Gazebo-related, not core functionality)
- Common errors (can be ignored)
  - python3-sip-dev failure: Dependency for GUI tools (rqt), does not affect core functionality
  - python3-nose failure: Deprecated in Python 3.12+, does not affect core functionality

Compile source code

colcon build --symlink-install

Issues that may be encountered during compilation

Issue 1: Fast DDS related errors

Error message:

Starting >>> rmw_connextdds
--- stderr: rmw_fastrtps_shared_cpp
CMake Deprecation Warning at CMakeLists.txt:15 (cmake_minimum_required):
  Compatibility with CMake < 3.10 will be removed from a future version of
  CMake.

  Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
  to tell CMake that the project requires at least <min> but has been updated
  to work with policies introduced by <max> or earlier.

CMake Error at CMakeLists.txt:47 (find_package):
  Could not find a package configuration file provided by "fastrtps"
  (requested version 2.6.2) with any of the following names:

    fastrtpsConfig.cmake
    fastrtps-config.cmake

  Add the installation prefix of "fastrtps" to CMAKE_PREFIX_PATH or set
  "fastrtps_DIR" to a directory containing one of the above files.  If
  "fastrtps" provides a separate development package or SDK, be sure it has
  been installed.

---
Failed   <<< rmw_fastrtps_shared_cpp [2.60s, exited with code 1]

Cause: The package rmw_fastrtps_shared_cpp depends on Fast DDS (fastrtps). Fast DDS is not installed, so CMake cannot find fastrtpsConfig.cmake, resulting in the error. Even if you plan to use Cyclone DDS, colcon will still attempt to build Fast DDS related packages unless explicitly skipped.

Solution: When using Cyclone DDS, directly skip the Fast DDS series packages:

  cd ~/ros2_humble
  export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
  colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release \
  --packages-skip \
  rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro \
  rmw_implementation

Issue 2: rmw_implementation build failure

Error message:

Starting >>> rmw_implementation
[-1762327992435806464.000s] ERROR:colcon.colcon_cmake.task.cmake.build:Failed to find the following files:
-/home/root/ros2_humble/install/rmw_fastrtps_shared_cpp/share/rmw_fastrtps_shared_cpp/package.sh
- /home/root/ros2_humble/install/rmw_fastrtps_cpp/share/rmw_fastrtps_cpp/package.sh
-/home/root/ros2_humble/install/rmw_fastrtps_dynamic_cpp/share/rmw_fastrtps_dynamic_cpp/package.sh
Check that the following packages have been built:
- rmw_fastrtps_shared_cpp
- rmw_fastrtps_cpp
- rmw_fastrtps_dynamic_cpp
Failed   <<< rmw_implementation [0.40s, exited with code 1]

Cause: The build system will by default look for Fast DDS family environment hooks (package.sh files for rmw_fastrtps_* under install). Fast DDS is not installed, so these files cannot be found, causing rmw_implementation, rcl, etc. to fail.

Solution:

Explicitly select Cyclone DDS: export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

Hide Fast DDS/Connext source packages (to avoid subsequent scanning):

for d in \
  src/**/rmw_fastrtps_shared_cpp \
  src/**/rmw_fastrtps_cpp \
  src/**/rmw_fastrtps_dynamic_cpp \
  src/**/rmw_connextdds \
  src/**/rmw_connextdds_common \
  src/**/rmw_connextddsmicro \
; do
  [ -d "$d" ] && touch "$d/COLCON_IGNORE"
done

Temporarily bypass with placeholder package.sh (does not affect compiled artifacts, can be deleted later):

for p in rmw_fastrtps_shared_cpp rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp; do
mkdir -p /home/root/ros2_humble/install/$p/share/$p
printf '#!/bin/sh\n# placeholder for %s\n' "$p" > /home/root/ros2_humble/install/$p/share/$p/package.sh
chmod +x /home/root/ros2_humble/install/$p/share/$p/package.sh
done

Build Cyclone DDS first, then build rmw_implementation, rcl:

colcon build --symlink-install \
--packages-select rmw_cyclonedds_cpp \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

colcon build --symlink-install \
--packages-select rmw_implementation \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

colcon build --symlink-install \
--packages-select rcl \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DRMW_IMPLEMENTATION=rmw_cyclonedds_cpp

Continue full build

After resolving the above issues, continue with the full build:

# Continue full build (skip Fast DDS & Connext; disable testing for speed and reduced dependencies)
colcon build --symlink-install \
--cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
--packages-skip \
rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
rmw_connextdds rmw_connextdds_common rmw_connextddsmicro

Environment Variable Setup

After compilation is complete, environment variables need to be set to use ROS 2:

export ros2_source=$PWD
echo -e "source ${ros2_source}/ros2_humble/install/setup.bash" >> $HOME/.bashrc
source $HOME/.bashrc

Note: ros2_source is the location of the ros2_humble directory, i.e., the ROS 2 workspace created in step 2 of the installation steps.

Usage Testing

Examples

Open a terminal and run the C++ talker example:
```
ros2 run demo_nodes_cpp talker
```
Open another terminal and run the Python listener example:
```
ros2 run demo_nodes_py listener
```

Verification

After executing these two commands, you should see messages from the talker side:

ros2 run demo_nodes_cpp talker
[INFO] [1728966840.691346935] [talker]: Publishing: 'Hello World: 1'
[INFO] [1728966841.691537928] [talker]: Publishing: 'Hello World: 2'
[INFO] [1728966842.691572879] [talker]: Publishing: 'Hello World: 3'
[INFO] [1728966843.691563207] [talker]: Publishing: 'Hello World: 4'
[INFO] [1728966844.691568120] [talker]: Publishing: 'Hello World: 5'

And messages from the listener side:

ros2 run demo_nodes_py listener
[INFO] [1728966840.716456921] [listener]: I heard: [Hello World: 1]
[INFO] [1728966841.698002748] [listener]: I heard: [Hello World: 2]
[INFO] [1728966842.697675740] [listener]: I heard: [Hello World: 3]
[INFO] [1728966843.697643318] [listener]: I heard: [Hello World: 4]
[INFO] [1728966844.697551980] [listener]: I heard: [Hello World: 5]

This indicates that both C++ and Python APIs are functioning correctly.

wx GUI Development

Container Deployment

Quectel Pi H1