From 7872c4f1b48cf06ac7820106d168353e8c852f2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= Date: Fri, 7 Mar 2025 12:12:24 +0100 Subject: [PATCH 01/12] Initial ROS2 AsyncAPI contribution by SIEMENS AG. This was a team effort and is corporate internal legally cleared for OSS contribution. --- README.md | 1 + ros2/README.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 ros2/README.md diff --git a/README.md b/README.md index 96e67ce1..a442091b 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ This repository contains the specifications for each AsyncAPI protocol binding. * [NATS binding](./nats) * [Pulsar](./pulsar) * [Redis binding](./redis) +* [ROS2](./ros2) * [SNS binding](./sns) * [Solace binding](./solace) * [SQS binding](./sqs) diff --git a/ros2/README.md b/ros2/README.md new file mode 100644 index 00000000..2896a9af --- /dev/null +++ b/ros2/README.md @@ -0,0 +1,185 @@ +# ROS 2 Bindings + +This document defines how to describe ROS 2-specific information in AsyncAPI. + +It applies to all versions of ROS 2 (foxy, galactic, humble, iron, jazzy). + + + +## 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 either DDS or Zenoh as its middleware. +DDS is decentralized with no central server, so the field `host` can set to `localhost`. +When using Zenoh, the `host` field specifies the Zenoh Router IP address. + +###### Fixed Fields + +Field Name | Type | ROS 2 Versions | Description +---|:---:|:---:|---| +`rmwImplementation` | string | all | Specifies the ROS 2 middleware implementation to be used. Valid values include `rmw_fastrtps_cpp` (Fast DDS), `rmw_cyclonedds_cpp` (Cyclone DDS), `rmw_connext_cpp` (RTI Connext), and `rmw_zenoh_cpp` (Zenoh). This determines the underlying middleware implementation that handles communication. +`domainId` | integer | all | 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 + +```yaml +servers: + ros2: + host: localhost + protocol: ros2 + protocolVersion: humble + bindings: + ros2: + rmwImplementation: rmw_fastrtps_cpp + domainId: 0 +``` + + + + +## Channel Binding Object + +A channel represents a ROS 2 topic, service or action interface. + +This object DOES NOT contain any ROS 2 specific properties. + +Example - ROS 2 topic: + +```yaml + address: /turtle1/cmd_vel + messages: + TwistMsg: + $ref: '#/components/messages/TwistMsg' +``` +Example - ROS 2 action: + +```yaml + RotateAbsoluteRequest: + address: /turtle1/rotate_absolute + messages: + RotateAbsoluteActionRequest: + $ref: '#/components/messages/RotateAbsoluteActionRequest' + + RotateAbsoluteReply: + address: /turtle1/rotate_absolute + messages: + RotateAbsoluteActionResult: + $ref: '#/components/messages/RotateAbsoluteActionResult' + RotateAbsoluteActionFeedback: + $ref: '#/components/messages/RotateAbsoluteActionFeedback' +``` + + + +## Operation Binding Object + +AsyncAPI operations with their `send` and `receive` actions map directly to ROS 2 subscribers, publishers, actions or services. +- send -> `publisher`, `action_client`, `service_client` +- receive -> `subscriber`, `action_server`, `service_server` + +###### Fixed Fields + +Field Name | Type | ROS 2 Versions | Description +---|:---:|:---:|---| +`type` | string | all | Specifies the ROS 2 type of the node for this operation. Valid values are: `publisher`, `subscriber`, `service_client`, `service_server`, `action_client`, `action_server`. This defines how the node will interact with the associated topic or action. +`node` | string | all | The name of the ROS 2 node that implements this operation. +`qosPolicies` | object | all | 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 | ROS 2 Versions | Description +---|:---:|:---:|---| +`reliability` | string | all | One of `best_effort` or `reliable`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`history` | string | all | One of `keep_last`, `keep_all` or `unknown`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`durability` | string | all | One of `transient_local` or `volatile`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`lifespan` | integer | all | 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 | all | The expected maximum amount of time between subsequent messages being published to a topic. `-1` means infinite. +`liveliness` | string | all | One of `automatic`or `manual`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`leaseDuration` | integer | all | 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: + +```yaml + 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 action Server example: + +```yaml + receiveRotateAbsolute: + action: receive + channel: + $ref: "#/channels/RotateAbsoluteRequest" + reply: + channel: + $ref: "#/channels/RotateAbsoluteReply" + bindings: + ros2: + role: action_server + node: /turtlesim +``` + + + + +## Message Binding Object + +ROS 2 message types (defined in .msg/.srv/.aciton files) are mapped to AsyncAPI message payloads. + +This object DOES NOT contain any ROS 2 specific properties. + +```yaml +Vector3Msg: + type: object + properties: + x: + type: number + format: double + y: + type: number + format: double + z: + type: number + format: double +``` + +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 | -- \ No newline at end of file From a1e98767d81b46743485b8bb829546f6a6fe6c97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= Date: Tue, 1 Apr 2025 18:20:54 +0200 Subject: [PATCH 02/12] feat: apply initial suggestions from Fran in the pull request --- ros2/README.md | 180 ++++++++++++++++++++++++------------------------- 1 file changed, 87 insertions(+), 93 deletions(-) diff --git a/ros2/README.md b/ros2/README.md index 2896a9af..1af67031 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -2,7 +2,7 @@ This document defines how to describe ROS 2-specific information in AsyncAPI. -It applies to all versions of ROS 2 (foxy, galactic, humble, iron, jazzy). +It applies to all [distributions of ROS 2](https://docs.ros.org/en/rolling/Releases.html). @@ -16,15 +16,15 @@ Current version is `0.1.0`. This object contains information about the server representation in ROS 2. ROS 2 can use either DDS or Zenoh as its middleware. -DDS is decentralized with no central server, so the field `host` can set to `localhost`. +DDS is decentralized with no central server, so the field `host` can be set to `localhost`. When using Zenoh, the `host` field specifies the Zenoh Router IP address. ###### Fixed Fields -Field Name | Type | ROS 2 Versions | Description ----|:---:|:---:|---| -`rmwImplementation` | string | all | Specifies the ROS 2 middleware implementation to be used. Valid values include `rmw_fastrtps_cpp` (Fast DDS), `rmw_cyclonedds_cpp` (Cyclone DDS), `rmw_connext_cpp` (RTI Connext), and `rmw_zenoh_cpp` (Zenoh). This determines the underlying middleware implementation that handles communication. -`domainId` | integer | all | 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. +Field Name | Type | Description +---|:---:|---| +`rmwImplementation` | string | Specifies the ROS 2 middleware implementation to be used. Valid values include the different [ROS 2 middleware vendors](https://docs.ros.org/en/rolling/Concepts/Intermediate/About-Different-Middleware-Vendors.html). 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 @@ -45,65 +45,38 @@ servers: ## Channel Binding Object -A channel represents a ROS 2 topic, service or action interface. - -This object DOES NOT contain any ROS 2 specific properties. - -Example - ROS 2 topic: - -```yaml - address: /turtle1/cmd_vel - messages: - TwistMsg: - $ref: '#/components/messages/TwistMsg' -``` -Example - ROS 2 action: - -```yaml - RotateAbsoluteRequest: - address: /turtle1/rotate_absolute - messages: - RotateAbsoluteActionRequest: - $ref: '#/components/messages/RotateAbsoluteActionRequest' - - RotateAbsoluteReply: - address: /turtle1/rotate_absolute - messages: - RotateAbsoluteActionResult: - $ref: '#/components/messages/RotateAbsoluteActionResult' - RotateAbsoluteActionFeedback: - $ref: '#/components/messages/RotateAbsoluteActionFeedback' -``` +This object MUST NOT contain any properties. Its name is reserved for future use. ## Operation Binding Object -AsyncAPI operations with their `send` and `receive` actions map directly to ROS 2 subscribers, publishers, actions or services. -- send -> `publisher`, `action_client`, `service_client` -- receive -> `subscriber`, `action_server`, `service_server` +This object contains information about the ROS 2 node. ###### Fixed Fields -Field Name | Type | ROS 2 Versions | Description ----|:---:|:---:|---| -`type` | string | all | Specifies the ROS 2 type of the node for this operation. Valid values are: `publisher`, `subscriber`, `service_client`, `service_server`, `action_client`, `action_server`. This defines how the node will interact with the associated topic or action. -`node` | string | all | The name of the ROS 2 node that implements this operation. -`qosPolicies` | object | all | Quality of Service (QoS) for the topic. +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](#QoSPolicyObject) | 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 | ROS 2 Versions | Description ----|:---:|:---:|---| -`reliability` | string | all | One of `best_effort` or `reliable`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) -`history` | string | all | One of `keep_last`, `keep_all` or `unknown`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) -`durability` | string | all | One of `transient_local` or `volatile`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) -`lifespan` | integer | all | 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 | all | The expected maximum amount of time between subsequent messages being published to a topic. `-1` means infinite. -`liveliness` | string | all | One of `automatic`or `manual`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) -`leaseDuration` | integer | all | 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. +Field Name | Type | Description +---|:---:|---| +`reliability` | string | One of `best_effort` or `reliable`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`history` | string | One of `keep_last`, `keep_all` or `unknown`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`durability` | string | One of `transient_local` or `volatile`. More information here: [ROS 2 QoS](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`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](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-policies) +`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: @@ -126,60 +99,81 @@ ROS 2 subscriber example: liveliness: automatic leaseDuration: -1 ``` -ROS 2 action Server example: +ROS 2 publisher example: ```yaml - receiveRotateAbsolute: + Pose: action: receive channel: - $ref: "#/channels/RotateAbsoluteRequest" + $ref: "#/channels/Pose" + bindings: + ros2: + role: publisher + node: /turtlesim +``` + +ROS 2 service server example: +```yaml +SetPen: + action: receive + channel: + $ref: "#/channels/SetPenRequest" reply: channel: - $ref: "#/channels/RotateAbsoluteReply" + $ref: "#/channels/SetPenReply" bindings: ros2: - role: action_server + role: service_server node: /turtlesim ``` +ROS 2 service client example: +```yaml +SetPen: + action: send + channel: + $ref: "#/channels/SetPenRequest" + reply: + channel: + $ref: "#/channels/SetPenReply" + bindings: + ros2: + role: service_client + node: /node_client +``` - - -## Message Binding Object - -ROS 2 message types (defined in .msg/.srv/.aciton files) are mapped to AsyncAPI message payloads. - -This object DOES NOT contain any ROS 2 specific properties. +ROS 2 action server example: +```yaml +receiveRotateAbsolute: + action: receive + channel: + $ref: "#/channels/RotateAbsoluteRequest" + reply: + channel: + $ref: "#/channels/RotateAbsoluteReply" + bindings: + ros2: + role: action_server + node: /turtlesim +``` +ROS 2 action client example: ```yaml -Vector3Msg: - type: object - properties: - x: - type: number - format: double - y: - type: number - format: double - z: - type: number - format: double +RotateAbsolute: + action: send + channel: + $ref: "#/channels/RotateAbsoluteRequest" + reply: + channel: + $ref: "#/channels/RotateAbsoluteReply" + bindings: + ros2: + role: action_client + node: /teleop_turtle ``` -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 | -- \ No newline at end of file + + +## Message Binding Object + +This object MUST NOT contain any properties. Its name is reserved for future use. \ No newline at end of file From 463fb3d3570cfcb51f5fe609ef348c343e0cbcf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= Date: Tue, 1 Apr 2025 18:21:51 +0200 Subject: [PATCH 03/12] feat: update README with comments from the PR. 1. Include in the server binding links and change to none instead of localhost. 2. Include the link to the non-negative less than 232. 3. Explain better the message binding with links. 4. Put at the end a whole example of a ROS application with its explanation. --- ros2/README.md | 131 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 110 insertions(+), 21 deletions(-) diff --git a/ros2/README.md b/ros2/README.md index 1af67031..b3331203 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -16,22 +16,23 @@ Current version is `0.1.0`. This object contains information about the server representation in ROS 2. ROS 2 can use either DDS or Zenoh as its middleware. -DDS is decentralized with no central server, so the field `host` can be set to `localhost`. +DDS is decentralized with no central server, so the field `host` can set to `none`. +For more information on DDS tuning, you can visit the [DDS Tuning Guide](https://docs.ros.org/en/rolling/How-To-Guides/DDS-tuning.html). 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](https://docs.ros.org/en/rolling/Concepts/Intermediate/About-Different-Middleware-Vendors.html). 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. +`rmwImplementation` | string | Specifies the ROS 2 middleware implementation to be used. Valid values include the different [ROS 2 middleware vendors (RMW)](https://docs.ros.org/en/rolling/Concepts/Intermediate/About-Different-Middleware-Vendors.html) 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](https://docs.ros.org/en/rolling/Concepts/Intermediate/About-Domain-ID.html). ### Examples ```yaml servers: ros2: - host: localhost + host: none protocol: ros2 protocolVersion: humble bindings: @@ -82,22 +83,22 @@ Field Name | Type | Description ROS 2 subscriber example: ```yaml - 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 +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: @@ -176,4 +177,92 @@ RotateAbsolute: ## Message Binding Object -This object MUST NOT contain any properties. Its name is reserved for future use. \ No newline at end of file +While this object DOES NOT contain any ROS 2 specific properties, it is important to understand how to express the different [ROS2 data types](https://design.ros2.org/articles/legacy_interface_definition.html#:~:text=to%20IDL%20types-,ROS%20type,string,-The%20mapping%20of) in [AsyncAPI message types and formats](https://www.asyncapi.com/docs/reference/specification/v3.0.0#dataTypeFormat:~:text=The%20formats%20defined%20by%20the%20AsyncAPI%20Specification%20are%3A). + +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 | -- + + +## Complete example: +From the AsyncAPI specification example it could be extracted that: +- It consist on a ROS2 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` +- `Vector3` has already the types converted to AsyncAPI types and formats (number and double), instead of using the ROS2 types. + +```yaml +asyncapi: 3.0.0 +info: + title: Head AsyncAPI definition + version: 1.0.0 +servers: + ros2: + host: none + protocol: ros2 + protocolVersion: jazzy + bindings: + x-ros2: + rmwImplementation: rmw_fastrtps_cpp + domainId: 0 +channels: + Twist: + address: /turtle1/cmd_vel + messages: + Twist: + $ref: "#/components/messages/Twist" +operations: + Twist: + action: receive + channel: + $ref: "#/channels/Twist" + bindings: + x-ros2: + role: subscriber + node: /turtlesim + qosPolicies: + history: unknown + reliability: reliable + durability: volatile + lifespan: -1 + deadline: -1 + liveliness: automatic + leaseDuration: -1 +components: + 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 +``` \ No newline at end of file From f6380c356bfbe8fc7cb4c49c7636a328dd39301c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= Date: Fri, 4 Apr 2025 14:06:29 +0200 Subject: [PATCH 04/12] added message header definition and complete example --- ros2/README.md | 122 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 92 insertions(+), 30 deletions(-) diff --git a/ros2/README.md b/ros2/README.md index b3331203..50b639a6 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -197,41 +197,94 @@ 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 ROS2. +For this reason, the AsyncAPI message header will be ignored. If you want to define the header of a message in ROS2, you should put in the payload of the message. [Example](https://docs.ros.org/en/ros2_packages/rolling/api/point_cloud_interfaces/msg/CompressedPointCloud2.html): + +```yaml +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 ROS2 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` +- 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 ROS2 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 + │ ├── .yaml + │ └── .... + └── head-asyncapi.yaml + ``` + +head-asyncapi.yaml ```yaml asyncapi: 3.0.0 info: - title: Head AsyncAPI definition + title: Turtlesim example for ROS 2 version: 1.0.0 + servers: ros2: host: none protocol: ros2 protocolVersion: jazzy bindings: - x-ros2: + ros2: rmwImplementation: rmw_fastrtps_cpp domainId: 0 + channels: - Twist: + CmdVel: address: /turtle1/cmd_vel messages: Twist: - $ref: "#/components/messages/Twist" + $ref: ./interfaces/geometry_msgs.yaml#/components/messages/Twist + operations: - Twist: + CmdVel: action: receive channel: - $ref: "#/channels/Twist" + $ref: "#/channels/CmdVel" bindings: - x-ros2: + ros2: role: subscriber node: /turtlesim qosPolicies: @@ -242,27 +295,36 @@ operations: deadline: -1 liveliness: automatic leaseDuration: -1 +``` + +./interfaces/geometry_msgs.yaml +```yaml +asyncapi: 3.0.0 +info: + title: geometry_msgs + version: 1.0.0 components: - 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 + 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 ``` \ No newline at end of file From 5e6bbc850c34f92539b39dad5ab49927b2488fbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= <6034322+gramss@users.noreply.github.com> Date: Mon, 7 Apr 2025 15:49:48 +0200 Subject: [PATCH 05/12] fix ros 2 typo Co-authored-by: Christophe Bedard --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a442091b..022fbc60 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ This repository contains the specifications for each AsyncAPI protocol binding. * [NATS binding](./nats) * [Pulsar](./pulsar) * [Redis binding](./redis) -* [ROS2](./ros2) +* [ROS 2](./ros2) * [SNS binding](./sns) * [Solace binding](./solace) * [SQS binding](./sqs) From 9654072641bac5731b15adeb418fc044332aaff4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Mon, 19 May 2025 11:54:08 +0200 Subject: [PATCH 06/12] Update ros2/README.md Co-authored-by: Christophe Bedard --- ros2/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ros2/README.md b/ros2/README.md index 50b639a6..fde9aafb 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -197,8 +197,8 @@ 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 ROS2. -For this reason, the AsyncAPI message header will be ignored. If you want to define the header of a message in ROS2, you should put in the payload of the message. [Example](https://docs.ros.org/en/ros2_packages/rolling/api/point_cloud_interfaces/msg/CompressedPointCloud2.html): +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](https://docs.ros.org/en/ros2_packages/rolling/api/point_cloud_interfaces/msg/CompressedPointCloud2.html): ```yaml channels: From 13162bf3c9a983d44375b14330d44fbc77d61033 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Mon, 19 May 2025 11:54:39 +0200 Subject: [PATCH 07/12] Update ros2/README.md Co-authored-by: Christophe Bedard --- ros2/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ros2/README.md b/ros2/README.md index fde9aafb..3b66f31d 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -177,7 +177,7 @@ RotateAbsolute: ## Message Binding Object -While this object DOES NOT contain any ROS 2 specific properties, it is important to understand how to express the different [ROS2 data types](https://design.ros2.org/articles/legacy_interface_definition.html#:~:text=to%20IDL%20types-,ROS%20type,string,-The%20mapping%20of) in [AsyncAPI message types and formats](https://www.asyncapi.com/docs/reference/specification/v3.0.0#dataTypeFormat:~:text=The%20formats%20defined%20by%20the%20AsyncAPI%20Specification%20are%3A). +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](https://design.ros2.org/articles/legacy_interface_definition.html#:~:text=to%20IDL%20types-,ROS%20type,string,-The%20mapping%20of) in [AsyncAPI message types and formats](https://www.asyncapi.com/docs/reference/specification/v3.0.0#dataTypeFormat:~:text=The%20formats%20defined%20by%20the%20AsyncAPI%20Specification%20are%3A). ROS 2 Type | AsyncAPI Type | AsyncAPI Format | ---|:---:|---| From 766a870c5e679e476dce34d2be3f34c50c6668f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Mon, 19 May 2025 11:56:02 +0200 Subject: [PATCH 08/12] Update ros2/README.md Co-authored-by: Christophe Bedard --- ros2/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ros2/README.md b/ros2/README.md index 3b66f31d..a045ec0e 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -238,7 +238,7 @@ components: ## Complete example: From the AsyncAPI specification example it could be extracted that: -- It consist on a ROS2 jazzy application running with Fast DDS as RMW. +- 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 ROS2 types. From 167b15ad5144ac47bd484911b5afeeb367818303 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Mon, 19 May 2025 11:56:10 +0200 Subject: [PATCH 09/12] Update ros2/README.md Co-authored-by: Christophe Bedard --- ros2/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ros2/README.md b/ros2/README.md index a045ec0e..3f6bef29 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -241,7 +241,7 @@ 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 ROS2 types. +- `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. ``` From 1c60da6a4d687a8122c5c8049d826e83f2c9c6e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= Date: Sat, 31 May 2025 14:56:05 +0200 Subject: [PATCH 10/12] final touches to address gavanderhoorn concerns regarding different rmw implementations --- ros2/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ros2/README.md b/ros2/README.md index 3f6bef29..dd232cf2 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -15,8 +15,8 @@ Current version is `0.1.0`. ## Server Binding Object This object contains information about the server representation in ROS 2. -ROS 2 can use either DDS or Zenoh as its middleware. -DDS is decentralized with no central server, so the field `host` can set to `none`. +ROS 2 can use a vast variety of [middleware implementations](https://docs.ros.org/en/rolling/Installation/RMW-Implementations.html). 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](https://docs.ros.org/en/rolling/How-To-Guides/DDS-tuning.html). When using Zenoh, the `host` field specifies the Zenoh Router IP address. From d64de7a4116dc5fd67d883ff84537d234280d44b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Gram=C3=9F?= Date: Thu, 4 Dec 2025 11:25:03 +0100 Subject: [PATCH 11/12] add @amparo-siemens and me as codeowners of the ros2 binding --- CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/CODEOWNERS b/CODEOWNERS index 6a8b7a5c..6118034e 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -17,3 +17,4 @@ /pulsar/ @VisualBean /sns/ @dpwdec @iancooper /sqs/ @dpwdec @iancooper +/ros2/ @amparo-siemens @gramss From be54d096f5e44f6a6a5116fc8545945e3c598c99 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Thu, 15 Jan 2026 19:08:50 +0100 Subject: [PATCH 12/12] Update CODEOWNERS for ros2 directory --- CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODEOWNERS b/CODEOWNERS index 6118034e..c9d1e192 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -17,4 +17,4 @@ /pulsar/ @VisualBean /sns/ @dpwdec @iancooper /sqs/ @dpwdec @iancooper -/ros2/ @amparo-siemens @gramss +/ros2/ @amparosancho @gramss