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 Handle for the ROS 2 middleware protocol, widely used in the robotics field.

This System Handle 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.

Dependencies

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

ROS 2: Foxy/Galactic ROS 2 distribution.

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 Handle, 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.

Examples

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

Some of these examples, where the 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 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.