Update First-Time Robot Setup Guide for Modern Gazebo #618

Amronos · 2024-12-10T13:37:38Z

Fixes #608.

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

Signed-off-by: Aarav Gupta <[email protected]>

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.

setup_guides/odom/setup_odom.rst

Amronos · 2024-12-11T11:08:59Z

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 · 2024-12-11T19:06:28Z

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

Signed-off-by: Aarav Gupta <[email protected]>

Amronos · 2025-01-04T07:00:13Z

@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 · 2025-01-07T22:37:01Z

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

setup_guides/index.rst

setup_guides/sdf/setup_sdf.rst

setup_guides/odom/setup_odom_gz_classic.rst

setup_guides/odom/setup_odom_gz.rst

Amronos · 2025-01-08T02:18:15Z

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 · 2025-01-08T02:58:58Z

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.

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Signed-off-by: Aarav Gupta <[email protected]>

setup_guides/sdf/setup_sdf.rst

setup_guides/index.rst

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

setup_guides/urdf/setup_urdf.rst

setup_guides/odom/setup_odom_gz.rst

SteveMacenski · 2025-01-21T23:33:48Z

setup_guides/odom/setup_odom_gz.rst

+
+  bridge_config_path = os.path.join(pkg_share, 'config', 'bridge_config.yaml')
+
+Making a Gazebo world


I might recommend clipping this section and just putting in a setnence in the Build, Run, and Verification section that there's an empty world file in the navigation2_tutorials package that we'll be using (with a link) and copy it over. I don't think we need to put it inline since its a supporting piece

I would like to guide the reader a bit better as we also make a small change in the CMakeLists.txt.

OK - I think this could be a dropdown then so that it can be opened if someone wants to look at it (otherwise point to a link to it). The CMake changes I 100% agree with!

I tried to do this but it didn't work and gave the below error.

ERROR: Unknown directive type "dropdown". .. dropdown:: Making a Gazebo world

@Amronos I think it has to be

.. dropdown:: Making a Gazebo world

If that doesn't work, see: https://github.com/ros-navigation/docs.nav2.org/blob/master/development_guides/build_docs/index.rst

It uses .. rst-class:: content-collapse and sections to create collapsing sections in https://docs.nav2.org/development_guides/build_docs/index.html#install

setup_guides/sensors/setup_sensors_gz.rst

SteveMacenski · 2025-01-21T23:51:01Z

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

Amronos · 2025-01-22T11:13:23Z

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

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

SteveMacenski · 2025-01-22T21:42:29Z

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 · 2025-01-23T01:53:32Z

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

Signed-off-by: Aarav Gupta <[email protected]>

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

setup_guides/sdf/images/base-bot_1.png

setup_guides/sdf/setup_sdf.rst

setup_guides/sensors/setup_sensors_gz.rst

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Signed-off-by: Aarav Gupta <[email protected]>

SteveMacenski

Hopefully the last round!

SteveMacenski · 2025-01-28T20:07:54Z

setup_guides/odom/setup_robot_localization.rst

+
+To add a sensor input to the ``ekf_filter_node``, add the next number in the sequence to its base name (odom, imu, pose, twist). In our case, we have one ``nav_msgs/Odometry`` and one ``sensor_msgs/Imu`` as inputs to the filter, thus we use ``odom0`` and ``imu0``. We set the value of ``odom0`` to ``demo/odom``, which is the topic that publishes the ``nav_msgs/Odometry``. Similarly, we set the value of ``imu0`` to the topic that publishes ``sensor_msgs/Imu``, which is ``demo/imu``.
+
+To understand how ``robot_localization`` is configured and understand the reasoning behind the config have a look at `Configuring robot_localization <http://docs.ros.org/en/melodic/api/robot_localization/html/configuring_robot_localization.html>`_.


Please readd the bit you deleted in a8c25ad, but I agree that we should point to those docs (and we do right below this in the seealso). So I think this can/should be reverted

SteveMacenski · 2025-01-28T20:08:55Z

setup_guides/sdf/setup_sdf.rst

+
+SDF is a file format for simulators, like Gazebo, that describes the simulator environment, models (including its links, connections, and physics simulator metadata), and appropriate plugins. The SDF that we will make is for modern Gazebo, but there are other simulator options such as Open3D Engine or Isaac Sim.
+
+We can also use our SDF with the robot_state_publisher using the following package:


Suggested change

We can also use our SDF with the robot_state_publisher using the following package:

We can also use our SDF with the robot_state_publisher using the following package. You will see how to do this in the tutorial below.

SteveMacenski · 2025-01-28T20:10:15Z

