Skip to main content

rmw_hdds Installation

Guide to installing the HDDS ROS2 middleware layer (rmw_hdds).

Prerequisites​

ROS2 Distribution​

rmw_hdds supports:

  • ROS2 Jazzy (recommended)
  • ROS2 Iron
  • ROS2 Humble

System Requirements​

ComponentRequirement
OSUbuntu 22.04+, Debian 12+
Architecturex86_64, aarch64
Memory2 GB RAM minimum
Disk500 MB for installation

Installation Methods​

From Source (Colcon Workspace)​

Package Repository Coming Soon

Pre-built Debian packages (ros-$ROS_DISTRO-rmw-hdds) will be available via an APT repository in a future release. For now, please install from source using the instructions below.

# Create workspace
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src

# Clone repository (rmw_hdds is included in the main repo under rmw_hdds/)
git clone https://git.hdds.io/hdds/hdds.git

# Install dependencies
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y

# Build
source /opt/ros/$ROS_DISTRO/setup.bash
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

# Source workspace
source ~/ros2_ws/install/setup.bash

Using Docker​

FROM ros:jazzy

# Install rmw_hdds
RUN apt-get update && apt-get install -y \
    ros-jazzy-rmw-hdds \
    && rm -rf /var/lib/apt/lists/*

# Set as default RMW
ENV RMW_IMPLEMENTATION=rmw_hdds_cpp
# Build and run
docker build -t ros2-hdds .
docker run -it ros2-hdds

Setting HDDS as Default RMW​

Temporary (Current Session)​

export RMW_IMPLEMENTATION=rmw_hdds_cpp

Permanent (Shell Configuration)​

# Add to ~/.bashrc or ~/.zshrc
echo 'export RMW_IMPLEMENTATION=rmw_hdds_cpp' >> ~/.bashrc
source ~/.bashrc

Per-Launch Configuration​

# Single command
RMW_IMPLEMENTATION=rmw_hdds_cpp ros2 run demo_nodes_cpp talker

# Launch file
ros2 launch my_package my_launch.py --ros-args --enclave /my_enclave

Verification​

Check Available RMW Implementations​

ros2 doctor --report | grep rmw

Expected output:

middleware name    : rmw_hdds_cpp

Test Communication​

Terminal 1:

export RMW_IMPLEMENTATION=rmw_hdds_cpp
ros2 run demo_nodes_cpp talker

Terminal 2:

export RMW_IMPLEMENTATION=rmw_hdds_cpp
ros2 run demo_nodes_cpp listener

Verify HDDS Status​

# Using hdds-admin CLI tool
hdds-admin info
hdds-admin health

Example output:

Gateway Info
  Name:        hdds-gateway
  Version:     1.0.0
  API Version: v1

HDDS Health Status
  Status:  ok
  Uptime:  5m 32s
  Version: 1.0.0
note

Install hdds-admin with cargo install --path tools/hdds-admin from the HDDS source tree.

Build Options​

CMake Options​

colcon build --cmake-args \
    -DCMAKE_BUILD_TYPE=Release \
    -DRMW_HDDS_WITH_SECURITY=ON \
    -DRMW_HDDS_WITH_SHM=ON \
    -DRMW_HDDS_WITH_TRACING=OFF
OptionDefaultDescription
RMW_HDDS_WITH_SECURITYONDDS Security support
RMW_HDDS_WITH_SHMONShared memory transport
RMW_HDDS_WITH_TRACINGOFFLTTng/ROS 2 tracing support
RMW_HDDS_DEFAULT_DOMAIN_ID0Default domain ID
RMW_HDDS_DEFAULT_LOG_LEVELINFODefault log level (TRACE, DEBUG, INFO, WARN, ERROR)
HDDS_STATIC_LINKOFFStatic linking

Legacy Options (Deprecated)​

Old OptionNew Option
HDDS_ENABLE_SECURITYRMW_HDDS_WITH_SECURITY
HDDS_ENABLE_SHMRMW_HDDS_WITH_SHM
HDDS_ENABLE_LOGGINGRMW_HDDS_DEFAULT_LOG_LEVEL

Optimized Build​

# Maximum performance
colcon build --cmake-args \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CXX_FLAGS="-O3 -march=native" \
    -DHDDS_ENABLE_LOGGING=OFF

Dependencies​

Runtime Dependencies​

# Automatically installed with package
libhdds1        # Core HDDS library
libhdds-cpp1    # C++ bindings

Build Dependencies (Source Build)​

sudo apt install \
    build-essential \
    cmake \
    cargo \
    rustc \
    libssl-dev

Troubleshooting Installation​

Package Not Found​

E: Unable to locate package ros-jazzy-rmw-hdds

Solution: Pre-built packages are not yet available. Please build from source instead.

Build Fails: Rust Not Found​

CMake Error: Could not find Rust compiler

Solution: Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

RMW Not Loading​

[ERROR] [rmw_implementation]: Failed to load rmw implementation

Solution: Ensure library path is set:

export LD_LIBRARY_PATH=/opt/ros/$ROS_DISTRO/lib:$LD_LIBRARY_PATH

Shared Memory Permission Error​

[WARN] [hdds]: Failed to create shared memory segment

Solution: Check shared memory limits:

# Increase limits
sudo sysctl -w kernel.shmmax=268435456
sudo sysctl -w kernel.shmall=65536

# Make permanent
echo "kernel.shmmax=268435456" | sudo tee -a /etc/sysctl.conf
echo "kernel.shmall=65536" | sudo tee -a /etc/sysctl.conf

Uninstallation​

Package Installation​

sudo apt remove ros-$ROS_DISTRO-rmw-hdds

Source Installation​

cd ~/ros2_ws
rm -rf build/rmw_hdds install/rmw_hdds
colcon build

Next Steps​