ros2

ROS 2 Bindings

This document defines how to describe ROS 2-specific information in AsyncAPI.

It applies to all distributions of ROS 2.

Version

Current version is 0.1.0.

Server Binding Object

This object contains information about the server representation in ROS 2. ROS 2 can use a vast variety of middleware implementations. This document focuses on DDS and Zenoh middleware implementations. DDS-based ROS 2 implementations are per default decentralized with no central server, so the field host can be set to none. For more information on DDS tuning, you can visit the DDS Tuning Guide. When using Zenoh, the host field specifies the Zenoh Router IP address.

Fixed Fields

Field Name	Type	Description
rmwImplementation	string	Specifies the ROS 2 middleware implementation to be used. Valid values include the different ROS 2 middleware vendors (RMW) like rmw_fastrtps_cpp (Fast DDS) or rmw_zenoh_cpp (Zenoh). This determines the underlying middleware implementation that handles communication.
domainId	integer	All ROS 2 nodes use domain ID 0 by default. To prevent interference between different groups of computers running ROS 2 on the same network, a group can be set with a unique domain ID. Must be a non-negative integer less than 232.

Examples

servers:
  ros2:
    host: none
    protocol: ros2
    protocolVersion: humble
    bindings:
      ros2:
        rmwImplementation: rmw_fastrtps_cpp
        domainId: 0

Channel Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Operation Binding Object

This object contains information about the ROS 2 node.

Fixed Fields

Field Name	Type	Description
role	string	Specifies the ROS 2 type of the node for this operation. If the action is send, valid values for the role are: publisher, action_client, service_client. If the action is receive, valid values for the role are: subscriber, action_server, service_server. This defines how the node will interact with the associated topic, service or action.
node	string	The name of the ROS 2 node that implements this operation.
qosPolicies	Quality of Service Policy Object	Quality of Service (QoS) for the topic.

Quality of Service Object

This object contains ROS 2 specific information about the Quality of Service policies. More information here: https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies

Field Name	Type	Description
reliability	string	One of best_effort or reliable. More information here: ROS 2 QoS
history	string	One of keep_last, keep_all or unknown. More information here: ROS 2 QoS
durability	string	One of transient_local or volatile. More information here: ROS 2 QoS
lifespan	integer	The maximum amount of time between the publishing and the reception of a message without the message being considered stale or expired. -1 means infinite.
deadline	integer	The expected maximum amount of time between subsequent messages being published to a topic. -1 means infinite.
liveliness	string	One of automatic or manual. More information here: ROS 2 QoS
leaseDuration	integer	The maximum period of time a publisher has to indicate that it is alive before the system considers it to have lost liveliness. -1 means infinite.

Examples

ROS 2 subscriber example:

receiveCmdVel:
  action: receive
  channel:
    $ref: "#/channels/CmdVel"
  bindings:
    ros2:
      role: subscriber
      node: /turtlesim
        qosPolicies:
          history: unknown
          reliability: reliable
          durability: volatile
          lifespan: -1
          deadline: -1
          liveliness: automatic
          leaseDuration: -1

ROS 2 publisher example:

 Pose:
    action: receive
    channel:
      $ref: "#/channels/Pose"
    bindings:
      ros2:
        role: publisher
        node: /turtlesim

ROS 2 service server example:

SetPen:
    action: receive
    channel:
      $ref: "#/channels/SetPenRequest"
    reply:
      channel:
        $ref: "#/channels/SetPenReply"
    bindings:
      ros2:
        role: service_server
        node: /turtlesim

ROS 2 service client example:

SetPen:
    action: send
    channel:
      $ref: "#/channels/SetPenRequest"
    reply:
      channel:
        $ref: "#/channels/SetPenReply"
    bindings:
      ros2:
        role: service_client
        node: /node_client

ROS 2 action server example:

receiveRotateAbsolute:
  action: receive
  channel:
    $ref: "#/channels/RotateAbsoluteRequest"
  reply:
    channel:
      $ref: "#/channels/RotateAbsoluteReply"
  bindings:
    ros2:
      role: action_server
      node: /turtlesim

ROS 2 action client example:

