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

1servers:
2  ros2:
3    host: none
4    protocol: ros2
5    protocolVersion: humble
6    bindings:
7      ros2:
8        rmwImplementation: rmw_fastrtps_cpp
9        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:

1receiveCmdVel:
2  action: receive
3  channel:
4    $ref: "#/channels/CmdVel"
5  bindings:
6    ros2:
7      role: subscriber
8      node: /turtlesim
9        qosPolicies:
10          history: unknown
11          reliability: reliable
12          durability: volatile
13          lifespan: -1
14          deadline: -1
15          liveliness: automatic
16          leaseDuration: -1

ROS 2 publisher example:

1 Pose:
2    action: receive
3    channel:
4      $ref: "#/channels/Pose"
5    bindings:
6      ros2:
7        role: publisher
8        node: /turtlesim

ROS 2 service server example:

1SetPen:
2    action: receive
3    channel:
4      $ref: "#/channels/SetPenRequest"
5    reply:
6      channel:
7        $ref: "#/channels/SetPenReply"
8    bindings:
9      ros2:
10        role: service_server
11        node: /turtlesim

ROS 2 service client example:

1SetPen:
2    action: send
3    channel:
4      $ref: "#/channels/SetPenRequest"
5    reply:
6      channel:
7        $ref: "#/channels/SetPenReply"
8    bindings:
9      ros2:
10        role: service_client
11        node: /node_client

ROS 2 action server example:

1receiveRotateAbsolute:
2  action: receive
3  channel:
4    $ref: "#/channels/RotateAbsoluteRequest"
5  reply:
6    channel:
7      $ref: "#/channels/RotateAbsoluteReply"
8  bindings:
9    ros2:
10      role: action_server
11      node: /turtlesim

ROS 2 action client example:

1RotateAbsolute:
2    action: send
3    channel:
4      $ref: "#/channels/RotateAbsoluteRequest"
5    reply:
6      channel:
7        $ref: "#/channels/RotateAbsoluteReply"
8    bindings:
9      ros2:
10        role: action_client
11        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:

1channels:
2  PointCloud:
3    address: /pointCloud
4    messages:
5      CompressedPointCloud2:
6        $ref: "#/components/messages/CompressedPointCloud2"
7components:
8  CompressedPointCloud2:
9    tags:
10      - name: msg
11    payload:
12      type: object
13      properties:
14        header:
15          $ref: "#/components/messages/std_msgs/header/payload"
16        height:
17          $ref: "#/components/messages/uint32/payload"
18        width:
19          $ref: "#/components/messages/uint32/payload"
20        fields:
21          $ref: "#/components/messages/sensor_msgs/PointField/payload"
22        is_bigendian:
23          $ref: "#/components/messages/bool/payload"
24        point_step:
25          $ref: "#/components/messages/uint32/payload"
26        row_step:
27          $ref: "#/components/messages/uint32/payload"
28        compressed_data:
29          $ref: "#/components/messages/uint8/payload"
30        is_dense:
31          $ref: "#/components/messages/bool/payload"
32        format:
33          $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.

1├── interfaces
2│ ├── geometry_msgs.yaml
3│ ├── std_msgs.yaml
4│ ├── <custom_pkg_msgs>.yaml
5│ └── ....
6└── head-asyncapi.yaml

head-asyncapi.yaml

1asyncapi: 3.0.0
2info:
3  title: Turtlesim example for ROS 2
4  version: 1.0.0
5
6servers:
7  ros2:
8    host: none
9    protocol: ros2
10    protocolVersion: jazzy
11    bindings:
12      ros2:
13        rmwImplementation: rmw_fastrtps_cpp
14        domainId: 0
15
16channels:
17  CmdVel:
18    address: /turtle1/cmd_vel
19    messages:
20      Twist:
21        $ref: ./interfaces/geometry_msgs.yaml#/components/messages/Twist
22
23operations:
24  CmdVel:
25    action: receive
26    channel:
27      $ref: "#/channels/CmdVel"
28    bindings:
29      ros2:
30        role: subscriber
31        node: /turtlesim
32        qosPolicies:
33          history: unknown
34          reliability: reliable
35          durability: volatile
36          lifespan: -1
37          deadline: -1
38          liveliness: automatic
39          leaseDuration: -1

./interfaces/geometry_msgs.yaml

1asyncapi: 3.0.0
2info:
3  title: geometry_msgs
4  version: 1.0.0
5components:
6  messages:
7    Twist:
8      tags:
9        - name: msg
10      payload:
11        type: object
12        properties:
13          linear:
14            $ref: "#/components/messages/Vector3/payload"
15          angular:
16            $ref: "#/components/messages/Vector3/payload"
17    Vector3:
18      payload:
19        properties:
20          x:
21            type: number
22            format: double
23          y:
24            type: number
25            format: double
26          z:
27            type: number
28            format: double

On this page

ros2

ROS 2 Bindings

Version

Server Binding Object

Fixed Fields

Examples

Channel Binding Object

Operation Binding Object

Fixed Fields

Quality of Service Object

Examples

Message Binding Object

Complete example: