Merge pull request #448 from gazebosim/caguero/ros_gz_overview

Extend ROS integration documentation

harmonic/index.yaml

@@ -85,9 +85,18 @@ pages:
       - name: spawn_urdf
         title: Spawn URDF
         file: spawn_urdf.md
+      - name: ros2_overview
+        title: ROS 2 integration overview
+        file: ros2_overview.md
+      - name: ros2_launch_gazebo
+        title: Launch Gazebo from ROS 2
+        file: ros2_launch_gazebo.md
       - name: ros2_integration
-        title: ROS 2 integration via bridge
+        title: Use ROS 2 to interact with Gazebo
         file: ros2_integration.md
+      - name: ros2_spawn_model
+        title: Use ROS 2 to spawn a Gazebo model
+        file: ros2_spawn_model.md  
       - name: ros2_interop
         title: ROS 2 interoperability
         file: ros2_interop.md

harmonic/ros2_integration.md

@@ -1,7 +1,7 @@
-# ROS 2 Integration
+# Use ROS 2 to interact with Gazebo
 
-In this tutorial we will learn how to Integrate ROS 2 with Gazebo. We will establish
-communication between them. This can help in many aspects; we can receive data (like joint states, TFs) or commands
+In this tutorial we will learn how to use ROS 2 to communicate with Gazebo. 
+This can help in many aspects; we can receive data (like joint states, TFs) or commands
 from ROS and apply it to Gazebo and vice versa. This can also help to enable RViz to visualize a robot model
 simulatenously simulated by a Gazebo world.
 
@@ -11,13 +11,7 @@ simulatenously simulated by a Gazebo world.
 
 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.
 
-## Requirements
-
-Please follow the [Install Gazebo and ROS document](/docs/latest/ros_installation)
-before starting this tutorial. A working installation of ROS 2 and Gazebo is
-required to go further.
-
-## Bidirectional communication
+## Launching the bridge manually
 
 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.
 
