ROS 2 tutorials upgrade & entrance level complexity

ROS ROS General
41

First of all, this is really great conversation. For many of us on the PMC, it has been quite a while since we began our robotics journey. On one hand, with time comes experience, but it also dulls the memory of a lot of the pain and sharp edges that come with starting out in a new field or with a new framework. Hearing first hand from users who are either new to ROS, new to robotics, or new to software development as a whole is really valuable for the project, and I personally appreciate reading the thoughts and insights.

I want to capture some of the energy and enthusiasm here in a more structured and productive way. Do you think this topic would also make a good candidate for a community working group? The general idea would be to have a group of people focused on the “new user” journey for ROS and making recommendations to the PMC and the community at large for best practices going forward.

I think now would be a great time to get something like this started. We are about to have the testing and tutorial party for Kilted, which would be an opportunity to get feedback, then roll into planning for L-turtle. Getting any improvements in before the L-turtle LTS would be the most impactful time.

I appreciate everyone’s time is limited and most folks are quite busy actually building things, but this could have a great outcome for the next generation of people coming to ROS and robotics.

5 Likes
42

Thanks a lot for the support!

I want to capture some of the energy and enthusiasm here in a more structured and productive way. Do you think this topic would also make a good candidate for a community working group? The general idea would be to have a group of people focused on the “new user” journey for ROS and making recommendations to the PMC and the community at large for best practices going forward.

This is actually one of the goals of this discussion. Quoting my initial post under the How? point:

I think that some organization such as a work group could also be interesting.

I just lack the experience on how to organize this :slight_smile: But I think it could help connect the viewpoint of more experienced developers that don’t need a lot of Docs support with new users.

I think now would be a great time to get something like this started.

I’m glad! For the short-term, I will focus on turning the feedback from this discussion into issues as everyone is suggesting. I will wait at your feedback on how to organize a potential work group.

2 Likes
43

We have tried experiments like this in the past and and the results have been lackluster at best. We already have a monthly Gazebo Community Meeting and the turnout isn’t great. In the past we did a couple of open office hours for the ROS 1 to ROS 2 migration and no one showed up to that. I am also going to go out on a limb here and guess that people who would be really interested in something like this are in a time zone that is completely out of phase with our core contributors.

We can try it again, but I tend to think there is a big difference between what people think they need and what they actually need. A lot of learning how to be a software developer is learning how to learn. In my entire career I can only think of one or two instances where a video helped me solve a problem I was working on, and most of those instances had to do with a poorly designed GUI.

1 Like
44

From a researcher’s perspective, I completely understand why this mindset has become the norm. But as an engineer, I wouldn’t recommend approaching robot development this way - especially if you’re serious about building robust systems.

Take CMake, for instance. There are some fantastic resources out there on “Modern CMake” (like cliutils/modern-cmake and Professional CMake by Craig Scott). If you’re doing serious robotics software development, it’s well worth spending a few hours to understand the components behind a typical ROS2 package’s CMake setup. That upfront investment will save you much more time later when you’re troubleshooting build issues.

ROS1 largely relied on older C++ standards and legacy CMake practices. ROS2, on the other hand, embraces modern C++ (C++11 and beyond) and target-based CMake. The introduction of DDS also brings in new concepts related to networking and communication. If you didn’t take the time to get familiar with these technical details during ROS1, they can definitely become stumbling blocks when transitioning to ROS2.

At the end of the day, everyone has limited time and will prioritize what they think matters most. Some folks may choose to focus only on getting their robot up and running and consider low-level technical details a distraction. And honestly, it’s rare that writing good tutorials or documentation is anyone’s top priority. It’s a tough reality - but it’s the one we’re working in.

5 Likes
45

That’s absolutely true if you are developing a robot. What about if you want to use a commercially available robot?

To me, ROS would be an exceptional platform to develop at least basic solutions in production for existing commercial robots, given that the safety part is handled by the robot’s proprietary controller. It could gain a huge popularity given the variety of new brands that came out in the last few years, most of which already provide the ROS drivers and moveit config packages.

Robotics is indeed hard and, in the industrial field, the steepness of the learning curve includes many different proprietary languages that are mostly used to deploy the same few functionalities over and over again. There haven’t been any substantial differences or updates in how a 6 axis robot works in the last 30 years. After learning 2 different proprietary industrial robot languages (KRL and RAPID), I was in need to use another brand of robots. The thought to start yet again with new syntax and nuances, just to do all the same stuff, was making me feel unwell…
I then started with ROS, and after a few months I’m still feeling unwell, but for different reasons :rofl:

