Updating ros_gz documentation related to composition. (#526)

Signed-off-by: Carlos Agüero <[email protected]>

Author: caguero

harmonic/ros2_integration.md

@@ -67,18 +67,21 @@ 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:
 
-Note: If you run the bridge as a standalone node with composition enabled (default configuration),
+Note: If you run the bridge as a standalone node with composition enabled,
 you'll need to create a container first.
 ```bash
 ros2 run rclcpp_components component_container --ros-args -r __node:=ros_gz_container
 ```
 
+Alternatively, if an existing container is already running, you can pass its name
+when launching the bridge using the `container_name` parameter.
+
 And now, the container will load your bridge with:
 ```bash
-ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge config_file:=<path_to_your_YAML_file>
+ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge use_composition:=True config_file:=<path_to_your_YAML_file>
 ```
 
-Check [this block](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_bridge/launch/ros_gz_bridge.launch.py#L27-L33)
+Check [this block](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_bridge/launch/ros_gz_bridge.launch.py#L27-L34)
 from the source code to know all the different parameters accepted by this
 launch file.
 
@@ -94,21 +97,22 @@ within this tag. Here's an example:
   <arg name="bridge_name" />
   <arg name="config_file" />
   <arg name="container_name" default="ros_gz_container" />
+  <arg name="create_own_container" default="False" />
   <arg name="namespace" default="" />
-  <arg name="use_composition" default="True" />
+  <arg name="use_composition" default="False" />
   <arg name="use_respawn" default="False" />
   <arg name="log_level" default="info" />
   <ros_gz_bridge
     bridge_name="$(var bridge_name)"
     config_file="$(var config_file)"
     container_name="$(var container_name)"
+    create_own_container="$(var create_own_container)"
     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.

harmonic/ros2_launch_gazebo.md

@@ -37,11 +37,13 @@ within this tag. Here's an example for launching Gazebo server:
   <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" />
+  <arg name="create_own_container" default="False" />
+  <arg name="use_composition" default="False" />
   <gz_server 
     world_sdf_file="$(var world_sdf_file)"
     world_sdf_string="$(var world_sdf_string)"
     container_name="$(var container_name)"
+    create_own_container="$(var create_own_container)"
     use_composition="$(var use_composition)">
   </gz_server>
 </launch>

harmonic/ros2_overview.md

@@ -32,16 +32,37 @@ We'll backport it to ROS 2 Jazzy soon.
 ## 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.
+tutorials, you'll notice that we have included in most cases two parameters
+named `use_composition` and `create_own_container`. When the `use_composition`
+parameter is set to `True`, the associated ROS node will be loaded within a
+ROS container. When this happens, all the nodes within the same ROS container
+share the same process and can leverage intraprocess communication.
+
+The parameter `create_own_container` only makes sense when `use_composition` is
+set to `True`. This parameter lets you control whether your start a ROS
+container for your composable nodes or you defer to an external ROS container.
+
+Our recommendation is to always set the `use_composition` parameter to `True`
+and decide if you need to create your own container based on your configuration.
+Typically, if you're only dealing with your own launch files you'll probably set
+`create_own_container` to `True`. On the other hand, if you're using your launch
+files as part of a more complex startup where a ROS container is already
+present, you should set `create_own_container` to `False` and, instead, set the
+parameter `container_name` to the existing container name.
+
+That way, the communication between Gazebo, the bridge, and other potential
+ROS nodes will be intraprocess.
+
+![composition_options](images/composition_options.png)
+
+This figure illustrates the concept of composition. The left diagram captures
+the idea of not using composition. All the three example nodes are standalone
+nodes, and they can talk via interprocess communication. The center diagram
+represents the scenario where we use composition and we start our own container
+from our own launch file. All communication is intraprocess here. The right
+diagram is still using composition but the launch file doesn't start the
+container directly. This setup by itself will not work until you start an
+external ROS container (manually or via a separate launch file).
 
 You can learn more about ROS composition in [this tutorial](https://docs.ros.org/en/galactic/Tutorials/Intermediate/Composition.html).