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.

[SteveMacenski]

I believe we're separating the SDF files now. I think the SDF tutorial should be before this one, so they should have one already (with basic frames?) that we're modifying to setup the odometry / diff drive controller

[Amronos]

This is something defined in line 90 of the old tutorial, which I slightly updated. I think since we have/will be having a URDF and SDF tutorial now, this is something that may cause confusion so I will remove it.

[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

[SteveMacenski]

I think what we should have here is a page split in half with 2 of these toctrees for each the Gazebo Classic and Modern Gazebo. I checked with rst and there isn't a way to split vertically, but we can using HTML. I'm not much a web-dev guy, but this is one case where chatgpt can be helpful. It looks like we can do that via the following, adapted to our case here obviously:

My Split Page
=============

.. raw:: html

    <div style="display: flex; gap: 20px;">

    <div style="flex: 1; padding: 10px; border-right: 1px solid #ccc;">

.. toctree::
   :maxdepth: 2

   section1
   section2
   section3

.. raw:: html

    </div>

    <div style="flex: 1; padding: 10px;">

.. toctree::
   :maxdepth: 2

   section4
   section5
   section6

.. raw:: html

    </div>
    </div>

So each side should have the full setup_transformations -> select_algorithm pipeline, but with the links to the appropriate GZ vs classic pages where required

[Amronos]

Thanks! Did it in 2f92964, had to use a bit of chatgpt too. :-)

[SteveMacenski]

So I see the 2 sections, but none of the actual links on it https://output.circle-artifacts.com/output/job/95f5e86b-5415-4fcd-8b17-ec6cdff44bb5/artifacts/0/html/setup_guides/index.html -- did you test this locally?

[SteveMacenski]

Suggested change

	- Introduce TF2 and setup your robot URDF or SDF
	- Introduce TF2 and setup your robot URDF & SDF

[Amronos]

I still think this should be URDF or SDF, as in most use cases, both are not needed. I will add a note in the tutorials for URDF & SDF, that the other is an option and to use SDF if the reader is going to make a Gazebo simulation.

[Amronos]

I will add a note in the tutorials for URDF & SDF, that the other is an option and to use SDF if the reader is going to make a Gazebo simulation.

Done in 4209601.

[SteveMacenski]

@Amronos I think for new Gazebo, they really are pushing you down the road of using SDFs and separate URDFs. That has been best practices in Gazebo Classic for awhile, but old habits die hard.

I think for the purposes of this tutorial, we should only propose this as URDF and SDF. URDF is the basic robot frames and descriptions. SDF is the gazebo plugins and simulation items

[SteveMacenski]

In this paragraph the following should be removed

Afterwards, we will discuss how various sources of odometry can be fused to provide a smoothed odometry using the robot_localization package. Lastly, we will also show how to publish the odom => base_link transform using robot_localization.

[SteveMacenski]

Shouldn't this be in the URDF section not the odometry section? I believe this is already done in this section

[Amronos]

The part where I set the <mu> tags hasn't been done in that section. Also, the reason I am including this here is that I think something related to this changed from Gazebo Classic to Modern Gazebo as it isn't present in the older tutorials and I think that various SDF related changes have also happened.
Will move it to setup_urdf and setup_sdf if this is not the case.

[SteveMacenski]

I think we should move this after the differential drive plugin is added -- I think that'll be more linear

[SteveMacenski]

Same comment on the SDF vs URDF

[SteveMacenski]

I think we should have a subsection after the Adding Gazebo Plugins to a URDF/SDF section called Creating Gazebo Bridge which does this (and adds a little explanation about the bridge). For example:

• There is a bridge 😆
• It translates GZ topics to ROS topics
• We have to launch the bridge with a configuration about what topics to translate and what their ROS types are

So I think this should be moved before Launch and Build Files so this file is setup and ready by the time they go to actually modifying launch files. I think that's important because having the filepath to this config file is part of the launch modifications

[SteveMacenski]

I don't think this path is defined yet in the instructions

[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.