Jokes aside, ROS has almost all necessary functionalities to cover most real applications, but there’s a lack of functioning, documented examples on real application scenarios.
Take for example Moveit Task Constructor: seems wonderful! But how does it handles some of the basic needs, for example the stop function? How do I handle stopping the robot mid-path? How do I resume it afterwards? Does it handle a controlled stop, since the FollowJointTrajectory doesn’t?

Sure, you can modify it, it’s open-source. But if I just need to use a robot in an application, and not to develop the robot itself, it is a bit too much to ask a ROS novice to deeply understand how an advanced feature as Moveit Task Constructor works when he barely understands how ROS works.

I’m not a researcher, so I’m probably missing something, but I wonder: do all researcher implement those basic functionalities themselves?

A colleague of mine here in Italy founded a startup with ROS-ready robots last year. He tried to use ROS but “it’s too complex, it would take too long”, so he went with their C++ SDK instead. Which is good, and it took him just a couple of months to have a solution ready. But if he ever needs to use another robot brand he’ll have to start from scratch. And then again with the next brand, with an increasing number of different deployed solutions to maintain.

I see a huge potential for ROS diffusion, and I think that making it a bit more “production-ready” would reel in a wave of new developers, and some of them could consequently become new contributors. Right now to get involved in ROS you need to learn all the various languages involved, and not in a superficial way. It would be nice if a roboticist could come in, see it work for some simple scenarios that would make its job way easier, and think: “well, that’s worth digging into!”.

1 Like
46

Thank you for your perspective! I completely agree that the best for engineers is to understand all their tools. As I advocate in this discussion, the sources you mentioned would be great additions to be linked in the tutorials.

However, I think there are two main questions any Tutorial and educational content should answer Why? And When?.

Why do users need to know CMake? As you mentioned “to solve build problems”. Users being introduced to ROS will hardly modify a lot the build system. They will first try to build some node, create some interface… Not only from research, but from the educator perspective I think that there should be a clear separation of concerns here. Build systems and communications should be part of some other CS course. Ideally, students should have learned these concepts by the time they reach ROS. In reality, robotics (and ROS) is approached by users from many different backgrounds and their CS knowledge is usually lacking. Our students come from electronics, mechanical, mathematics, or physics background. They come because they want to learn robotics. And I agree that all these concepts are part of robotics, but the next question is when?

When learning ROS, I think the best approach in the beginning is to first implement basic versions of the concepts such as publishers, subscribers, services, custom msgs… If a user has to learn deeply CMake, DDS and other concepts before being able to implement these, we are artificially raising the entry bar and ultimately scaring people off from joining the community.

My takes here are:

  1. As you said, ROS experts should have a knowledge about all those concepts.
  2. However, the tutorials could avoid getting deep into these details too soon or assume that users will bring that knowledge.
  3. Also, tutorials could include useful pointers to sources for learning them.

How does that sound?

4 Likes
47

If it is a “gnarly” problem then yes, videos probably do not help that much, unless it’s coincidentally a very similar problem or bug. However, for guidance, learning by example and quick immersion into frameworks, I think videos are good. As said above, some people do respond better to visual media.

48

As the primary maintainer of the tutorials for many years, I’m all for improving the tutorials. Thus I think it is worthwhile to collect issues and try to solve them.

However, one non-obvious thing I want to point out is that keeping the Beginner tutorials “simple” is far more difficult than you may think. The problem is that when beginners have problems, each one tends to have a different kind of problem. This can be from lack of understanding of their OS, their editor, their environment, their package manager, ROS installation, ROS concepts, etc. etc.

Some of those beginners solve their problems, and then very kindly want to submit a PR to the documentation to help with their exact problem. But if you have a hundred of these come in, then all of sudden your “Beginner” tutorial has lots and lots of extra things that aren’t really core to what the tutorial is about.

From the other side, you have the people working on the core making improvements, and wanting to let the world know about their improvements. This is again a great thing, but it can be challenging to figure out what is really helpful for beginners, and thus should be in the beginner tutorials, or what should be put elsewhere.

I frequently have said “no” to changes to the beginner tutorials, because they lead down these paths. But that is also somewhat beginner user-unfriendly, because now you’ve pushed back on someone who just thought they were doing a good deed. And it is not that their deed wasn’t good, but it was instead that they were optimizing for a local maxima rather than a global one.

I don’t have a solution for these issues; they are thorny and depend on both who the maintainer is, and who the contributor is. But some of the unwanted complexity you see in the tutorials is exactly because of these problems. Thus, while finding and fixing the issues that we have in the tutorials today is a worthy goal, really this needs to be an ongoing thing that someone needs to continually do.

5 Likes
49

Would it be possible to have foldable sections on the beginner tutorials with hints on what to do if a step of the tutorial failed? This could keep a clean path for those who don’t have problems, while providing a few debug pointers right at the place where it might be needed.

