Sync Ionic and Jetty directories with Harmonic (gazebosim#599)

* Updates from Harmonic/Ionic to Jetty

Signed-off-by: Addisu Z. Taddese <[email protected]>

* Updates from Harmonic to Ionic

Signed-off-by: Addisu Z. Taddese <[email protected]>

* Update rosdep instructions

Signed-off-by: Addisu Z. Taddese <[email protected]>

* Keep the skip-keys on gz-cmake3

Signed-off-by: Addisu Z. Taddese <[email protected]>

---------

Signed-off-by: Addisu Z. Taddese <[email protected]>

Author: azeey

ionic/ros2_integration.md

@@ -78,36 +78,34 @@ ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge con
 Alternatively, if an existing container is already running, you can pass its name
 when launching the bridge using the `container_name` parameter. More info about composition can be viewed [here](ros2_overview.md#composition)
 
-Check [this block](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_bridge/launch/ros_gz_bridge.launch.py#L27-L34)
+Check [this block](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_bridge/launch/ros_gz_bridge.launch.py#L25-L68)
 from the source code to know all the different parameters accepted by this
 launch file.
 
+QOS Overrides:
+
+QOS overrides can be passed as extra parameters to the bridge using the `bridge_params` argument of the launch file. An example of this:
+```bash
+ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge config_file:=<path_to_your_YAML_file> bridge_params:={'qos_overrides./topic_name.publisher.durability': 'transient_local', 'qos_overrides./another_topic_name.publisher.durability': 'transient_local'}
+```
+You can omit the following from what you pass to `bridge_params`: `{}`, ` `, `"`, `'`.
+
+More info about using QOS overrides can be found [here](https://docs.ros.org/en/jazzy/How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback.html#using-qos-overrides)
+
 ## Launching the bridge from a custom launch file in XML.
 
 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:
+within this tag. Here's a simplified example, a more comprehensive example can be viewed [here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/launch/ros_gz_bridge.launch):
 
 ```xml
 <launch>
   <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="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)">
+    config_file="$(var config_file)">
   </ros_gz_bridge>
 </launch>
 ```
@@ -119,7 +117,7 @@ of the values or not even use all the parameters.
 ## Launching the bridge from a custom launch file in Python.
 
 Here's a simplified example of a Python launch file used to load a bridge from
-Python:
+Python, a more comprehensive example can be viewed [here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/launch/ros_gz_bridge.launch.py):
 ```python
 from launch import LaunchDescription
 from launch.actions import DeclareLaunchArgument

ionic/ros2_launch_gazebo.md

@@ -54,45 +54,49 @@ an option but not strictly necessary as you could decide to hardcode some of the
 values or not even use all the parameters.
 
 ### Python
-Python launch files provide more low-level customization and logic compared to XML launch files. 
-In the following example, the user can specify a world argument to launch an environment for
-the Moon, Mars, or Enceladus. It additionally sets the resource path environment variable and
-sets up empty arrays for topics to be bridged and remapped from Gazebo to ROS 2:
+Python launch files provide more low-level customization and logic compared to XML launch files. For example, you can set environment variables and include Python specific functions and logic.
+In the following example, the user can replace the example package, world, and bridged topic with their own. This is intended as a scaffolding more than something that can be run on its own.
+
 ```python
-from ament_index_python.packages import get_package_share_directory
 from launch import LaunchDescription
-from launch.actions import (DeclareLaunchArgument, SetEnvironmentVariable, 
-                            IncludeLaunchDescription, SetLaunchConfiguration)
-from launch.substitutions import PathJoinSubstitution, LaunchConfiguration, TextSubstitution
 from launch_ros.actions import Node
+from launch.actions import SetEnvironmentVariable, IncludeLaunchDescription
 from launch.launch_description_sources import PythonLaunchDescriptionSource
+from launch.substitutions import PathJoinSubstitution
+from launch_ros.substitutions import FindPackageShare
 
 
 def generate_launch_description():
-    pkg_ros_gz_sim = get_package_share_directory('ros_gz_sim')
-    pkg_spaceros_gz_sim = get_package_share_directory('spaceros_gz_sim')
+    ros_gz_sim_pkg_path = get_package_share_directory('ros_gz_sim')
+    example_pkg_path = FindPackageShare('example_package')  # Replace with your own package name
     gz_launch_path = PathJoinSubstitution([pkg_ros_gz_sim, 'launch', 'gz_sim.launch.py'])
-    gz_model_path = PathJoinSubstitution([pkg_spaceros_gz_sim, 'models'])
 
     return LaunchDescription([
-        DeclareLaunchArgument(
-            'world',
-            default_value='moon',
-            choices=['moon', 'mars', 'enceladus'],
-            description='World to load into Gazebo'
+        SetEnvironmentVariable(
+            'GZ_SIM_RESOURCE_PATH',
+            PathJoinSubstitution([example_pkg_path, 'models'])
+        ),
+        SetEnvironmentVariable(
+            'GZ_SIM_PLUGIN_PATH',
+            PathJoinSubstitution([example_pkg_path, 'plugins'])
         ),
-        SetLaunchConfiguration(name='world_file', 
-                               value=[LaunchConfiguration('world'), 
-                                      TextSubstitution(text='.sdf')]),
-        SetEnvironmentVariable('GZ_SIM_RESOURCE_PATH', gz_model_path),
         IncludeLaunchDescription(
             PythonLaunchDescriptionSource(gz_launch_path),
             launch_arguments={
-                'gz_args': [PathJoinSubstitution([pkg_spaceros_gz_sim, 'worlds',
-                                                  LaunchConfiguration('world_file')])],
+                'gz_args': [PathJoinSubstitution([example_pkg_path, 'worlds/example_world.sdf'])],  # Replace with your own world file
                 'on_exit_shutdown': 'True'
             }.items(),
         ),
+
+        # Bridging and remapping Gazebo topics to ROS 2 (replace with your own topics)
+        Node(
+            package='ros_gz_bridge',
+            executable='parameter_bridge',
+            arguments=['/example_imu_topic@sensor_msgs/msg/[email protected]',],
+            remappings=[('/example_imu_topic',
+                         '/remapped_imu_topic'),],
+            output='screen'
+        ),
     ])
 ```
 

jetty/Model_insertion_fuel.md

@@ -49,7 +49,7 @@ There are a few different ways to spawn a model into the simulation.
     - Download the model files from [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models).
     - Extract the files and place them under your local model directory (e.g. `~/my-local-models/model-name`). 
     The folder should contain `materials`, `meshes` as well as the `model.config` and the `model.sdf` files. 
-    - Add your model directory as a resource with `export GZ_SIM_RESOURCE_PATH=~/my-local-models/model-name`
+    - Add your model directory as a resource with `export GZ_SIM_RESOURCE_PATH=~/my-local-models/`
     - Open the Gazebo Simulator and add the Resource Spawner Plugin, the model should now show up under your local resources. 
 
     ![Resource Spawner - Fuel resources](tutorials/fuel_insert/resource_spawner_local.png)

jetty/install_ubuntu_src.md

@@ -103,6 +103,38 @@ sudo apt -y install \
   $(sort -u $(find . -iname 'packages-'`lsb_release -cs`'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | sed '/gz\|sdf/d' | tr '\n' ' ')
 ```
 
+Alternatively, if you want to install dependencies using
+[rosdep](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Rosdep.html),
+ensure that [rosdep is installed](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Rosdep.html#how-do-i-use-the-rosdep-tool)
+and use the following command:
+
+```bash
+cd ~/workspace/src
+rosdep install -i --from-path . -y \
+    --skip-keys "gz-cmake3 DART libogre-dev libogre-next-2.3-dev"
+```
+
+The `rosdep` command attempts to install dependencies listed in `package.xml`
+files, but when problems arise the `--skip-keys` argument is used. Explanations
+for its use in the previous line are given below:
+
+* `gz-cmake3`: `gz-tools2` can build from source against
+  [any of `gz-cmake3`, `gz-cmake4`, and `gz-cmake` (v5)](https://github.com/gazebosim/gz-tools/pull/128),
+  and this workspace only contains `gz-cmake` (v5). The `gz-tools2` `package.xml`
+  file only [depends on gz-cmake3](https://github.com/gazebosim/gz-tools/blob/2b228e5b956/package.xml#L13)
+  and since that package is not present, use `--skip-keys gz-cmake3`.
+* `DART`: `gz-physics` can build against [dartsim](http://dartsim.github.io),
+  which is listed as DART in the [gz-physics package.xml file](https://github.com/gazebosim/gz-physics/blob/main/package.xml#L16).
+  This package is not in the workspace, so `DART` is added to the `--skip-keys`
+  string.
+  See the discussion in [gz-physics#608](https://github.com/gazebosim/gz-physics/pull/608#discussion_r1589512231)
+  for more background on the package name used for `DART`.
+* `libogre-dev` and `libogre-next-2.3-dev`: `gz-rendering` can build against
+  ogre 1.9 and ogre-next 2.3. The debian package names are listed as
+  dependencies in the [gz-rendering package.xml](https://github.com/gazebosim/gz-rendering/blob/main/package.xml#L22-L23)
+  but they are not available on all Linux versions, so work around with
+  `--skip-keys "libogre-dev libogre-next-2.3-dev"`.
+
 ## Building the Gazebo Libraries
 
 Once the compiler and all the sources are in place it is time to compile them.

jetty/ros2_integration.md

@@ -65,43 +65,93 @@ for a valid configuration file.
 
 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 bridge_name:=ros_gz_bridge config_file:=<path_to_your_YAML_file>
+```
+
+Launching with composition:
+```bash
+ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge config_file:=<path_to_your_YAML_file> use_composition:=True create_own_container:=True
+```
+Alternatively, if an existing container is already running, you can pass its name
+when launching the bridge using the `container_name` parameter. More info about composition can be viewed [here](ros2_overview.md#composition)
+
+Check [this block](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_bridge/launch/ros_gz_bridge.launch.py#L25-L68)
+from the source code to know all the different parameters accepted by this
+launch file.
+
+QOS Overrides:
 
+QOS overrides can be passed as extra parameters to the bridge using the `bridge_params` argument of the launch file. An example of this:
 ```bash
-ros2 launch ros_gz_bridge ros_gz_bridge.launch.py 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 config_file:=<path_to_your_YAML_file> bridge_params:={'qos_overrides./topic_name.publisher.durability': 'transient_local', 'qos_overrides./another_topic_name.publisher.durability': 'transient_local'}
 ```
+You can omit the following from what you pass to `bridge_params`: `{}`, ` `, `"`, `'`.
 
-## Launching the bridge from a custom launch file.
+More info about using QOS overrides can be found [here](https://docs.ros.org/en/jazzy/How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback.html#using-qos-overrides)
+
+## Launching the bridge from a custom launch file in XML.
 
 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:
+within this tag. Here's a simplified example, a more comprehensive example can be viewed [here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/launch/ros_gz_bridge.launch):
 
 ```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)">
+  <arg name="bridge_name" />
+  <arg name="config_file" />
+  <ros_gz_bridge
+    bridge_name="$(var bridge_name)"
+    config_file="$(var config_file)">
   </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.
+of the values or not even use all the parameters.
+
+## Launching the bridge from a custom launch file in Python.
+
+Here's a simplified example of a Python launch file used to load a bridge from
+Python, a more comprehensive example can be viewed [here](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/launch/ros_gz_bridge.launch.py):
+```python
+from launch import LaunchDescription
+from launch.actions import DeclareLaunchArgument
+from launch.substitutions import LaunchConfiguration, TextSubstitution
+from ros_gz_bridge.actions import RosGzBridge
+
+
+def generate_launch_description():
+
+    bridge_name = LaunchConfiguration('bridge_name')
+    config_file = LaunchConfiguration('config_file')
+
+    declare_bridge_name_cmd = DeclareLaunchArgument(
+        'bridge_name', description='Name of ros_gz_bridge node'
+    )
+
+    declare_config_file_cmd = DeclareLaunchArgument(
+        'config_file', description='YAML config file'
+    )
+
+    # Create the launch description and populate
+    ld = LaunchDescription([
+        RosGzBridge(
+            bridge_name=LaunchConfiguration('bridge_name'),
+            config_file=LaunchConfiguration('config_file'),
+        ),
+    ])
+
+    # Declare the launch options
+    ld.add_action(declare_bridge_name_cmd)
+    ld.add_action(declare_config_file_cmd)
+
+    return ld
+```
 
 ## Publish key strokes to ROS