setup_guides/sdf/setup_sdf.rst

+Writing the SDF
+================
+
+For now the SDF will pretty much be a copy of the URDF code converted into SDFormat. Changes between the two descriptions will happen when we start adding various plugins and sensors in the next tutorials.


Suggested change

For now the SDF will pretty much be a copy of the URDF code converted into SDFormat. Changes between the two descriptions will happen when we start adding various plugins and sensors in the next tutorials.

For now the SDF will pretty much be a copy of the URDF code converted into SDFormat. Changes between the two descriptions will happen when we start adding various plugins and sensors in the next tutorials. We also add in physical properties needed by the simulator such as the ineria, mass, and material.

SteveMacenski · 2025-01-28T20:14:57Z

setup_guides/odom/setup_odom_gz.rst

+=====================
+
+Create a ``world`` directory in your package and add the following to a new file named ``my_world.sdf``:
+


Quick change to complete this page:

Have the section as any other section

Leave the "Create a world directory..." like any other

The world file is shown below but can also be found on the tutorial at .

Move the .. rst-class:: content-collapse to just surrent the code block (also that code block might technically need to be listed as a new section for the title of the collapsed block, but that's just a quirk of the RST and not how its read by users)

The stuff below the collapsed code block should not be in the collapsed block ("We also have to add the..." bit)

Update setup_odom.rst for the new Gazebo

ccbf4e3

Signed-off-by: Aarav Gupta <[email protected]>

SteveMacenski reviewed Dec 10, 2024

View reviewed changes

setup_guides/odom/setup_odom.rst Outdated Show resolved Hide resolved

Amronos added 2 commits December 12, 2024 16:23

Merge branch 'master' into update-new-gazebo

4a14db5

Update setup_odom tutorials, and add pages for other tutorials

8118513

Signed-off-by: Aarav Gupta <[email protected]>

Amronos requested a review from SteveMacenski January 4, 2025 08:36

SteveMacenski requested changes Jan 7, 2025

View reviewed changes

Amronos and others added 6 commits January 8, 2025 18:20

Apply suggestions from code review

937c420

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Update Table of Contents - from code review

2f92964

Signed-off-by: Aarav Gupta <[email protected]>

Complete tutorial for setting up SDF

4209601

Signed-off-by: Aarav Gupta <[email protected]>

Codespell fix

8d831d2

Signed-off-by: Aarav Gupta <[email protected]>

Apply suggestions from code review

e60812d

Signed-off-by: Aarav Gupta <[email protected]>

Update setup_sensors docs

de4aa2b

Signed-off-by: Aarav Gupta <[email protected]>

Amronos marked this pull request as ready for review January 19, 2025 07:15

Amronos requested a review from SteveMacenski January 19, 2025 07:16

SteveMacenski reviewed Jan 21, 2025

View reviewed changes

SteveMacenski requested changes Jan 21, 2025

View reviewed changes

Amronos and others added 3 commits January 22, 2025 17:37

Update setup_guides/index.rst

397849b

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Update setup_guides/sdf/setup_sdf.rst

db30bb3

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Update setup_guides/sdf/setup_sdf.rst

2809efe

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Amronos mentioned this pull request Jan 23, 2025

Update sam_bot_description for the new Gazebo ros-navigation/navigation2_tutorials#102

Open

6 tasks

Amronos added 2 commits January 25, 2025 10:28

Apply suggestions from code review

aa61c35

Signed-off-by: Aarav Gupta <[email protected]>

Fix pre-commit

ac0fe27

Signed-off-by: Aarav Gupta <[email protected]>

Amronos requested a review from SteveMacenski January 25, 2025 05:10

SteveMacenski requested changes Jan 28, 2025

View reviewed changes

Amronos and others added 4 commits January 28, 2025 20:48

Apply suggestions from code review

4c2b0d3

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Update setup_guides/sensors/setup_sensors_gz.rst

3c90f8b

Co-authored-by: Steve Macenski <[email protected]> Signed-off-by: Aarav Gupta <[email protected]>

Implement review comments

cebd588

Signed-off-by: Aarav Gupta <[email protected]>

Merge branch 'master' into update-new-gazebo

7aa0c2e

Amronos requested a review from SteveMacenski January 28, 2025 16:56

Update setup_robot_localization.rst

a8c25ad

Signed-off-by: Aarav Gupta <[email protected]>

SteveMacenski requested changes Jan 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update First-Time Robot Setup Guide for Modern Gazebo #618

Update First-Time Robot Setup Guide for Modern Gazebo #618

Amronos commented Dec 10, 2024 •

edited

Loading

SteveMacenski left a comment •

edited

Loading

Amronos commented Dec 11, 2024

SteveMacenski commented Dec 11, 2024

Amronos commented Jan 4, 2025

SteveMacenski commented Jan 7, 2025

SteveMacenski left a comment •

edited

Loading

Amronos commented Jan 8, 2025 •

edited

Loading

SteveMacenski commented Jan 8, 2025

SteveMacenski left a comment •

edited

Loading

SteveMacenski Jan 21, 2025

Amronos Jan 22, 2025

SteveMacenski Jan 22, 2025 •

edited

Loading

Amronos Jan 25, 2025

SteveMacenski Jan 28, 2025

SteveMacenski Jan 28, 2025

SteveMacenski commented Jan 21, 2025

Amronos commented Jan 22, 2025 •

edited

Loading

SteveMacenski commented Jan 22, 2025 •

edited

Loading

Amronos commented Jan 23, 2025

SteveMacenski left a comment •

edited

Loading

SteveMacenski left a comment

SteveMacenski Jan 28, 2025 •

edited

Loading

SteveMacenski Jan 28, 2025

SteveMacenski Jan 28, 2025

SteveMacenski Jan 28, 2025


		bridge_config_path = os.path.join(pkg_share, 'config', 'bridge_config.yaml')

		Making a Gazebo world


		To add a sensor input to the ``ekf_filter_node``, add the next number in the sequence to its base name (odom, imu, pose, twist). In our case, we have one ``nav_msgs/Odometry`` and one ``sensor_msgs/Imu`` as inputs to the filter, thus we use ``odom0`` and ``imu0``. We set the value of ``odom0`` to ``demo/odom``, which is the topic that publishes the ``nav_msgs/Odometry``. Similarly, we set the value of ``imu0`` to the topic that publishes ``sensor_msgs/Imu``, which is ``demo/imu``.

		To understand how ``robot_localization`` is configured and understand the reasoning behind the config have a look at `Configuring robot_localization <http://docs.ros.org/en/melodic/api/robot_localization/html/configuring_robot_localization.html>`_.


		SDF is a file format for simulators, like Gazebo, that describes the simulator environment, models (including its links, connections, and physics simulator metadata), and appropriate plugins. The SDF that we will make is for modern Gazebo, but there are other simulator options such as Open3D Engine or Isaac Sim.

		We can also use our SDF with the robot_state_publisher using the following package:

	For now the SDF will pretty much be a copy of the URDF code converted into SDFormat. Changes between the two descriptions will happen when we start adding various plugins and sensors in the next tutorials.
	For now the SDF will pretty much be a copy of the URDF code converted into SDFormat. Changes between the two descriptions will happen when we start adding various plugins and sensors in the next tutorials. We also add in physical properties needed by the simulator such as the ineria, mass, and material.

		=====================

		Create a ``world`` directory in your package and add the following to a new file named ``my_world.sdf``:

Update First-Time Robot Setup Guide for Modern Gazebo #618

Are you sure you want to change the base?

Update First-Time Robot Setup Guide for Modern Gazebo #618

Conversation

Amronos commented Dec 10, 2024 • edited Loading

SteveMacenski left a comment • edited Loading

Choose a reason for hiding this comment

Amronos commented Dec 11, 2024

SteveMacenski commented Dec 11, 2024

Amronos commented Jan 4, 2025

SteveMacenski commented Jan 7, 2025

SteveMacenski left a comment • edited Loading

Choose a reason for hiding this comment

Amronos commented Jan 8, 2025 • edited Loading

SteveMacenski commented Jan 8, 2025

SteveMacenski left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SteveMacenski Jan 22, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SteveMacenski commented Jan 21, 2025

Amronos commented Jan 22, 2025 • edited Loading

SteveMacenski commented Jan 22, 2025 • edited Loading

Amronos commented Jan 23, 2025

SteveMacenski left a comment • edited Loading

Choose a reason for hiding this comment

SteveMacenski left a comment

Choose a reason for hiding this comment

SteveMacenski Jan 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Amronos commented Dec 10, 2024 •

edited

Loading

SteveMacenski left a comment •

edited

Loading

SteveMacenski left a comment •

edited

Loading

Amronos commented Jan 8, 2025 •

edited

Loading

SteveMacenski left a comment •

edited

Loading

SteveMacenski Jan 22, 2025 •

edited

Loading

Amronos commented Jan 22, 2025 •

edited

Loading

SteveMacenski commented Jan 22, 2025 •

edited

Loading

SteveMacenski left a comment •

edited

Loading

SteveMacenski Jan 28, 2025 •

edited

Loading