ROS2

The ROS2 plugin connects the ROS2 network on your ROS2-based robot to the Rocos platform. In order to use the ROS plugin, it is required to be installed separately beside the rocos-agent. Subsequently, the ROS2 plugin will appear as a ROS2 node to other ROS2 components on your robot.

The ROS plugin is bidirectional; it can both subscribe to ROS messages and send them upstream to the DroneDeploy's Ground Robotics (DDGR) platform, as well as receive downstream messages from the DDGR platform and publish them into the ROS network.

Installing The Plugin

Currently, the plugin is only available for Linux systems. A rocos-agent version of v1.6.9 and above is required for running the ros2 plugins. If the rocos-agent is installed via apt, then the plugin installation steps are:

sudo apt-get update
sudo apt install rocos-agent-plugin-ros2-$ROS_DISTRO

Where $ROS_DISTRO could be foxy, galactic, humble, iron or jazzy. The Debian packages are available for amd46 and arm64 architectures.

Data Model

The data model for the message sent and received by the ROS2 plugin is determined by the ROS2 message topics used on the ROS2 network to which the plugin is connected.

Receiving (Upstream) Messages

In order to receive ROS messages from your robot, the ROS2 plugin needs to understand the dialect of the ROS messages being used. In order to do this, the ROS2 plugin needs access to the shared object files which are built for each ROS package, and contain all the necessary code to read/write the ROS messages which are defined by that package. You will need to configure the ROS2 plugin with the location of these files by setting the LD_LIBRARY_PATH env variable as described in the Configuration section.

The ROS2 plugin searches for message files once each time that it starts up; if you change or create a message file while the Agent is running, you will need to disable and then re-enable the ROS2 plugin so that it searches for new messages.

The ROS2 plugin will automatically discover the topics being published on the connected ROS2 network and expose them as data URIs that you can read data from. The content of ROS messages is automatically converted into a JSON representation to allow access and binding to individual message fields.

Once the message files have been discovered by the Agent, then when ROS message topics become available (i.e. when a ROS node begins advertising a topic) the topic, and the fields contained therein, will become visible in the data picker.

ROS messages received automatically have two pieces of metadata applied:

Metadata Field	Description	Example
`ros.type`	The ROS message type of the original message.	`"geometry_msgs/Twist"`
`ros.node`	The name of the ROS node which published the message.	`"sensor1"`

Note

Support for Transient local durability policy (details below) is only available for ROS2 plugin version v2.2.2 and higher.

ROS2 implements various Quality of Service (QoS) policies that allow to tune communication between nodes (see ROS2 documentation). The ROS2 plugin will subscribe advertised topic using the best available QoS policies compatible will all current publishers. In particular, the plugin will automatically upgrade the Reliability and Durability policies if supported by all advertised ROS2 publishers for this topic.

The QoS policies used by the plugin are detailed below :

History: Keep Last
Depth: 5
Reliability: Best Effort (upgrade to Reliable)
Durability: Volatile (upgrade to Transient local)
Deadline: Infinite
Lifespan: Infinite
Liveliness: System Default (defined by DDS middleware).
Lease Duration: Infinite

Ignoring the possible Reliability and Durability policy upgrades, this is equivalent to the Sensor Data QoS profile defined in ROS2 Middleware Interface.

For subscriptions with Transient Local durability, the ROS2 plugin will echo the last message received on the topic to ensure it gets distributed to all new subscribers. This behavior can be disabled by setting disableTransientLocalEcho as described in the Configuration section. By default, all "transient" topics get echoed every 1 s but this rate can be adjusted when subscribing with the int query parameter. The ROS2 plugin will increase the echo rate to match the smallest int of all active subscribers. To ensure consistent reception rate, it is recommended to always specify an interval when subscribing a telemetry topic.

Sending (Downstream) Messages

In order to send ROS messages to your robot, the ROS2 plugin needs to understand the dialect of the ROS messages being used. In order to do this, the ROS2 plugin needs access to the shared object files. You will need to configure the ROS plugin with the location of these files by setting the LD_LIBRARY_PATH env variable as described in the Configuration section.

The ROS plugin needs to know the ROS message type for each downstream message being sent. You should include this information in the Metadata field for each control message, for example:

{
  "ros.type": "geometry_msgs/Twist"
}

The ROS2 plug needs the contents of each downstream message being sent, in the Payload Template field, to be structured in a particular JSON representation. For example, the contents of the geometry_msgs/PoseStamped message might look like:

{
  "header":{
      "stamp": {
         "secs": 0,
        "nsecs": 0
         },
       "frame_id": "map",
       "seq": 1
       },
  "pose":{
      "position": {
          "x": 1,
          "y": 2,
          "z": 3
         },
  "orientation": {
          "x": 0,
          "y": 0,
          "z": 0,
          "w": 1
    }
  }
}

Configuration

To use the ROS2 plugin, your agent will need a section in its agent-settings.json file which enables the ros2 component, as shown below. For more information on how to configure the agent plugins, see Agent Configuration.

...
"components": [
...
{
    "enabled": true,
    "id": "plugin",
    "settings": {
      "logLevel": 4,
      "name": "plugin_ros",
      "envVariables": {
        "LD_LIBRARY_PATH": "/home/ros_ws/install/velodyne_msgs/lib:/opt/ros/humble/lib/aarch64-linux-gnu:/opt/ros/humble/lib",
        "RMW_IMPLEMENTATION": "rmw_cyclonedds_cpp",
      },
      "plugin": "/opt/rocos-agent/bin/rocos-agent-plugin-ros2",
      "delayNewPubs": 200,
      "disableTransientLocalEcho": true,
      "blacklistServices": [
        ".*rviz.*_[0-9]+",
        ".*rqt.*_[0-9]+",
        ".*_ros2cli_[0-9]+"
      ]
    }
  },
...
]

