Invitation to Collaborate on AsyncAPI Specification for ROS2

General
,
1

Dear ROS Community Members,

image
image420×392 56.9 KB

We are excited to announce that we are crafting a standard message representation for ROS2 using AsyncAPI. A draft is already available on GitHub, and we warmly invite the ROS community to join us in refining this specification. Your input is invaluable, and we encourage you to participate in the ongoing discussions.

Right now, we have developed an AsyncAPI binding for ROS2, and there’s a vibrant conversation happening on GitHub. To enhance collaboration, we’re planning to hold an open discussion session. To help us find a time that suits everyone, please indicate your availability using the Microsoft Forms link below:

:backhand_index_pointing_right: Indicate Your Availability Here

image
image800×800 93.4 KB

Slot 1: 2025-04-08T12:00:00Z→2025-04-08T13:00:00Z

Slot 2: 2025-04-09T12:00:00Z→2025-04-09T13:00:00Z

Slot 3: 2025-04-10T08:00:00Z→2025-04-10T09:00:00Z

Slot 4: 2025-04-10T14:00:00Z→2025-04-10T15:00:00Z

If you’re interested in learning more about AsyncAPI and its significance for ROS2 users, we invite you to watch the ROSCon DE talk we presented last year:

:movie_camera: Watch the ROSCon DE Talk - PDF
( @destogl would you please help us access the video recording, please?)

Join the discussion on GitHub:

:rocket: AsyncAPI Specification Draft on GitHub

We look forward to your contributions and to meeting you all soon!

Best regards,

Florian

This Communication is part of the aerOS project that has received funding from the European Union’s Horizon Europe research and innovation programme under grant agreement Nº101069732

2 Likes
2

I’ve looked at the PR and posted some (very minor) comments.

Something that kept bothering me while reading up on AsyncAPI and reading the PR is the fact I’m not sure there isn’t a mismatch between (some of) the concepts in AsyncAPI and a typical ROS API (which I believe you’re trying to model using either one or multiple AsyncAPI documents).

The AsyncAPI specifically describes it as being used for modelling event driven architectures, which is certainly something ROS can be used for, but I’m wondering at which level services and actions would need to be described to really match with AsyncAPIs concepts (I believe the need to introduce custom properties for instance (role?) is a consequence of this).

Note: I’m not an AsyncAPI expert, far from it, so this may be all due to misunderstanding their documentation.

3

This is awesome! I’m pretty new to the community, and I want to be involved. Can I make useful contributions to this as a beginner? Would love some guidance.

4

I want to point out that there is an existing way to define a ROS 2 API - NoDL. I believe AsyncAPI may be worth the shot, even though NoDL is made specifically for ROS 2 given AsyncAPI has a sizable community and includes tools for visualizing the API as well as standards and examples for generating code from an API spec. While this may feel like the xkcd standards situation, AsyncAPI has received a lot more support from other open-source communities, while NoDL seems to have been abandoned shortly after conception. Just my 2c, would love to hear other opinions.

2 Likes
5

Hello again,

Thank you for your valuable input so far! I am looking forward to discuss them with you tomorrow.

The poll has drawn towards the first meeting slot.
So therefore, I’ll post here the link for our meeting tomorrow and warmly invite all interested parties to join the open meeting.

Currently, this is our agenda:

image
image1600×900 130 KB

Time is: Slot 1: 2025-04-08T12:00:00Z→2025-04-08T13:00:00Z

