A new tutorial for package creation with Turtle Nest?

[Jannkar]

Hi!

I recently developed a Turtle Nest package for ROS 2, which is a GUI tool to make package creation super simple. I'm hoping that it will help new developers to get easily started with ROS, while also being a useful tool for professional developers.

I would like new developers to find out about this tool, and in my opinion ros2 documentation would be a perfect place for that. So the question is, would you accept a pull request for a page that shows how to setup a package using Turtle Nest?

I've often heard and seen people struggling with the package creation, when they are getting started with ROS 2. There is a huge amount of things they need to know and understand before creating a package, for example:

• How to create a workspace
• How to create a package from CLI
• What are the available build types (ament_cmake and ament_python) and when to use which
• What are the available licenses
• What is the information needed to be modified in package.xml
• How to create a new Node
• How to create a launch file and launch the newly created Nodes
• How to create parameter files, pass it to Nodes in launch file and how to read the parameters in the Nodes
• How to add the nodes, launch file and parameter file to CMakeLists and setup.py
• How to add the basic dependencies (rclpy or rclcpp)
• etc. etc.

I see this being a huge barrier for the newcomers when getting started, and it is also a place for very easy mistakes and vague error messages. I believe that Turtle Nest can help in this, by flipping this learning process the otherway around. Instead of user having to know all of this information first, they could easily create a package with Turtle Nest that works and is ready for immediate development. And from there, they could continue advancing to any of the existing tutorials in case they need to broaden their understanding or add for example more nodes and new launch/parameter files.

This being my motivation, I would like to create some type of "Quick Start" guide for package creation with Turtle Nest, which would assist the user in creating a package that has Python and CPP nodes, launch file and a parameter file. It would also show a simple talker-listener example with the created Python and CPP nodes. The guide overlap with a bunch of existing tutorials:

• Creating a workspace
• Creating a package
• Writing a simple publisher and subscriber (C++)
• Writing a simple publisher and subscriber (Python)
• Using parameters in a class (C++)
• Using parameters in a class (Python)
• Creating a launch file
• Integrating launch files into ROS 2 packages
• Developing a ROS 2 package
• ament_cmake_python user documentation

What are your thoughts on this?

[clalancette]

Turtle Nest is a great project, so thanks for doing that.

However, it is not part of the core of ROS, so I don't think putting it into ros2_documentation is the appropriate place. Instead, we generate per-package documentation for all released packages that end up in https://docs.ros.org/en/rolling/p/ . In the particular case of Turtle Nest, that would be https://docs.ros.org/en/rolling/p/turtle_nest/.

I'll suggest that you start by documenting how you want people to use Turtle Nest there.

[Jannkar]

Thanks!

It's unfortunate that only core packages are accepted in the main documentation. I appreciate you pointing out the existence of the package-specific documentation; I wasn’t aware of that and will certainly add documentation there. However, this doesn’t quite address the reason I was hoping to include Turtle Nest in the main docs.

I want new ROS users to be aware of Turtle Nest, and I believe the tutorials on the main page are where most of them begin their journey. At that point, they wouldn’t know to specifically look for the Turtle Nest package or its documentation, even though it could be especially useful to them at that point. Having it in the main documentation would ensure they can find and benefit from it earlier.

I think I understand some of the reasons behind accepting only core packages. But could you clarify them? What packages are considered as core packages, and what is required for one to become one?

[clalancette]

I think I understand some of the reasons behind accepting only core packages. But could you clarify them? What packages are considered as core packages, and what is required for one to become one?

We have to draw the line somewhere. There are literally thousands of packages in the ROS ecosystem, and there are quite a few that make life "easier" for users to get started. Rather than trying to put them all in the core documentation, the packages can document themselves using the per-package documentation.

What is in the core is defined by https://github.com/ros2/ros2/blob/rolling/ros2.repos . To become a core package, the ROS PMC has to vote to take on the repository, and fully support it on all platforms (right now this includes Ubuntu, RHEL, and Windows).