The ROS plugin understands the following configuration parameters:

Name	Description	Unit	Default
`enabled`	Whether to enable the ROS plugin or not.		`false`
`name`	How this instance of the ROS plugin should be named.
`logLevel`	The logging verbosity: 1 - very quiet, 6 - very talkative.		4
`plugin`	The path to the plugin executable. If installed via `apt` it should be `/opt/rocos-agent/bin/rocos-agent-plugin-ros2`
`envVariables`	Any environment variables pair to send to plugin executable such as `LD_LIBRARY_PATH`, `RMW_IMPLEMENTATION` or `ROS_DOMAIN_ID`(if applicable).
`ROS_NAMESPACE`	Allows pushing the ROS plugin's node down into a namespace.
`pollingPeriod`	How frequently the ROS plugin should look for any new ROS topics which are available to subscribe to.	ms	2000
`keepOldTopics`	Whether topics which no longer have any ROS publishers should continue to be listed as available or not.		false
`publisherLifetime`	When the ROS plugin publishes a downstream message from the platform, a ROS publisher is created and advertised by the ROS plugin's node. This setting determines how long that publisher should continue to be advertised after each downstream message. If set to a non-positive value, then the plugin's ROS publishers will never expire.	s	300
`delayNewPubs`	When the ROS plugin publishes a downstream message from the platform, a ROS publisher is created and advertised by the ROS plugin's node. This setting determines how long the ROS plugin should wait between creating the publisher and transmitting the first message. Allowing a short delay here may help other ROS nodes from missing the published message if they are slow at subscribing.	ms	0
`disableTransientLocalEcho`	Automatically republish transient local messages if false.		false
`blacklistServices`	List of RegExs that match ROS2 services to be ignored by the plugin.		RViz, RQT & ROS2 CLI

Troubleshooting Node Discovery Issues with Fast DDS

Symptom

Some users experience problems where nodes and topics do not show up or connect as expected when using the default Fast DDS (rmw_fastrtps_cpp) RMW implementation in ROS 2 especially in certain network environments, containers, or after system reboots. These issues often do not occur with Cyclone DDS.

Solution: Use a Custom Fast DDS UDPv4 XML Profile

A common solution is to configure Fast DDS to use the UDPv4 (network) transport, disabling all other (built-in) transports like shared memory, which are often the cause of these problems. This makes discovery and communication more robust and predictable across different deployment scenarios.

Instructions

1. Create or modify a Fast DDS XML Profile

If you do not already have a Fast DDS XML configuration, create a new file (e.g., fastdds_profile.xml) with the following content:

<?xml version="1.0" encoding="UTF-8" ?>

<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles" >
    <transport_descriptors>
        <transport_descriptor>
            <transport_id>UdpTransport</transport_id>
            <type>UDPv4</type>
        </transport_descriptor>
    </transport_descriptors>

    <participant profile_name="udp_transport_profile" is_default_profile="true">
        <rtps>
            <userTransports>
                <transport_id>UdpTransport</transport_id>
            </userTransports>
            <useBuiltinTransports>false</useBuiltinTransports>
        </rtps>
    </participant>
</profiles>

If you already have a Fast DDS XML profile file, add the <transport_descriptor> and <userTransports> sections above, and make sure <useBuiltinTransports>false</useBuiltinTransports> is set inside your <participant> profile.

2. Configure ROS 2 and your plugin to Use the Profile

Set the FASTRTPS_DEFAULT_PROFILES_FILE environment variable to the path of your modified XML file, for example:

export FASTRTPS_DEFAULT_PROFILES_FILE=/path/to/fastdds_profile.xml

You can add this line to your shell's startup script (e.g., ~/.bashrc or ~/.zshrc) to make it persistent across sessions.

Update the agent settings to set the Fast DDS profile file, by adding the FASTRTPS_DEFAULT_PROFILES_FILE environment variable to the envVariables section of your agent-settings.json:

"envVariables": {
    "LD_LIBRARY_PATH": "/opt/ros/humble/opt/rviz_ogre_vendor/lib:/opt/ros/humble/lib/x86_64-linux-gnu:/opt/ros/humble/lib",
    "RMW_IMPLEMENTATION": "rmw_fastrtps_cpp",
    "FASTRTPS_DEFAULT_PROFILES_FILE": "/path/to/fastdds_profile.xml"
}

Restart the Agent
- Restart your ROS 2 nodes and the Rocos agent.

What this Does

Forces Fast DDS to use the UDPv4 network transport for all node discovery and topic communication.
Disables all built-in transports (especially shared memory) that may cause connection issues in some environments.
Offers a robust and predictable setup for most single-machine and multi-machine deployments.

Additional Notes

This configuration is safe and common in the ROS 2 community, especially in Docker, VMs, or complex network setups.
Advanced users can further customize UDP transport options; refer to the official Fast DDS documentation for details.
This workaround does not break compatibility with other nodes but may lead to reduced performance for intra-process (local) communication compared to shared memory in some specific scenarios.
If you continue to experience issues, consider switching to Cyclone DDS by installing and setting RMW_IMPLEMENTATION=rmw_cyclonedds_cpp in your environment variables, which is often more reliable in diverse network conditions. You may need to install the Cyclone DDS package if it's not already available:

sudo apt install ros-$ROS_DISTRO-rmw-cyclonedds-cpp

Installing The Plugin​

Data Model​

Receiving (Upstream) Messages​

Sending (Downstream) Messages​

Configuration​

Troubleshooting Node Discovery Issues with Fast DDS​

Symptom​

Solution: Use a Custom Fast DDS UDPv4 XML Profile​

Instructions​

What this Does​

Additional Notes​