Skip to content

Commit b6552cb

Browse files
caguerocaguero
authored
Merge pull request #448 from gazebosim/caguero/ros_gz_overview
Extend ROS integration documentation
2 parents 5bdee85 + d64fc67 commit b6552cb

File tree

5 files changed

+230
-11
lines changed

5 files changed

+230
-11
lines changed

‎harmonic/index.yaml

+10-1
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,18 @@ pages:
8585
- name: spawn_urdf
8686
title: Spawn URDF
8787
file: spawn_urdf.md
88+
- name: ros2_overview
89+
title: ROS 2 integration overview
90+
file: ros2_overview.md
91+
- name: ros2_launch_gazebo
92+
title: Launch Gazebo from ROS 2
93+
file: ros2_launch_gazebo.md
8894
- name: ros2_integration
89-
title: ROS 2 integration via bridge
95+
title: Use ROS 2 to interact with Gazebo
9096
file: ros2_integration.md
97+
- name: ros2_spawn_model
98+
title: Use ROS 2 to spawn a Gazebo model
99+
file: ros2_spawn_model.md
91100
- name: ros2_interop
92101
title: ROS 2 interoperability
93102
file: ros2_interop.md

‎harmonic/ros2_integration.md

+65-10
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# ROS 2 Integration
1+
# Use ROS 2 to interact with Gazebo
22

3-
In this tutorial we will learn how to Integrate ROS 2 with Gazebo. We will establish
4-
communication between them. This can help in many aspects; we can receive data (like joint states, TFs) or commands
3+
In this tutorial we will learn how to use ROS 2 to communicate with Gazebo.
4+
This can help in many aspects; we can receive data (like joint states, TFs) or commands
55
from ROS and apply it to Gazebo and vice versa. This can also help to enable RViz to visualize a robot model
66
simulatenously simulated by a Gazebo world.
77

@@ -11,13 +11,7 @@ simulatenously simulated by a Gazebo world.
1111

