ROS 2 System Handle

Introduction

What is a System Handle?

A System Handle is a plugin that allows a certain middleware or communication protocol to speak the same language used by the eProsima Integration Service, that is, Extensible and Dynamic Topic Types for DDS (xTypes); specifically, Integration Service bases its intercommunication abilities on eProsima's open source implementation for the xTypes protocol, that is, eProsima xTypes.

The ROS 2 SystemHandle

This repository contains the source code of Integration Service System Handles for the ROS 2 middleware protocol, widely used in the robotics field. Two implementations can be distinguished: static one based on ROS 2 rclcpp and dynamic one based on Fast DDS (by the moment it is only available for the Publisher-Subscriber paradigm).

This System Handles can be used for two main purposes:

Connection between a ROS 2 application and an application running over a different middleware implementation. This is the classic use-case approach for Integration Service.
Connecting two ROS 2 applications running under different Domain IDs.

The main advantages of the Dynamic ROS 2 System Handle over the Static ROS 2 System Handle are the following ones:

It allows using types defined by IDL without previously generating and installing the ROS 2 Type Support for that type, which gives it a greater versatility with respect to the Static ROS 2 System Handle.
It is not necessary to decide which ROS 2 builtin types you are going to use during the compilation phase, as it allows you to use any of them.

Dependencies

This section provides a list of the dependencies needed in order to compile ROS 2 System Handles.

Static ROS 2 System Handle

ROS 2: Foxy/Galactic ROS 2 distribution.

Dynamic ROS 2 System Handle

Fast DDS: eProsima C++ implementation for DDS.

Configuration

Integration Service is configured by means of a YAML configuration file, which specifies the middlewares, topics and/or services involved in the intercommunication process, as well as their topic/service types and the data exchange flow. This configuration file is loaded during runtime, so there is no need to recompile any package before switching to a whole new intercommunication architecture.

To get a more precise idea on how these YAML files have to be filled and which fields they require in order to succesfully configure and launch an Integration Service project, please refer to the dedicated configuration section of the official documentation.

Regarding the ROS 2 System Handles, there are several specific parameters which can be configured for the ROS 2 middleware. All of these parameters are optional, and fall as suboptions of the main five sections described in the Configuration chapter of the Integration Service repository:

systems: The system type must be ros2. In addition to the type and types-from fields, the ROS 2 System Handle accepts the following specific configuration fields:
```
systems:
  ros2:
    type: ros2
    namespace: "/"
    node_name: "my_ros2_node"
    domain: 4
```
- namespace: The namespace of the ROS 2 node created by the ROS 2 System Handle.
- node_name: The ROS 2 System Handle node name.
- domain: Provides with an easy way to change the Domain ID of the ROS 2 entities created by the ROS 2 System Handle.
topics: The topic route must contain ros2 within its from or to fields. Additionally, the ROS 2 System Handle accepts the following topic specific configuration parameters, within the ros2 specific middleware configuration tag:
```
routes:
  ros2_to_ros1: { from: ros2, to: ros1 }

topics:
  hello_ros1:
    type: std_msgs/String
    route: ros2_to_ros1
    ros2: { qos: {
        deadline: { sec: 1, nanosec: 10},
        durability: VOLATILE,
        history: { kind: KEEP_LAST, depth: 10 },
        lifespan: { sec: 2, nanosec: 20 },
        liveliness: { kind: AUTOMATIC, sec: 2, nanosec: 0 },
        reliability: RELIABLE
      }}
```
- qos: The Quality of Service policies that are going to be applied to the ROS 2 entity involved in the pub-sub operation (in this case the publisher). This parameter accepts any of the QoS available for ROS 2:
  - deadline: This QoS policy raises an alarm when the frequency of new samples falls below a certain threshold, which can be defined by means of the sec and nanosec tags. On the publishing side, the deadline defines the maximum period in which the application is expected to supply a new sample. On the subscribing side, it defines the maximum period in which new samples should be received.
  - durability: A Publisher can send messages throughout a Topic even if there are no Subscribers on the network. This QoS defines how the system will behave regarding those samples that existed on the Topic before the Subscriber joins. There are two possible values: VOLATILE and TRANSIENT_LOCAL.
  - history: This QoS controls the behavior of the system when the value of an instance changes one or more times before it can be successfully communicated to the existing Subscriber entities.
    - kind: Controls if the service should deliver only the most recent values, all the intermediate values or do something in between. There are two possible values: KEEP_LAST and KEEP_ALL.
    - depth: Establishes the maximum number of samples that must be kept on the history. It only has effect if the kind is set to KEEP_LAST.
  - lifespan: Each data sample written by a Publisher has an associated expiration time beyond which the data is removed from the Publisher and Subscriber history. That expiration time can be defined by means of the sec and nanosec tags.
  - liveliness: This QoS controls the mechanism used by the service to ensure that a particular entity on the network is still alive.
    - kind: Establishes if the service needs to assert the liveliness automatically or if it needs to wait until the liveliness is asserted by the publishing side. There are two possible values: AUTOMATIC and MANUAL_BY_TOPIC.
    - lease_duration: Amount of time to wait since the last time the Publisher asserts its liveliness to consider that it is no longer alive. It can be defined by means of the sec and nanosec tags.
  - reliability: This QoS indicates the level of reliability offered and requested by the service. There are two possible values: RELIABLE and BEST_EFFORT.
The Dynamic ROS 2 System Handle has an additional parameter:
```
  systems:
    ros2:
      type: ros2_dynamic
      namespace: "/"
      node_name: "my_ros2_node"
      domain: 4
      using: [std_msgs/String, geometry_msgs]
```
- using: List of the ROS 2 builtin types or packages that want to be used in the communication.

Examples

There are several Integration Service examples using the Static ROS 2 System Handle available in the project's main source code repository.

Some of these examples, where the Static ROS 2 System Handle plays a different role in each of them, are introduced here.

ROS 2 - ROS 1 bridge (publisher - subscriber)

In this example, Integration Service uses both this Static ROS 2 System Handle and the ROS 1 System Handle to transmit data coming from a ROS 2 publisher into the ROS 1 data space, so that it can be consumed by a ROS 1 subscriber on the same topic, and viceversa.

The configuration file used by Integration Service for this example can be found here.