@@ -48,6 +42,67 @@ It is also possible to use ROS Launch with the `ros_gz_bridge` and represent the
   direction: GZ_TO_ROS  # BIDIRECTIONAL or ROS_TO_GZ
 ```
 
+The configuration file is a YAML file that contains the mapping between the ROS
+and Gazebo topics to be bridged. For each pair of topics to be bridged, the
+following parameters are accepted:
+
+* `ros_topic_name`: The topic name on the ROS side.
+* `gz_topic_name`: The corresponding topic name on the Gazebo side.
+* `ros_type_name`: The type of this ROS topic.
+* `gz_type_name`: The type of this Gazebo topic.
+* `subscriber_queue`: The size of the ROS subscriber queue.
+* `publisher_queue`: The size of the ROS publisher queue.
+* `lazy`: Whether there's a lazy subscriber or not. If there's no real
+subscribers the bridge won't create the internal subscribers either. This should
+speedup performance.
+* `direction`: It's possible to specify `GZ_TO_ROS`, `ROS_TO_GZ` and
+`BIDIRECTIONAL`.
+
+See [this example](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/test/config/full.yaml)
+for a valid configuration file.
+
+## Launching the bridge using the launch files included in `ros_gz_bridge` package.
+
+The package `ros_gz_bridge` contains a launch file named
+`ros_gz_bridge.launch.py`. You can use it to start a ROS 2 and Gazebo bridge.
+Here's an example:
+
+```bash
+ros2 launch ros_gz_bridge ros_gz_bridge.launch.py name:=ros_gz_bridge config_file:=<path_to_your_YAML_file>
+```
+
+## Launching the bridge from a custom launch file.
+
+It's also possible to trigger the bridge from your custom launch file. For that
+purpose we have created the `<ros_gz_bridge/>` tag that can be used from you
+XML or YAML launch file. In this case, the arguments are passed as attributes
+within this tag. Here's an example:
+
+```xml
+<launch>
+  <arg name="name" default="ros_gz_bridge" />
+  <arg name="config_file" default="" />
+  <arg name="container_name" default="ros_gz_container" />
+  <arg name="namespace" default="" />
+  <arg name="use_composition" default="True" />
+  <arg name="use_respawn" default="False" />
+  <arg name="log_level" default="info" />
+  <ros_gz_bridge 
+    name="$(var name)"
+    config_file="$(var config_file)"
+    container_name="$(var container_name)"
+    namespace="$(var namespace)"
+    use_composition="$(var use_composition)"
+    use_respawn="$(var use_respawn)"
+    log_level="$(var log_level)">
+  </ros_gz_bridge>
+</launch>
+```
+
+In this case the `<ros_gz_bridge>` parameters are read from the command line.
+That's an option but not strictly necessary as you could decide to hardcode some
+of the values.
+
 ## Publish key strokes to ROS
 
 Let's send messages to ROS using the `Key Publisher` an Gazebo plugin.

harmonic/ros2_launch_gazebo.md

@@ -0,0 +1,51 @@
+# Launch Gazebo from ROS 2
+
+Gazebo can be launched from a ROS 2 launch system in multiple ways:
+
+## Using the launch files included in
+[ros_gz_sim](https://github.com/gazebosim/ros_gz/tree/ros2/ros_gz_sim).
+
+The package `ros_gz_sim` contains two launch files named `gz_server.launch.py`
+and `gz_sim.launch.py`. You can use them to start Gazebo server or Gazebo (server and GUI)
+respectively.
+
+```bash
+ros2 launch ros_gz_sim gz_sim.launch.py gz_args:=empty.sdf
+```
+
+Or you can just start the server:
+
+```bash
+ros2 launch ros_gz_sim gz_server.launch.py world_sdf_file:=empty.sdf
+```
+
+Consult the argument block of each launch file
+[here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_sim/launch/gz_sim.launch.py.in#L75-L96)
+and [here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_sim/launch/gz_server.launch.py#L27-L38)
+to learn about the different parameters that are accepted by each launch file.
+
+## Using a custom launch file.
+
+It's also possible to start Gazebo from your custom launch file. For that
+purpose we have created the custom `<gz_server/>` tag that can be used from you
+XML or YAML launch file. In this case, the arguments are passed as attributes
+within this tag. Here's an example for launching Gazebo server:
+
+```xml
+<launch>
+  <arg name="world_sdf_file" default="empty.sdf" />
+  <arg name="world_sdf_string" default="" />
+  <arg name="container_name" default="ros_gz_container" />
+  <arg name="use_composition" default="True" />
+  <gz_server 
+    world_sdf_file="$(var world_sdf_file)"
+    world_sdf_string="$(var world_sdf_string)"
+    container_name="$(var container_name)"
+    use_composition="$(var use_composition)">
+  </gz_server>
+</launch>
+```
+
+In this case the `<gz_server>` parameters are read from the command line. That's
+an option but not strictly necessary as you could decide to hardcode some of the
+values.

harmonic/ros2_overview.md

@@ -0,0 +1,43 @@
+# ROS 2 integration overview
+
+Gazebo can be integrated within a ROS 2 system. Let's start describing the
+different types of integrations that you can achieve between Gazebo and ROS.
+
+* Use ROS to launch Gazebo: ROS prescribes a specific way to launch all
+the pieces needed in your system. There's a dedicated
+[launch mechanism](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Launch/Creating-Launch-Files.html)
+to orchestrate the launch of all your components and many tooling around it.
+Gazebo can be launched in this way.
+
+* Use ROS to interact with Gazebo topics via the [`ros_gz` bridge](https://github.com/gazebosim/ros_gz):
+Once Gazebo is up and running, it's very common to communicate with the
+simulation. A common way to perform this communication is via topics. Gazebo has
+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
+Gazebo and your ROS system, that translates between Gazebo Transport and ROS 2
+as needed.
+
+* Use ROS to spawn a Gazebo model: Gazebo worlds can include models that are
+loaded at startup. However, sometimes you need to spawn models at runtime. This
+task can be performed using ROS 2.
+
+## Requirements
+
+Please follow the [Install Gazebo and ROS document](/docs/latest/ros_installation)
+before starting this tutorial. A working installation of ROS 2 and Gazebo is
+required to go further.
+
+## Composition
+
+If you inspect the parameters of the launch files mentioned in the next
+tutorials, you'll notice that we have included in most cases a parameter named
+`use_composition`. When that parameter is set to `True`, the associated ROS
+node will be included within a ROS container. When this happens all the nodes
+live within the same process and can leverage intraprocess communication.
+
+Our recommendation is to always set the `use_composition` parameter to `True`.
+That way, the communication between Gazebo and the bridge will be intraprocess.
+If your ROS nodes are also written as composable nodes, make sure that they are
+launched with the `container_node_name` parameter matching the container name
+including Gazebo and the bridge.
+
+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

@@ -0,0 +1,61 @@
+# Spawn a Gazebo model from ROS 2
+
+Gazebo will spawn all the models included in the provided world file at startup.
+Additionally, it's possible to spawn new models at any time. To do so using ROS
+we have provided the following mechanisms:
+
+## Spawn a model using the launch file included in `ros_gz_sim`.
+
+The package `ros_gz_sim` contains a launch file named
+`ros_gz_spawn_model.launch.py`. You can use it to spawn a new model into an
+existing simulation. Here's an example:
+
+```bash
+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
+```
+
+Check [this block](https://github.com/gazebosim/ros_gz/blob/cadae1c8323a74395c09a37e3de4c669c8c09d4f/ros_gz_sim/launch/ros_gz_spawn_model.launch.py#L33-L44)
+from the source code to know all the different parameters accepted by this
+launch file.
+
+## Spawn a model from a custom launch file.
+
+It's also possible to spawn the model from your custom launch file. For that
+purpose we have created the `<gz_spawn_model/>` tag that can be used from you
+XML or YAML launch file. In this case, the arguments are passed as attributes
+within this tag. Here's an example:
+
+```xml
+<launch>
+  <arg name="world" default="" />
+  <arg name="file" default="" />
+  <arg name="xml_string" default="" />
+  <arg name="topic" default="" />
+  <arg name="name" default="" />
+  <arg name="allow_renaming" default="False" />
+  <arg name="x" default="" />
+  <arg name="y" default="" />
+  <arg name="z" default="" />
+  <arg name="roll" default="" />
+  <arg name="pitch" default="" />
+  <arg name="yaw" default="" />
+  <gz_spawn_model 
+    world="$(var world)"
+    file="$(var file)"
+    xml_string="$(var xml_string)"
+    topic="$(var topic)"
+    name="$(var name)"
+    allow_renaming="$(var allow_renaming)"
+    x="$(var x)"
+    y="$(var y)"
+    z="$(var z)"
+    roll="$(var roll)"
+    pitch="$(var pitch)"
+    yaw="$(var yaw)">
+  </gz_spawn_model>
+</launch>
+```
+
+In this case the `<gz_spawn_model>` parameters are read from the command line.
+That's an option but not strictly necessary as you could decide to hardcode some
+of the values.