1212
Example uses of the bridge can be found in [`ros_gz_sim_demos`](https://github.com/gazebosim/ros_gz/tree/ros2/ros_gz_sim_demos), including demo launch files with bridging of all major actuation and sensor types.
1313

14-
## Requirements
15-
16-
Please follow the [Install Gazebo and ROS document](/docs/latest/ros_installation)
17-
before starting this tutorial. A working installation of ROS 2 and Gazebo is
18-
required to go further.
19-
20-
## Bidirectional communication
14+
## Launching the bridge manually
2115

2216
We can initialize a bidirectional bridge so we can have ROS as the publisher and Gazebo as the subscriber or vice versa. The syntax is `/TOPIC@ROS_MSG@GZ_MSG`, such that `TOPIC` is the Gazebo internal topic, `ROS_MSG` is the ROS message type for this topic, and `GZ_MSG` is the Gazebo message type.
2317

@@ -48,6 +42,67 @@ It is also possible to use ROS Launch with the `ros_gz_bridge` and represent the
4842
direction: GZ_TO_ROS # BIDIRECTIONAL or ROS_TO_GZ
4943
```
5044

45+
The configuration file is a YAML file that contains the mapping between the ROS
46+
and Gazebo topics to be bridged. For each pair of topics to be bridged, the
47+
following parameters are accepted:
48+
49+
* `ros_topic_name`: The topic name on the ROS side.
50+
* `gz_topic_name`: The corresponding topic name on the Gazebo side.
51+
* `ros_type_name`: The type of this ROS topic.
52+
* `gz_type_name`: The type of this Gazebo topic.
53+
* `subscriber_queue`: The size of the ROS subscriber queue.
54+
* `publisher_queue`: The size of the ROS publisher queue.
55+
* `lazy`: Whether there's a lazy subscriber or not. If there's no real
56+
subscribers the bridge won't create the internal subscribers either. This should
57+
speedup performance.
58+
* `direction`: It's possible to specify `GZ_TO_ROS`, `ROS_TO_GZ` and
59+
`BIDIRECTIONAL`.
60+
61+
See [this example](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/test/config/full.yaml)
62+
for a valid configuration file.
63+
64+
## Launching the bridge using the launch files included in `ros_gz_bridge` package.
65+
66+
The package `ros_gz_bridge` contains a launch file named
67+
`ros_gz_bridge.launch.py`. You can use it to start a ROS 2 and Gazebo bridge.
68+
Here's an example:
69+
70+
```bash
71+
ros2 launch ros_gz_bridge ros_gz_bridge.launch.py name:=ros_gz_bridge config_file:=<path_to_your_YAML_file>
72+
```
73+
74+
## Launching the bridge from a custom launch file.
75+
76+
It's also possible to trigger the bridge from your custom launch file. For that
77+
purpose we have created the `<ros_gz_bridge/>` tag that can be used from you
78+
XML or YAML launch file. In this case, the arguments are passed as attributes
79+
within this tag. Here's an example:
80+
81+
```xml
82+
<launch>
83+
<arg name="name" default="ros_gz_bridge" />
84+
<arg name="config_file" default="" />
85+
<arg name="container_name" default="ros_gz_container" />
86+
<arg name="namespace" default="" />
87+
<arg name="use_composition" default="True" />
88+
<arg name="use_respawn" default="False" />
89+
<arg name="log_level" default="info" />
90+
<ros_gz_bridge
91+
name="$(var name)"
92+
config_file="$(var config_file)"
93+
container_name="$(var container_name)"
94+
namespace="$(var namespace)"
95+
use_composition="$(var use_composition)"
96+
use_respawn="$(var use_respawn)"
97+
log_level="$(var log_level)">
98+
</ros_gz_bridge>
99+
</launch>
100+
```
101+
102+
In this case the `<ros_gz_bridge>` parameters are read from the command line.
103+
That's an option but not strictly necessary as you could decide to hardcode some
104+
of the values.
105+
51106
## Publish key strokes to ROS
52107

53108
Let's send messages to ROS using the `Key Publisher` an Gazebo plugin.

‎harmonic/ros2_launch_gazebo.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Launch Gazebo from ROS 2
2+
3+
Gazebo can be launched from a ROS 2 launch system in multiple ways:
4+
5+
## Using the launch files included in
6+
[ros_gz_sim](https://github.com/gazebosim/ros_gz/tree/ros2/ros_gz_sim).
7+
8+
The package `ros_gz_sim` contains two launch files named `gz_server.launch.py`
9+
and `gz_sim.launch.py`. You can use them to start Gazebo server or Gazebo (server and GUI)
10+
respectively.
11+
12+
```bash
13+
ros2 launch ros_gz_sim gz_sim.launch.py gz_args:=empty.sdf
14+
```
15+
16+
Or you can just start the server:
17+
18+
```bash
19+
ros2 launch ros_gz_sim gz_server.launch.py world_sdf_file:=empty.sdf
20+
```
21+
22+
Consult the argument block of each launch file
23+
[here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_sim/launch/gz_sim.launch.py.in#L75-L96)
24+
and [here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_sim/launch/gz_server.launch.py#L27-L38)
25+
to learn about the different parameters that are accepted by each launch file.
26+
27+
## Using a custom launch file.
28+
29+
It's also possible to start Gazebo from your custom launch file. For that
30+
purpose we have created the custom `<gz_server/>` tag that can be used from you
31+
XML or YAML launch file. In this case, the arguments are passed as attributes
32+
within this tag. Here's an example for launching Gazebo server:
33+
34+
```xml
35+
<launch>
36+
<arg name="world_sdf_file" default="empty.sdf" />
37+
<arg name="world_sdf_string" default="" />
38+
<arg name="container_name" default="ros_gz_container" />
39+
<arg name="use_composition" default="True" />
40+
<gz_server
41+
world_sdf_file="$(var world_sdf_file)"
42+
world_sdf_string="$(var world_sdf_string)"
43+
container_name="$(var container_name)"
44+
use_composition="$(var use_composition)">
45+
</gz_server>
46+
</launch>
47+
```
48+
49+
In this case the `<gz_server>` parameters are read from the command line. That's
50+
an option but not strictly necessary as you could decide to hardcode some of the
51+
values.

‎harmonic/ros2_overview.md

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# ROS 2 integration overview
2+
3+
Gazebo can be integrated within a ROS 2 system. Let's start describing the
4+
different types of integrations that you can achieve between Gazebo and ROS.
5+
6+
* Use ROS to launch Gazebo: ROS prescribes a specific way to launch all
7+
the pieces needed in your system. There's a dedicated
8+
[launch mechanism](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Launch/Creating-Launch-Files.html)
9+
to orchestrate the launch of all your components and many tooling around it.
10+
Gazebo can be launched in this way.
11+
12+
* Use ROS to interact with Gazebo topics via the [`ros_gz` bridge](https://github.com/gazebosim/ros_gz):
13+
Once Gazebo is up and running, it's very common to communicate with the
14+
simulation. A common way to perform this communication is via topics. Gazebo has
15+
its own middleware, Gazebo Transport, that exposes a set of topics and services quite similar to ROS. The `ros_gz` bridge allows you to create a bridge between
16+
Gazebo and your ROS system, that translates between Gazebo Transport and ROS 2
17+
as needed.
18+
19+
* Use ROS to spawn a Gazebo model: Gazebo worlds can include models that are
20+
loaded at startup. However, sometimes you need to spawn models at runtime. This
21+
task can be performed using ROS 2.
22+
23+
## Requirements
24+
25+
Please follow the [Install Gazebo and ROS document](/docs/latest/ros_installation)
26+
before starting this tutorial. A working installation of ROS 2 and Gazebo is
27+
required to go further.
28+
29+
## Composition
30+
31+
If you inspect the parameters of the launch files mentioned in the next
32+
tutorials, you'll notice that we have included in most cases a parameter named
33+
`use_composition`. When that parameter is set to `True`, the associated ROS
34+
node will be included within a ROS container. When this happens all the nodes
35+
live within the same process and can leverage intraprocess communication.
36+
37+
Our recommendation is to always set the `use_composition` parameter to `True`.
38+
That way, the communication between Gazebo and the bridge will be intraprocess.
39+
If your ROS nodes are also written as composable nodes, make sure that they are
40+
launched with the `container_node_name` parameter matching the container name
41+
including Gazebo and the bridge.
42+
43+
You can learn more about ROS composition in [this tutorial](https://docs.ros.org/en/galactic/Tutorials/Intermediate/Composition.html).

‎harmonic/ros2_spawn_model.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Spawn a Gazebo model from ROS 2
2+
3+
Gazebo will spawn all the models included in the provided world file at startup.
4+
Additionally, it's possible to spawn new models at any time. To do so using ROS
5+
we have provided the following mechanisms:
6+
7+
## Spawn a model using the launch file included in `ros_gz_sim`.
8+
9+
The package `ros_gz_sim` contains a launch file named
10+
`ros_gz_spawn_model.launch.py`. You can use it to spawn a new model into an
11+
existing simulation. Here's an example:
12+
13+
```bash
14+
ros2 launch ros_gz_sim gz_spawn_model.launch.py world:=empty file:=$(ros2 pkg prefix --share ros_gz_sim_demos)/models/vehicle/model.sdf name:=my_vehicle x:=5.0 y:=5.0 z:=0.5
15+
```
16+
17+
Check [this block](https://github.com/gazebosim/ros_gz/blob/cadae1c8323a74395c09a37e3de4c669c8c09d4f/ros_gz_sim/launch/ros_gz_spawn_model.launch.py#L33-L44)
18+
from the source code to know all the different parameters accepted by this
19+
launch file.
20+
21+
## Spawn a model from a custom launch file.
22+
23+
It's also possible to spawn the model from your custom launch file. For that
24+
purpose we have created the `<gz_spawn_model/>` tag that can be used from you
25+
XML or YAML launch file. In this case, the arguments are passed as attributes
26+
within this tag. Here's an example:
27+
28+
```xml
29+
<launch>
30+
<arg name="world" default="" />
31+
<arg name="file" default="" />
32+
<arg name="xml_string" default="" />
33+
<arg name="topic" default="" />
34+
<arg name="name" default="" />
35+
<arg name="allow_renaming" default="False" />
36+
<arg name="x" default="" />
37+
<arg name="y" default="" />
38+
<arg name="z" default="" />
39+
<arg name="roll" default="" />
40+
<arg name="pitch" default="" />
41+
<arg name="yaw" default="" />
42+
<gz_spawn_model
43+
world="$(var world)"
44+
file="$(var file)"
45+
xml_string="$(var xml_string)"
46+
topic="$(var topic)"
47+
name="$(var name)"
48+
allow_renaming="$(var allow_renaming)"
49+
x="$(var x)"
50+
y="$(var y)"
51+
z="$(var z)"
52+
roll="$(var roll)"
53+
pitch="$(var pitch)"
54+
yaw="$(var yaw)">
55+
</gz_spawn_model>
56+
</launch>
57+
```
58+
59+
In this case the `<gz_spawn_model>` parameters are read from the command line.
60+
That's an option but not strictly necessary as you could decide to hardcode some
61+
of the values.

0 commit comments

Comments
 (0)