Update First-Time Robot Setup Guide for Modern Gazebo

[Amronos]

Fixes #608.

• Update setup_odom.rst
• Update setup_sensors.rst
• Add tutorial for SDF.

[SteveMacenski]

First of all, a huge, huge thank you for taking this on, it really helps alot to get some support in updating documentation :-)

I'm wondering if we should possibly create new pages for the odometry, sensors (in addition to the SDF we've already discussed) and leave the current pages alone. That would let you start fresh (which would probably make this easier honestly than trying to shoe horn the changes in) and also let us on the Index page https://docs.nav2.org/setup_guides/index.html allow people to choose their adventure for GZ Classic or Modern GZ if they're still on Humble. Unfortunately Humble is supported until mid-2025, so there will still be alot of GZ Classic users around for awhile.

Basically what I'm thinking is to have 2 parallel table contents, one for GZ and another for GZ Classic. They'd both share the Transformations and URDF tutorials, but the Odometry, Sensors, and SDF would change by simulator -- and then the Footprint / Plugins would again be the same. That would also give us a recipe to work with for adding support for new simulators in the future

Then once that passes, we can just delete those changes to complete the migration. What do you think? I think that would make your life easier by being able to have more control on the flow of the guide page and code blocks instead of trying to make a 1:1 analog.

[Amronos]

First of all, a huge, huge thank you for taking this on, it really helps alot to get some support in updating documentation :-)

You are welcome! Thanks a lot for appreciating the effort.

I'm wondering if we should possibly create new pages for the odometry, sensors (in addition to the SDF we've already discussed) and leave the current pages alone. That would let you start fresh (which would probably make this easier honestly than trying to shoe horn the changes in) and also let us on the Index page docs.nav2.org/setup_guides/index.html allow people to choose their adventure for GZ Classic or Modern GZ if they're still on Humble. Unfortunately Humble is supported until mid-2025, so there will still be alot of GZ Classic users around for awhile.

Basically what I'm thinking is to have 2 parallel table contents, one for GZ and another for GZ Classic. They'd both share the Transformations and URDF tutorials, but the Odometry, Sensors, and SDF would change by simulator -- and then the Footprint / Plugins would again be the same. That would also give us a recipe to work with for adding support for new simulators in the future

Then once that passes, we can just delete those changes to complete the migration. What do you think? I think that would make your life easier by being able to have more control on the flow of the guide page and code blocks instead of trying to make a 1:1 analog.

Those ideas do sound good to me. I'm not sure what you mean by "2 parallel table contents." Could you go into a bit more detail about that/how to implement it?

[SteveMacenski]

In the index page, we have a section called "Table of Contents" where we list those guide pages. Instead, we could have 2 separate sections, one for GZ Modern and another for GZ Classic where we link the appropriate versions of the pages. For some, they'll be the same page (URDF, Footprint), but for others they'll change (the ones you're working on).

that would give us the tutorials for both up simultaneously and give you more free reign on the Modern GZ pages to break from the existing where things change more easily

[Amronos]

@SteveMacenski, I'm sorry for the delay on this! I will try my best to get this completed in a couple of days.
I tried my best to implement what you suggested for the index page. Do give feedback if it isn't how you expected it to be (I don't think it is).

[SteveMacenski]

Hey no worries at all - the holidays are for relaxing afterall :-)

[SteveMacenski]

Nice thinking in breaking out the robot localization page for both to share :-)

Largely speaking, this looks great! More or less small tweaks and a few things to shuffle around

[Amronos]

About the SDF and URDF things:
What I am trying to do here is to allow the readers to use either the URDF or SDF, whichever they are more comfortable with using / like more as it is possible to not use both the description formats and just use one instead. :-)
Of course if they want they could do what has been done in the nav2_min_tb3_sim package, instead of using a single description format.

[SteveMacenski]

Ah I see, I think we should have the instructions be best practices: URDF for robot description, SDF for simulation, and we help them setup both. I don't think its wise to give folks too many options in first time setup (since they're new to all this and can't make a knowledgeable trade off yet), so I think its best to go with the best practices only.

[SteveMacenski]

Thanks again! I did another run through and it looks like the only remaining thing is getting on the same page about URDF and SDF. Let me explain what I'm thinking