RotateAbsolute:
    action: send
    channel:
      $ref: "#/channels/RotateAbsoluteRequest"
    reply:
      channel:
        $ref: "#/channels/RotateAbsoluteReply"
    bindings:
      ros2:
        role: action_client
        node: /teleop_turtle

Message Binding Object

While this object DOES NOT contain any ROS 2 specific properties, it is important to understand how to express the different ROS 2 data types in AsyncAPI message types and formats.

ROS 2 Type	AsyncAPI Type	AsyncAPI Format
bool	boolean	boolean
byte	string	octet
char	integer	uint8
float32	number	float
float64	number	double
int8	integer	int8
uint8	integer	uint8
int16	integer	int16
uint16	integer	uint16
int32	integer	int32
uint32	integer	uint32
int64	integer	int64
uint64	integer	uint64
string	string	string
array	array	--

It is important to understand that the message header of the AsyncAPI specification does not map with the message header in ROS 2. For this reason, the AsyncAPI message header will be ignored. If you want to define the header of a message in ROS 2, you should put in the payload of the message. Example:

channels:
  PointCloud:
    address: /pointCloud
    messages:
      CompressedPointCloud2:
        $ref: "#/components/messages/CompressedPointCloud2"
components:
  CompressedPointCloud2:
    tags:
      - name: msg
    payload:
      type: object
      properties:
        header:
          $ref: "#/components/messages/std_msgs/header/payload"
        height:
          $ref: "#/components/messages/uint32/payload"
        width:
          $ref: "#/components/messages/uint32/payload"
        fields:
          $ref: "#/components/messages/sensor_msgs/PointField/payload"
        is_bigendian:
          $ref: "#/components/messages/bool/payload"
        point_step:
          $ref: "#/components/messages/uint32/payload"
        row_step:
          $ref: "#/components/messages/uint32/payload"
        compressed_data:
          $ref: "#/components/messages/uint8/payload"
        is_dense:
          $ref: "#/components/messages/bool/payload"
        format:
          $ref: "#/components/messages/string/payload"     

Complete example:

From the AsyncAPI specification example it could be extracted that:

• It consist on a ROS 2 Jazzy application running with Fast DDS as RMW.

• /turtlesim node is a subscriber of the /turtle1/cmd_vel topic and its qos policies.

• The interface of the /turtle1/cmd_vel topic is Twist that has a nested type: Vector3. Both of them are part of the standard package geometry_msgs.

• Vector3 has already the types converted to AsyncAPI types and formats (number and double), instead of using the ROS 2 types.

• There is one file (head-asyncapi.yaml) that references the different standard/custom packages. This packages contains the strucute of its messages.

  ├── interfaces
  │ ├── geometry_msgs.yaml
  │ ├── std_msgs.yaml
  │ ├── <custom_pkg_msgs>.yaml
  │ └── ....
  └── head-asyncapi.yaml
  

head-asyncapi.yaml

asyncapi: 3.0.0
info:
  title: Turtlesim example for ROS 2
  version: 1.0.0

servers:
  ros2:
    host: none
    protocol: ros2
    protocolVersion: jazzy
    bindings:
      ros2:
        rmwImplementation: rmw_fastrtps_cpp
        domainId: 0

channels:
  CmdVel:
    address: /turtle1/cmd_vel
    messages:
      Twist:
        $ref: ./interfaces/geometry_msgs.yaml#/components/messages/Twist

operations:
  CmdVel:
    action: receive
    channel:
      $ref: "#/channels/CmdVel"
    bindings:
      ros2:
        role: subscriber
        node: /turtlesim
        qosPolicies:
          history: unknown
          reliability: reliable
          durability: volatile
          lifespan: -1
          deadline: -1
          liveliness: automatic
          leaseDuration: -1

./interfaces/geometry_msgs.yaml

asyncapi: 3.0.0
info:
  title: geometry_msgs
  version: 1.0.0
components:
  messages:
    Twist:
      tags:
        - name: msg
      payload:
        type: object
        properties:
          linear:
            $ref: "#/components/messages/Vector3/payload"
          angular:
            $ref: "#/components/messages/Vector3/payload"
    Vector3:
      payload:
        properties:
          x:
            type: number
            format: double
          y:
            type: number
            format: double
          z:
            type: number
            format: double