In the meantime, there is now also the recording available to my ROSConDE`24 talk about AsyncAPI:

Looking forward to tomorrow!
Cheers :clinking_beer_mugs:

1 Like
6

Unfortunately that time slot excludes West Coast USA (except maybe a few morning birds at 5am). If we can’t do an additional time slot, can the session be recorded and shared?

7

We are having our discussion here now:

We try to record it and find another session for the west cost

2 Likes
8

Thanks! I’ll catch up this afternoon. Thanks for spearheading this!

9

When is the next meeting?

---- Replied Message ----

From | Florian Gramß via ROS Discoursenotifications@ros.discoursemail.com |

  • | - |
    Date | 04/08/2025 20:27 |
    To | 15651859189@163.com |
    Cc | |
    Subject | [ROS Discourse] [General] Invitation to Collaborate on AsyncAPI Specification for ROS2 |

| flo
April 8 |

  • | - |

We are having our discussion here now:

Microsoft Teams
### Join conversation

We try to record it and find another session for the west cost

10

:fire: Meeting Minutes :robot:

Please feel free to reach out for the meeting recording at research.industry@siemens.com if needed. We would appreciate your feedback on interest in follow-up meetings—please thumbs up to this message if interested in having a call on 2025-04-17T15:00:00Z→2025-04-17T16:00:00Z!

:bookmark_tabs: Attendees:

Introduction: Florian introduced the purpose of the meeting, explaining Siemens’ efforts on an AsyncAPI specification for ROS 2, originally presented at ROSCon Germany. Progress has led to the contribution phase with an open pull request: GitHub PR #270. The aim is to receive community feedback rather than unilaterally defining the specification.

:speech_balloon: Key Discussion Points

Message Type References

  • Discussed how to reference message types in the AsyncAPI specification
  • Two approaches were considered:
    1. File-based references (copying the message definition)
    2. URL-based references (pointing to message definitions stored elsewhere)

Repository Structure Considerations

  • Ramon mentioned their team is moving from multi-repository to mono-repository development to keep things in sync
  • Different approaches might be needed based on repository structure:
    • For mono-repositories: file-based references might be sufficient
    • For distributed/multi-repositories: URL-based references might be more appropriate
  • Even with multiple repositories, once checked out locally, relative references could work

Documentation Concerns

  • There was a concern about duplicating the same information in different formats
  • A suggestion was made to dynamically pull information from URLs (either online or local) when viewing documentation

Ideas and Suggestions

  1. CI Integration
    • Implement CI checks to verify documentation and AsyncAPI specs remain in sync
  2. Build System Integration
    • Add code generation as part of the colcon build process to obtain directly the AsyncAPI specification
  3. Validation
    • Develop a validator to ensure implementations comply with standards
    • Could be integrated into CI pipelines
  4. Documentation Distribution
    • Some AsyncAPI HTML format documentation should be part of a code repository (like github)
  5. Repository Structure Considerations
    • Consider implications of mono-repository vs. multiple-repository setups
    • URL references to message definitions (online or offline) might be beneficial

Next Steps:

  1. Proceed with the Initial Pull Request:
    • Finalize the PR for ROS 2 integration into AsyncAPI as introduced by ROS2 bindings #254.
  2. Decision on URL-based Referencing:
    • Determine the feasibility and agreement on using URL-based references for message types.
  3. Documentation Management:
    • Ensure that AsyncAPI files are represented and appropriately managed on GitHub as both file and HTML formats.
  4. Engage with Community:
    • Continuously gather feedback to determine interest in follow-up meetings.
    • Evaluate and implement community suggestions for maintaining ROS 2 AsyncAPI specifications.

Special thanks to @Timple and Ramon Wijnands for the interesting call we had! :slightly_smiling_face: :flexed_biceps:

3 Likes
11

Since it seems that there is no more open points to have another discussion, we will proceed with the finalization of the pull request! :slight_smile: :flexed_biceps:

2 Likes
12

Sorry, missed the last meeting!

Have you considered instead of relying on a URL or relative path to the Async API doc, that you could instead use the path relative to the package prefix? ROS messages in a workspace are unique. For example, there is only one geometry_msgs/msg/Point.

This gives you ability to not worry about where your messages come from, and where they are relative to the AsyncAPI spec.

Is it a fair assumption that those writing async API specs:

  1. source their ROS workspace
  2. “ros2 pkg prefix --share geometry_msgs” should work

If both of those are true, then the problem might be a lot easier to solve in a way already used by lots of ROS tooling.

1 Like