1 Like
50

Thanks for the feedback and advice. All of this makes a lot of sense and I will consider it when creating the issues. I’m aware that the tutorials didn’t come at once and from nowhere and are rather the result of an iterative process. Comments as yours help me understand the process to join it. From your experience, is there anything that bugged you from the tutorials but that you didn’t do because you are lacking the time?

51

I’m adding this to the GDocs. Thanks for the suggestion.

52

re: when would learners need to learn about X, Y or Z?

My experience over the years (academia, industrial training, ad-hoc conversations/troubleshooting sessions) has been there isn’t really an ideal linear path through all these topics. As already mentioned, robotics is hard (especially when we include the sw and hw infrastructural parts), sometimes very difficult and adding (a) complex software framework(s) can’t be expected to make it any simpler – unfortunately we’re just not there yet.

“beginners only need to know how to use things” can be true, but it reduces their zelfredzaamheid to use a very appropriate Dutch word, meaning something like “the ability to deal with things oneself” or being independent or self-reliant.

Additionally, ROS is not a product. It’s a collection of tools and building blocks. I’ve always wondered whether pure users actually exist, as anyone I’ve ever interacted with was trying to make something with it. Perhaps only things like RViz and some RQT plugins can be just used in this sense.

Coming back to the zelfredzaamheid: if learners don’t have at least a basic grasp of the underlying technologies in ROS what I’ve seen happen is that all problems are treated as equally important and as obstacles of equal size. While in reality there could be a “simple” typo in a package manifest or CMakeLists.txt which should be relatively straightforward to spot – if you know what to look for.

On top of that: if everything/large parts are kept a black box, everything happening and/or needed is part of ROS, and conversely, everything that isn’t working is also “blamed” on ROS.

I’m sure ROS doesn’t really care (it doesn’t have feelings .. yet), but pragmatically, this can also lead learners to limit their searches to solutions “in / with / for ROS”. In the example of the typo in your CMakeLists.txt for instance, that’s unnecessary and can potentially make things much more complex than they need to be for whoever is trying to solve something.

4 Likes
53

I agree in general. And I also think that defining a clear and single path for learning is hard. However, we are talking about “entry” level tutorials / understanding the basics. Would you say that learning paths for the basic concepts will vary a lot?

That’s something I am also noticing in general in this discussion. Experienced people argue that ROS is difficult with complex concepts, that people should learn to learn, etc. I think that message is 100% true for learning to be a full ROS engineer. However, I would like to remind that we are talking about “entrance level” to ROS, hence my when.

Of course, as each individual’s learning path advances, the ideal path becomes diffuse and dependent to their needs. But maybe we can improve the first steps + adding clear pointers on how to advance for different needs. Distilling what is essential or not is difficult and I think it can only be done through iteration.

54

the fact that deprecated / non-working 3rd party tutorials and videos live forever in search engine results.

I understand the frustration about this problem but I do think it’s important to reflect on why so many people are making third party tutorial pages and videos instead of official documentation pull requests.

Should software maintainers really respond to the proliferation of third-party tutorials by slowing software improvements?

I’ve got my own little third-party minimal example for ros2_control that’s currently obsolete and broken with a helpful open issue about how I did it wrong in the first place. If I’d submitted it as a PR the maintainers would have told me that during the review process.

I wrote it for Humble. When I sat down to try to fix it on Jazzy, which I’m currently running, I met some other API issue in the tests related to resource manager. Super busy at work designing robots so it’s still sitting.

If it was an official resource and got obsoleted by an API or ABI change, or because it used some internal API that was bound to change, it would have broken CI and someone else probably would have fixed it already.

There’s a lot to be said for people contributing to the official resources here.

2 Likes
55

The original discussion conflates two distinct issues.

But first, a reminder that at its heart, ROS is an SDK that enables distributed computing, providing APIs in various languages and leveraging an underlying middleware for communication.
The core ROS packages (~360) primarily provide these APIs, along with tools for visualization and testing, enabling users to build distributed robotics applications. Building on this foundation, community members have developed and open-sourced many powerful out-of-the-box capabilities for tasks such as SLAM, navigation, motion planning, and control. These capabilities are not part of the ROS “core” and are therefore not typically included in the official core ROS documentation.

Issue 1: Picking up ROS for Beginners.

As many have pointed out, defining the “Beginner” persona is non-trivial, which complicates the creation and maintenance of targeted learning guides. For instance, is a ‘beginner’ someone new to programming entirely, or someone experienced with distributed applications but new specifically to ROS?

