Introducing Husarnet-DDS

We are excited to introduce Husarnet-DDS, a tool designed to simplify the configuration of Husarnet for your ROS 2 applications. Husarnet-DDS is an open-source utility that automatically generates DDS XML configuration files compatible with both Cyclone DDS and Fast DDS.

Before Husarnet-DDS, users had to manually create and fill out XML profile files each time a new device was added to the Husarnet network. This process was not only tedious but also error-prone, often resulting in issues such as typos that required troubleshooting.

Husarnet-DDS streamlines this process, making it simpler and more efficient. The tool's source code and GitHub releases can be found at https://github.com/husarnet/husarnet-dds.

Quick Start Guide

The Husarnet-DDS tool is straightforward to install and use. To get started, follow the installation instructions provided in the README file on the GitHub repository. Once the tool is installed, you can easily generate the appropriate DDS configuration for your ROS 2 applications.

1. Installing Husarnet-DDS

First, install Husarnet-DDS on each device in your Husarnet group (eg. on your robot and your laptop) from GitHub releases (available for Linux, MacOS, and Windows), eg. on Ubuntu:

RELEASE="v1.3.5"
ARCH="amd64"

sudo curl -L https://github.com/husarnet/husarnet-dds/releases/download/$RELEASE/husarnet-dds-linux-$ARCH -o /usr/local/bin/husarnet-dds
sudo chmod +x /usr/local/bin/husarnet-dds

Husarnet setup

If your devices are not connected to the same Husarnet group, you need to install Husarnet first, and then join your devices to the same group.

2. Launching Husarnet-DDS

Next, choose the DDS implementation that you want to use with your ROS 2 application. Husarnet-DDS supports both Fast DDS and Cyclone DDS.

Set up the required environment variables based on your chosen DDS implementation on each device in your ROS 2 network (eg. on your robot and your laptop)

Fast DDS (Simple Discovery)

export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
export FASTRTPS_DEFAULT_PROFILES_FILE=/var/tmp/husarnet-fastdds-simple.xml
husarnet-dds singleshot

Fast DDS (Discovery Server)

For devices acting as a SERVER (with the my-server Husarnet hostname used below in the CLIENT config):

export DISCOVERY_SERVER_PORT=11811
husarnet-dds singleshot
fast-discovery-server -i 0 -x /var/tmp/husarnet-dds/fastdds-ds-server.xml

For devices acting as a CLIENT:

export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
export FASTRTPS_DEFAULT_PROFILES_FILE=/var/tmp/husarnet-fastdds-ds-client.xml
export ROS_DISCOVERY_SERVER=my-server:11811
husarnet-dds singleshot

Cyclone DDS

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export CYCLONEDDS_URI=file:///var/tmp/husarnet-cyclone.xml
husarnet-dds singleshot

Running Husarnet-DDS as a Service (Optional)

Husarnet-DDS can also be run as a service, automatically starting after a system reboot and updating the hosts in DDS XML profile files every five seconds. To install and start the service, follow the instructions provided in the README file.

Running Husarnet-DDS as a hook for Husarnet Client (Optional)

Starting from the 2.0.78 release, a hooking mechanism has been introduced in the Husarnet Client, which allows certain events to trigger the execution of custom user scripts. This feature can be used in conjunction with Husarnet-DDS!

To set up Husarnet-DDS as a hook, follow these steps:

1. First, update your Husarnet Client to the latest version:

   sudo apt update
   sudo apt install husarnet

2. Create a hook script file named dds-update.sh in the /var/lib/husarnet/hook.whitelist_changed.d/ directory:

   sudo mkdir /var/lib/husarnet/hook.whitelist_changed.d
   sudo vim /var/lib/husarnet/hook.whitelist_changed.d/dds-update.sh

3. Insert the following script into the file:

   #!/bin/bash
   
   husarnet-dds singleshot

4. Save the file, make it executable, and enable Husarnet hooks:

   sudo chmod +x /var/lib/husarnet/hook.whitelist_changed.d/dds-update.sh
   husarnet daemon hooks enable

That's it! Now Husarnet-DDS will be launched as a hook whenever specific events occur in the Husarnet Client. Read more about using Husarnet hooks here

3. Launching a ROS 2 Application

With the environment variables set up, you can now launch your ROS 2 application as usual. The Husarnet-DDS tool will take care of generating the DDS configuration for your application.

Conclusion

Husarnet-DDS offers numerous benefits, including simplifying the configuration of Husarnet for ROS 2 applications, reducing the risk of errors associated with manual XML profile file creation, and facilitating streamlined communication between ROS 2 nodes over the Husarnet network.

Get started with Husarnet-DDS today by visiting the GitHub repository at https://github.com/husarnet/husarnet-dds and exploring the provided documentation. We look forward to hearing your feedback and seeing the amazing projects you'll create with the help of Husarnet-DDS!

COMMENTS

If you have any questions, or simply wish to share your thoughts regarding this blog post, check out this thread on the Husarnet Community Forum.