ROS Resources: Documentation | Support | Discussion Forum | Service Status | Q&A

Guidelines on how to architect ROS-based systems

Many thanks for the launch files paper! Will definitely have a look at it!

External packages: yes, if you use submodules then you need to manually sync them with upstream, especially if there are some interesting developments in there for you.

Bagfiles: I know that chossing “top platforms” in unbiased manner is a challenge but maybe you can select them based on number of stars in the repo? Or you can be biased and say: these platforms do everything correctly in our view, check out examples of their raw data.

I’m now realizing that the bagfile data project I’m proposing might not necessarily be fit for a research project but having something similar to AOSAA book but for Robotics could be very interesting. @Katherine_Scott maybe OpenRobotics could lead such effort? I’d be up for writing a chapter on some platform if this was to become a thing.

Sorry I went even more off topic here :slight_smile:

You are welcome! And thanks for the clarification on the external packages.

In empirical software engineering there are many ways in which this bias may be controlled. For example, here is a paper about the do’s and dont’s related to the treatment of third-party GitHub repositories for scientific purposes.

This is extremely interesting for me (and for my research group) and we are definitely willing to help and put effort in this!

Awesome paper, thanks!

This is probably in the paper and I just missed it, but do you have any recommendations on the best way to document the system architecture? The paper says:

… documented architecture (i.e. the system is described in terms of nodes, services, topics, and their configuration).

Are these best described in a single README file or as ROS node graphs with text descriptions or do you have some other example of great architecture documentation that the rest of us can follow?

Is there one particularly excellent architecture that could be used as a starting point for most other robot architectures? Perhaps something like the Niryo One five layers architecture of external communication, command, motion planning, control, and hardware? Or are most robots unique enough to require independently designed architectures? Thanks!

1 Like

I can’t wait for this to be published for me to be able to cite that zinger.


Thanks Peter, here are my thoughts on your points.

My experience with this study is that people document the architecture of their systems in a very heterogeneous way, ranging from raw node communication graphs, to box-and-line diagrams done in Powerpoint, etc. Actually, in the dataset I collected a direct link to each Architecture documentation, you can refer to the “SA documentation” column here and explore.

About recommendations, I think that the best architectures (in terms of documentation) are the ones combining a graphical representation (of both nodes, topics, and pub/subs) and a textual description of the main responsibilities of each node. Personally, I also like those in which you have a high-level architecture description at the beginning and then details are provided in a top-down fashion, such as in MoveIt.

This is difficult to say. I think it is doable to have some kind of reference architecture for robots belonging to specific domains (e.g., delivery robots, or industrial arms), but it really depends on the requirements and regulations of each domain. If we want to be generic and cover all application domains, maybe the Niryo One layered architecture is a good candidate, but I doubt it will be able to cover all possible needs. Funnily enough, in these weeks I am working with a group of researchers between Italy and Sweden on a generic platform for (1) specifying reference architectures of arbitrary application domains (e.g., delivery robots) and (2) automatically checking the compliance of specific architectures against the reference architecture of their domain. I will keep you posted about it, if you are interested :slight_smile:



1 Like

I would be very interested, thanks!

The MoveIt documentation looks fantastic. I imagine it takes a lot of manual work to make it look that nice. Do you think it is possible to generate system architecture documentation automatically, even if it does not look quite that good, in a standardized way that makes it easy to compare architectures and subsystem compatibility? Maybe something like rqt_graph. I do not know how much could be determined statically and how much would need runtime information. Or does proper documentation require high level information that you cannot get from a set of packages alone? It seems like if you have enough information to check the compliance of an architecture then you would have enough information to automatically create documentation for it.


Maybe something like rqt_graph. I do not know how much could be determined statically and how much would need runtime information.

Here goes another shameless plug.

HAROS is able to extract the computation graph statically - to some extent.

An automatic documentation generator is something I have been meaning to do for a while, but never got the opportunity. I might have some time in a couple of months.

André Santos

1 Like

Hi Peter,
as soon as we will publish the paper I will come back to you with a copy of it. :slight_smile:

About the automatic generation. There are approaches and some of them are pretty cool (see Haros by André in his other message), but the problem is still very hard, specially with ROS where the “architectural connectors” emerge only at run-time, basically when you publish/subscribe to specific topics. Interestingly, in ROS it is “fairly simple” to identify the main components of the architecture, but the connects are difficult to extract.

And yes, it could be fantastic (also for us, researchers) to have a standard notation for representing the architecture of robotics systems and to be able to compare architectures across systems, types of robots, and application domains. This would open up for large-scale studies where we could extract even more details information from the system, even more than architecting guidelines!

HAROS looks really interesting thanks! Do you have plans to extend it to ROS 2? Could it work with just vcstool yaml files or does it need more information in its configuration files?

Would the Node Interface Definition Language help with extracting all of the necessary connections between components?

1 Like

Not right now, although a few community members have contributed in that regard.
In a few months I might get into another project which, likely, will require ROS 2 support at some point.

It does need its own YAML files with a little extra information, unfortunately. That is also something I want to address whenever I have the time to start working on v4.0.

Btw, thanks for sharing that PR with the Node IDL! I had no clue it was a thing, and it might be useful for HAROS, since I already have a similar mini language going on.


Please do review that PR, we’re developing the code behind it now. It sounds like we have similar interests, and I’d love to make sure your use-case is empowered.

1 Like

Are the quality working groups something that anyone can join to listen in? Thanks, Allan

1 Like

Hey @Allan_Scherger, welcome to the comunity!

I’d say yes, for all Working Groups (WG).

It’s up to @Alami and other folks to answer formally but in my past experience with the QA WG, I joined without notice and started participating in the meetings.

All of the working groups are open. Anyone can join at any time.

Yes, the ROS Quality meeting is open for all the ROS Community. Any community member can join listen and participate in the discussion if he/she wishes to.

1 Like

Hi all,
I am bring to life this thread since yesterday we published an extended version of our architecting guidelines, it is available here.

There we discuss in details ALL 47 architecting guidelines and include several examples about how to apply them in concrete projects. I hope that this is useful for you, people!

As usual, the raw dataset is available on GitHub as well:

@wasowski, I see that you last edited the Quality/tutorials page on the ROS wiki, do you think it makes sense to list our guidelines there?



Thnx for those guidelines. Nice to have the things I knew intuitively spelled out clearly.

I did spot one very minor error though:

ED is developed by TU Delft

That should be TU Eindhoven. Both in the Netherlands, we’re a small country, but still :slight_smile:

1 Like

Ooops, thanks @Loy for the correction.

Thanks @Loy for appreciating our work!


1 Like

that surprised me as well, especially because in the sentence following that statement the authors include a link to the repository, which is on the tue-robotics organisation.

More interesting to me though is the fact that N8 recommends to use a single node for environment representation, gives a few examples why that would be advantageous (single source of truth mostly), but seems to ignore the fact all of those (ultimately) rely on TF – which is an asynchronous, distributed graph based approach for keeping track of coordinate frames in 6D space.

It’s very much possible for TF consumers to have a partial view of the transform tree, and thus by extension of “the world” I believe.

Wouldn’t it be more prudent to assume all world representations are always partial, and not consider any of them as an absolute source of truth?

1 Like

I wouldn’t say that this applies for all projects, it really depends on the system being developed and the used packages.