The former group needs to learn foundational concepts, including compilers, linkers, build tools, build systems, dependency management, binaries, networking fundamentals, inter-process communication, version control, code editors, software design patterns, operating system basics, terminal commands, debugging techniques etc. I started my ROS journey as a mechanical engineering student with limited experience writing Arduino code. There was a lot I had to learn (and am continuing to learn) and jumping into a Turtlebot tutorial was extremely overwhelming. Learning basic concepts and getting familiar with introspection tools can enable one to learn most ROS-based systems.

The issue may be reduced to defining a concrete set of “Prerequisites” before one can embark on their ROS journey and agreeing on which of these prerequisites come from our documentation vs leaving it as “an exercise for the reader”. → Is this something we can collective define as a community?

Even the Unity tutorials which are the best I’ve seen for any project, can be frustrating for someone new to programming.

Once prerequisites are met, I argue that beginners should start with the Concepts page before moving to the Beginner Tutorials. There is significant room for improvement on the Concepts page, potentially aided by LLM tools suggested by others.

Regarding guidance on building complex applications, rather than extensive core tutorials, it might be more effective to direct users to established projects like Navigation2, MoveIt 2, Open-RMF, and ros2_control. These serve as excellent examples of how to develop performant applications and libraries using ROS.

As for tutorials on best practices, production deployment, and scaling, much valuable information already exists within various ROSCon talks presented over the years. Most of these talks are recorded and available on Vimeo. Automagically (with “AI”) generating blog-style content or summaries for the documentation pages from these videos and slides could be highly beneficial.

We could certainly to do a better job of consolidating & organizing information for different user personas and help from the community is much needed. It’s got to be a continuous effort.

Issue 2: Helping ROS 1 users migrate to ROS 2

I argue that most ROS 1 users are already familiar with core ROS concepts. For them, migration primarily involves understanding the API changes required to adapt their code for ROS 2 interfaces, nodes, topics, services, actions, parameters, and launch files.

Are there specific gaps in our current migration guide or client library tutorials that hinder maintainers during API migration? I don’t see any callouts to these resources in the Google document linked above.

If the challenges involve migrating large, complex systems (e.g., migrating your entire ROS 1 navigation stack to nav2), I believe this falls outside the scope of core ROS documentation and relates more to specific application-level packages and their respective communities.

9 Likes
56

Thanks for the in-depth analysis. I didn’t have time these days to answer.

For instance, is a ‘beginner’ someone new to programming entirely, or someone experienced with distributed applications but new specifically to ROS?

Is this something we can collective define as a community?

From my experience, I would say that the prerequisites to being able to grasp ROS concepts and write basic ROS applications are very minimal. They were in ROS (1) since, as I mentioned, I didn’t have to know barely anything about CMake, distributed applications, or even a lot of programming. I would say basic Python or C++ code programming (not even build systems) is enough to get started.

As the user advances, it’s clear that they will need many more concepts, and then is when experienced programmers will just advance way faster, and when people will have to learn more about CMake etc. But they will do it with a purpose and at the right time. The only thing needed here are crystal clear pointers to where they can learn about those instead of assuming prior knowledge (this might be really difficult or even impossible but worth giving it a try). The concept of pre-requisites already exist in the tutorials, but I would say they could be improved with the pointers I mentioned before.

We could certainly to do a better job of consolidating & organizing information for different user personas and help from the community is much needed. It’s got to be a continuous effort.

I agree and, as long as information is distilled and not redundant, I don’t see why more is a problem since people could just skip sections. But an unanswered question will always cause frustration.

Regarding guidance on building complex applications, rather than extensive core tutorials, it might be more effective to direct users to established projects like Navigation2, MoveIt 2, Open-RMF, and ros2_control. These serve as excellent examples of how to develop performant applications and libraries using ROS.

I see a problem with recommending large projects as example, which is actually a common practice. Since they are giant systems that also have to appeal to a large variety of users, scenarios, and cases in a rather stable manner, they add many layers of complexity just to make it work. Also, they are difficult to adapt to the latest changes or new best practices without breaking the system for their current users. Then, when people take them as examples, they might face excessive complexity to keep generality, and outdated practices to keep the system stable. I would say that a complete but more manageable project could work better for establishing good practices and showing examples or templates.

I argue that most ROS 1 users are already familiar with core ROS concepts.

I think (also from discussing with other people) that the ROS (1) to ROS 2 transition is more complex than just being familiar with core ROS concepts, which is precisely the problem. The ament system, switching to Python launch files, a different parameter system, having to declare and read params, etc. There are some non-trivial changes where the main difficulties lay and that some tutorials or even some migrations I read just assume as known. It’s true that I didn’t include anything from the migration guides in the GDoc and now that you said it I will take a look. Last time I checked, the migration guide was still on foxy, so there were some gaps there. Now they seem much more solid. You are free to add anything to the GDocs if you find it troublesome.

2 Likes