Guide to `ros_gz_project_template` for ROS 2 and Gazebo Development#

In this guide, you will learn how to use the ros_gz_project_template to create a (recommended) structured workspace or improve your existing workspace for your ROS 2 and Gazebo projects. This template offers a consistent layout, automated build process, and integration with both ROS 2 and Gazebo, enabling you to focus on developing your robotics applications.

Installation Steps#

If you are starting a project, create a new workspace or go to your existing project’s source directory:
```
mkdir -p ~/project_ws/src
cd ~/project_ws/src
```
Directly use the ros_gz_project_template template and create your project repository on GitHub.

Or start by cloning the template repository:
```
vcs import --input https://raw.githubusercontent.com/gazebosim/ros_gz_project_template/main/template_workspace.yaml
```
Rename the cloned repository folder to your desired project name:
```
mv ros_gz_project_template your_project_name
```

Package structure#

At this point you’ll have the following packages in your project:

ros_gz_example_application - holds ROS 2 specific code and configurations. Namely where control, planning or any high level algoritms reside.
```
 ├── CMakeLists.txt
 ├── package.xml
 ├── src
     └── ...
 
```

ros_gz_example_bringup - holds launch files and high level utilities, communication bridge between ROS and Gazebo. Any robot or hardware specific configurations go here.

 ├── config
 │   ├── ros_gz_example_bridge.yaml
 │   └── diff_drive.rviz
 ├── launch
     └── diff_drive.launch.py

ros_gz_example_description - holds the SDF description of the simulated system and any other simulation assets.

 ├── hooks
 │   └── ros_gz_example_description.dsv.in
 ├── models
     ├── diff_drive
         ├── model.config
         └── model.sdf

ros_gz_example_gazebo - holds Gazebo specific code and configurations. Namely this is where user-defined worlds and custom system plugins end up.

 ├── include
 │   └── ros_gz_example_gazebo
 │       ├── BasicSystem.hh
 │       └── FullSystem.hh
 ├── src
 │   ├── BasicSystem.cc
 │   └── FullSystem.cc
 ├── worlds
         └── diff_drive.sdf

Accessing Simulation Assets#

Simulation assets include your models or robot descriptions in URDF or SDF, meshes and materials files to help visualize different parts of the robot and finally compiling all these elements in a simulated world SDF. Gazebo offers a few different mechanisms for locating those, initializing it’s search on GZ_SIM_RESOURCE_PATH environment variable, see gz-sim API on finding resources for more details.

There is a difference in how ROS and Gazebo resolves URIs, that the ROS side can handle package:// URIs, but by default SDFormat only supports model://. Now libsdformat can convert package:// to model:// URIs. So existing simulation assets can be loaded by “installing” the models directory and exporting the model paths to your environment.

This can be automated using colcon environment hooks (shell scripts provided by a ROS package) in a DSV file. Whenever you source the setup file in a workspace these environment hooks are also being sourced. See an example of prepending the model share path to GZ_SIM_RESOURCE_PATH which enables Gazebo to load models from a ROS package using the model:// URI.

Development#

Choose a ROS and Gazebo combination

Note: If you’re using a specific and unsupported Gazebo version with ROS 2, you might need to set the GZ_VERSION environment variable, for example:
```
export GZ_VERSION=ionic
```

Install dependencies

cd ~/project_ws
source /opt/ros/<ROS_DISTRO>/setup.bash
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -r -i -y --rosdistro <ROS_DISTRO>

Modify

Explore the src/your_project_name directory to add/modify the packages associated with your project. There are two primary mechanisms to integrate ROS 2 and Gazebo depending on your application:
1. Use ros_gz_bridge to dynamically connect topics between ROS 2 and Gazebo (which is demonstrated as an example in this template)
2. Embed ROS 2 directly in a Gazebo system plugin
The main consideration is in choosing the depth of integration is required between ROS and Gazebo. Using the bridge keeps dependencies separate and Gazebo systems don’t have to know about ROS. By embedding ROS 2 nodes directly allows accessing the EntityComponentManager within a Gazebo plugin.

Build

cd ~/project_ws
colcon build --cmake-args -DBUILD_TESTING=ON

Usage#

Source the workspace
```
. ~/project_ws/install/setup.sh
```
Launch the simulation and visualize in RViz:

To visualize your robot model and the data generated by your ROS 2 nodes, open a new terminal and launch:
```
ros2 launch ros_gz_example_bringup diff_drive.launch.py
```

ROSCon 2022#

Check out a ROSCon 2022 talk titled ROS 2 and Gazebo Integration Best Practices, to learn more about best practices of integrating simulation with ROS 2, drawn from accumulated experience and successful deployments. The talk will additionally cover tips and techniques to ease migration to the latest versions.

Guide to ros_gz_project_template for ROS 2 and Gazebo Development#