• URDF is the file used by the robot state publisher to setup the static frames and visualize the robot in rviz. This is used regardless of simulator, if we're using a simulator, or a physical robot. This must always be present.
• SDF is a specific file for Gazebo / GZ for describing the simulator environment or model - and wouldn't be used if using something like Isaac Sim or Open3D Engine
• We can setup URDFs that are SDF and Gazebo-free (see Update First-Time Robot Setup Guide for Modern Gazebo #618 (comment)), so we should as best practices from the GZ maintainers. We should also be recommending that to users. If they happen to do something else, that's on them, but this is the habit we should be steering people down -- both so that they can swap simulators later easily and so that if Gazebo stops supporting implicit URDF to SDF conversions, we don't need to update everything
• So with that in mind, the tutorial has a URDF section that sets up the basic static frames. We should build on that in the SDF tutorial, not replace it. We should have the SDF setup for what the SDF needs as the base-file going into the Odom/Sensor/other tutorials (installing SDF, if needed; creating the file next to the URDF; copying over whatever from the URDF is minimally required; adding in physics tags; etc)
• In the later tutorial steps, we should have the frames added to the URDF and the simulator items added into the SDF. But we should be having both, not expressing things as optional or having an option to do it one of two ways

[SteveMacenski]

This is overall really good! Thanks so much for your efforts here so far 😄

[Amronos]

@SteveMacenski thanks a lot for the reviews and sorry for being a bit difficult with the URDF and SDF things. I get your point now. I think this reasoning should also be available to the readers so is it ok if I add the following note in the URDF tutorial?

"Note that you will also be setting up a SDF for simulation in Gazebo in the next tutorials, you don't need to and shouldn't make it if you are not going to use Gazebo.
URDF is the file used to set up the robot frames. SDF is a specific file for Gazebo that describes the simulator environment or model (including its frames and Gazebo-specific information). It wouldn't be used if using something like Isaac Sim or Open3D Engine.
If you are writing a SDF and think you will not be using any other simulator except Gazebo there isn't really a need to write the URDF but you should still write it in case you encounter a ROS package that requires it or you switch simulators."

Also, I think the SDF tutorial should remain as it is (if you agree with the above note) with a message that some parts of it will seem redundant if the URDF tutorial has been followed.

P.S. I would like if you had a look at this.

[SteveMacenski]

I'd rewrite a little to:

"Note that you will also be setting up a SDF for simulation in Gazebo in the next tutorials. URDF is used to set up the robot frames and describe the robot's structure for run-time use on hardware and possibly in simulation. SDF is a specific file for simulators, like Gazebo, that describes the simulator environment, model (including its frames and Gazebo-specific information), and appropriate plugins. The SDF that we will make is for Gazebo, but could be replaced with an appropriate SDF or other format file for Open3D Engine or Isaac Sim."

Its a little more concise - and you actually can use SDF with other simulators, but most of the SDF we're setting up is with Gazebo sensor and odometry plugins, which are obviously going to be different from other simulators since they have their own plugins or capabilities. So I think this is important to reword for that distinction.

Also, I think the SDF tutorial should remain as it is (if you agree with the above note) with a message that some parts of it will seem redundant if the URDF tutorial has been followed.

Isn't this still saying do 'this' or 'that' for SDF vs URDF? I think we want to steer down a single direction still

P.S. I would like if you had a look at this.

I get their point from the GZ project's perspective. Just use SDF, since you'll have the SDF for the simulator. But alot of people are now using other simulators as that technology has been massively improving over the years and there are new ones like MoJoCo, Isaac Sim, Open3D, Unity, etc. So, I think its more important than ever we still have URDF for the robot description that's not dependent on simulator (and used on actual hardware) and the SDF for simulation.

[Amronos]

Ok, thanks! Will make the necessary changes needed then in all the tutorials.

[SteveMacenski]

Very close to being done! Just a few small changes and I think this is good to go!

I think after you make these changes, its worth reading through it from start to end once more just to make sure there's no additional duplication or gap missing :-) Also make sure the files in ros-navigation/navigation2_tutorials#102 keep aligned with the tutorial's contents. I'm going to review that PR next

[SteveMacenski]

Hopefully the last round!

[SteveMacenski]

Great, I crazy appreciate your time and energy here! I know it was a few rounds and I was a bit picky since this is some of the first docs users see -- and it is very acknowledged.

I'm going to post on ROS Discourse and LinkedIn about this update, can you share with me your Discourse handle / linkedin profile so I can make sure I give you credit where credit is due?

This is really fantastic and let me know if you're interested in working on something else in the code or docs! I'm happy to help you find some other contribution :-)

[Amronos]

Great, I crazy appreciate your time and energy here! I know it was a few rounds and I was a bit picky since this is some of the first docs users see -- and it is very acknowledged.

Thanks!

I'm going to post on ROS Discourse and LinkedIn about this update, can you share with me your Discourse handle / linkedin profile so I can make sure I give you credit where credit is due?

My discourse handle would be @amronos, I don't have a LinkedIn account.

This is really fantastic and let me know if you're interested in working on something else in the code or docs! I'm happy to help you find some other contribution :-)

I would love to! One thing you have already told me to do is update nav2_bringup with composition for Gazebo.