Workshopping a ROS / Gazebo Tutorial Page to Land Under "Related Projects"

[kscottz]

Quite a few users having a hard time figuring out how to make ROS 2 work with modern Gazebo. I propose we add a page under "related projects" that summarizes resources related to ROS / Gazebo integration. I intend to the solicit the community for resources they find useful.

Here is an initial "strawman" list.

• Main Gz Docs
• Gazebo Classic Migration
• ROS / Gazebo Installation Guide
• ROS 2 / Gazebo Project Template
• ROS 2 / Gazebo Example Code
• Gazebo Community Forum
• Gazebo Sim Forum
• Gazebo Source Code
• Gazebosim Simulation Assets (aka Fuel)
• Gazebo Plugins

I've attached a list of other potential resources to go through that we think are worth adding. @Ryanf55 says that he would be up for helping us reduce the attached list into a useful guide.

Potential ROS / Gazebo Resources: GazeboList.md

[Ryanf55]

Thanks for this starter!

[kscottz]

@Ryanf55 I think this directory would be a good place for this to land. @clalancette has final say on location, and may have differing opinions.

[Ryanf55]

LGTM for a central landing page. Only tutorials that are maintained should go there.

[clalancette]

We already have a location for Gazebo/ROS integration pages at http://docs.ros.org/en/rolling/Tutorials/Advanced/Simulators/Gazebo/Simulation-Gazebo.html , so I think we should just expand on that.

[Ryanf55]

Good idea. I started by overhauling the Gazebo.rst page to have tabs for Ignition and Garden or Newer because all the instructions were still using ign commands, and fixed some invalid links. The ros_gz_bridge set up is complex enough that I changed to link directly to the official table.

Perhaps the most important thing for me that's missing is the context on why you would use the bridge, and what the alternatives are. It's not the only option to communicate between ROS 2 and Gazebo.

[clalancette]

I started by overhauling the Gazebo.rst page to have tabs for Ignition and Garden or Newer

This shouldn't be necessary. Starting with Rolling/Jazzy, we are going to just be using a particular version of Gazebo with a particular version of ROS 2. So we just need to update everything to use gz. Also, we should also coordinate with https://github.com/ros2/ros2_documentation/pull/4311 and https://github.com/ros2/ros2_documentation/issues/3340 , where similar things are being discussed.

[Ryanf55]

Subbed! I'm interested to ensure the tutorials work with humble/harmonic combination that ROS aerial is actively using. Per the last community group meeting, we're hoping to help improve official documentation on setup.

[knmcguire]

Thanks for the headsup @Ryanf55! I was a bit too quick with creating my draft PR it seems for some improvements but I can close that and coordinate with you all.

At least from the issue I was part of, the issue was that it was unclear what the recommended gazebo is for the distro from the preliminary of the documentation, as one doc says harmonic (gz) and the other says fortress (ign), so at least advising it to install it as dependency from ros-gz would ensure the right version for the ros bridge.

but that being, if all will be updated to gz then maybe we should wait a bit indeed.

[Ryanf55]

And, mine: https://github.com/ros2/ros2_documentation/pull/4312 It doesn't provide a recommendation to users and instead lets them decide based on whether they are using ign or gz.

Given it's just some tabs in rst, I'm interested to support the combinations in this table with the lightning icon: https://gazebosim.org/docs/garden/ros_installation#summary-of-compatible-ros-and-gazebo-combinations

The Ignition/Garden+tabs will only be needed for humble and iron docs because Ignition isn't supported with jazzy.

[azeey]

I plan to bring this up in our Gazebo team meeting today, but my preference would be to have a minimal tutorial here showing how to install ros_gz with the assumption that they would use the officially paired version of Gazebo (e.g Humble/Fortress) and to point users to gazebosim.org for more in depth tutorials that discuss how to use Gazebo itself or how to set it up with different versions of Gazebo. This will, IMO, ensure that there is one source of truth and it would be easier on the Gazebo team to maintain one documentation website than two.

[Ryanf55]

Sounds good! Perhaps this just needs to have a gz -h or ign -h and conclude the tutorial there.

[knmcguire]

Alright just let us know what comes out of the meeting @azeey. From what you are explaining I can perhaps assume that my PR is more closer of what you had in mind, since that is what we discussed in the issue beforehand. It is only missing extra resources on the bottom (like those that @kscottz assembled above). But just let me know what you decide from the gazebo meeting.

[azeey]

There was agreement at the meeting with what I said in https://github.com/ros2/ros2_documentation/issues/4302#issuecomment-2070261541. We can expand the ROS related tutorials in gazebosim.org/docs or create new ones as need be. I feel like there's still a lot of confusion as to which version of Gazebo should be paired with a version of ROS. Any clarifying content that y'all can add is most welcome.

[Ryanf55]

You got it. I'll work with Kim.