[fujitatomoya]

@Jannkar

1st of all, thank you very much for developing great tool, https://github.com/Jannkar/turtle_nest 🐢

i have a few comments here.

I've often heard and seen people struggling with the package creation, when they are getting started with ROS 2. it is also a place for very easy mistakes and vague error messages.

i would like to know more specific here, which error messages and which part they are having the problems and difficulties? we can create issues anytime for these, so that we can address them.

they wouldn’t know to specifically look for the Turtle Nest package or its documentation, even though it could be especially useful to them at that point.

IMO, either core package or not, people do use if they find it useful for that. besides, we can release the package in the same way. I myself have a few ROS 2 projects that are not in the core packages either (i guess everybody else does), but that is fine for me.

Probably you have different perspective here, but i wanted to share my opinion 😃

thanks

[Jannkar]

@clalancette thanks for the clarification, I got it now. It wouldn't be feasible to add all the user-made packages and tools to the documentation, even if they helped with the installation, setup, etc.

@fujitatomoya Thank you, I appreciate it. And it is good to hear your view on this as well.

i would like to know more specific here, which error messages and which part they are having the problems and difficulties?

I don't really have a proper list of the errors that I'm referring to. In general, I mean configuration errors, that are easily doable by for example accidentally skipping a step in a tutorial, typoing something while configuring CMakelists, or not changing something from a tutorial according to your needs (custom Node name, etc.). From the top of my head, here are couple of such issues (which I've also encountered myself a couple of times):

• Not adding __init__.py file for python (ament_cmake_python package)
• Forgetting to add Python Shebang line #!/usr/bin/env python3 (ament_cmake_python package). Error message:

  Error message: OSError: [Errno 8] Exec format error: '/home/user/ros2_ws/src/install/test_cpp_python/lib/test_cpp_python/py_node.py'

• Defining your Node name or the location incorrectly in the CMakeLists. For example this seems to be one such case: https://robotics.stackexchange.com/questions/105834/modulenotfounderror-no-module-named-aruco-marker-aruco-subscriber

IMO, either core package or not, people do use if they find it useful for that. besides, we can release the package in the same way. I myself have a few ROS 2 projects that are not in the core packages either (i guess everybody else does), but that is fine for me.

Good to hear this. Given the requirements for a package to be considered a core package, I currently don't have any plans to push Turtle Nest to become one. Hopefully people find it, if they find it truly useful :grin:

Thanks to both of you! From my side this issue can be closed.

[clalancette]

• Forgetting to add Python Shebang line #!/usr/bin/env python3 (ament_cmake_python package). Error message:

For what it is worth, this is an anti-pattern. That is, you should never do this, because this doesn't work on Windows. Instead, you should use the entry_points functionality of setup.py, as pointed out in the tutorials: https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Writing-A-Simple-Py-Publisher-And-Subscriber.html (among others)

[Jannkar]

For what it is worth, this is an anti-pattern. That is, you should never do this, because this doesn't work on Windows. Instead, you should use the entry_points functionality of setup.py, as pointed out in the tutorials: https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Writing-A-Simple-Py-Publisher-And-Subscriber.html (among others)

Yes, for the regular Python package that uses ament_python, the shebang isn't needed. But for the packages that use ament_cmake_python (ament_cmake_python user documentation) in a way that it combines Cpp and Python, it is still needed, right? As far as I know, there is no way around it.

[clalancette]

Yes, for the regular Python package that uses ament_python, the shebang isn't needed. But for the packages that use ament_cmake_python (ament_cmake_python user documentation) in a way that it combines Cpp and Python, it is still needed, right?

It will have the same problem, since shebang can't possibly work on Windows (by builtin policy). I don't actually know how to make it work on Windows via an ament_cmake_python package, but those are rare enough these days that I haven't looked into it in depth.