Update Ionic tutorial with latest changes that were made in the Harmo…

…nic directory (gazebosim#489) * Update Ionic tutorial with latest changes that were made in the Harmonic directory Signed-off-by: Addisu Z. Taddese <[email protected]> * More updates Signed-off-by: Addisu Z. Taddese <[email protected]> * Update ionic/install_osx.md Co-authored-by: Ian Chen <[email protected]> Signed-off-by: Addisu Z. Taddese <[email protected]> --------- Signed-off-by: Addisu Z. Taddese <[email protected]> Co-authored-by: Ian Chen <[email protected]>
azeey · Jan 9, 2025 · e58d442 · e58d442
1 parent 23a8b4e
commit e58d442
Show file tree

Hide file tree

Showing 15 changed files with 330 additions and 77 deletions.
diff --git a/ionic/comparison.md b/ionic/comparison.md
@@ -36,7 +36,7 @@ Sonar | ✓ | [Issue](https://github.com/gazebosim/gz-sensors/issues/19)
 Thermal camera | ✕  | ✓
 Triggered camera | ✕ | ✓
 Wide-angle camera | ✓ | ✓
-Wireless | ✓ | [Issue](https://github.com/gazebosim/gz-sensors/issues/28)
+Wireless | ✓ | ✓ RFComms
 
 Sensor features | Gazebo-classic | Gazebo Sim
 -- | -- | --

diff --git a/ionic/index.yaml b/ionic/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

diff --git a/ionic/install_osx.md b/ionic/install_osx.md
@@ -1,15 +1,8 @@
 # Binary Installation on MacOS
 
 All the Ionic binaries are available in Monterey and Ventura using the
-[homebrew package manager](https://brew.sh/).
 
-The homebrew tool can be installed using:
-
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
-```
-
-After installing the homebrew package manager, Gazebo Ionic can be installed running:
+[Homebrew package manager](https://brew.sh/). After installing Homebrew, Gazebo Ionic can be installed running:
 
 ```bash
 brew tap osrf/simulation

diff --git a/ionic/install_osx_src.md b/ionic/install_osx_src.md
@@ -12,33 +12,34 @@ The easiest way to get the sources of all libraries is to use
 
 To compile all the different libraries and gz-sim in the right order
 [colcon](https://colcon.readthedocs.io/en/released/) is recommended.
-The colcon tool is available on all platforms using pip (or pip3, if pip fails).
 
-## Python3 from homebrew
-
-Tools and dependencies for Ionic can be installed using the [homebrew package manager](https://brew.sh/).
-The homebrew tool can be installed by entering the following in a terminal:
+Tools and dependencies for Ionic can be installed using the [Homebrew package manager](https://brew.sh/). After installing Homebrew, add the `osrf/simulation` to Homebrew tap to be able to install prebuilt dependencies.
 
 ```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+brew tap osrf/simulation
+brew update
 ```
 
-Ionic is compatible with Python3; it can be installed by running the following in a terminal:
+### Install compiler requirements
+
+Building Gazebo Libraries require at least Xcode 10 on MacOS Mojave. The Xcode Command Line Tools are sufficient, and can be installed with:
 
 ```bash
-brew install python3
+xcode-select --install
 ```
 
-## vcstool and colcon from pip
+## Python 3 from Homebrew
 
-PIP is available on all platforms:
+Ionic is compatible with Python 3. Install the latest version from Homebrew:
 
 ```bash
-python3 -m pip install vcstool
+brew install python3
 ```
 
+## vcstool and colcon from PyPI
+
 ```bash
-python3 -m pip install -U colcon-common-extensions
+python3 -m pip install -U colcon-common-extensions vcstool
 ```
 
 ## Getting the sources
@@ -55,7 +56,7 @@ All the sources of gazebo-ionic are declared in a yaml file. Download
 it to the workspace:
 
 ```bash
-curl -O https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-ionic.yaml
+curl -OL https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-ionic.yaml
 ```
 
 Use `vcstool` to automatically retrieve all the Gazebo libraries sources from
@@ -69,19 +70,10 @@ The src subdirectory should contain all the sources ready to be built.
 
 ## Install dependencies
 
-Add `osrf/simulation` to Homebrew formulae
-
-```bash
-brew update
-brew tap osrf/simulation
-```
-
-Install all dependencies:
-
 Dependency for Ogre:
 
 ```bash
-brew cask install xquartz
+brew install --cask xquartz
 ```
 
 General dependencies:
@@ -103,17 +95,6 @@ Unlink `qt` to avoid conflicts with other versions of qt (e.g. qt6)
 brew unlink qt
 ```
 
-### Install compiler requirements
-
-The Gazebo Libraries require the Xcode 10 compiler on MacOS Mojave.
-
-On Mac machines, gcc is acquired by installing Xcode command line tools.
-The required version of Xcode for Ionic is Xcode 10.3, which can be downloaded from
-[Apple Developer Site](https://developer.apple.com/download/more/).
-You will need to sign in to your Apple account and download the Mojave version of
-Xcode command line tools. Command line tools can also be obtained by downloading
-Xcode from the Apple App Store (installing the full app may take over an hour).
-
 ## Building the Gazebo Libraries
 
 Once the compiler and all the sources are in place it is time to compile them.
@@ -172,16 +153,16 @@ If there are no errors, all the binaries should be ready to use.
 
 The workspace needs to be sourced every time a new terminal is used.
 
-Run the following command to source the workspace in bash:
+Run the following command to source the workspace in zsh (the default macOS shell):
 
-```bash
-. ~/workspace/install/setup.bash
+```zsh
+. ~/workspace/install/setup.zsh
 ```
 
-Or in zsh:
+Or if you are using bash:
 
-```zsh
-. ~/workspace/install/setup.zsh
+```bash
+. ~/workspace/install/setup.bash
 ```
 
 You should now be able to launch gazebo:

diff --git a/ionic/install_ubuntu.md b/ionic/install_ubuntu.md
@@ -1,6 +1,6 @@
 # Binary Installation on Ubuntu
 
-Ionic binaries are provided for Ubuntu Jammy (22.04) and Ubuntu Noble (24.04). The
+Ionic binaries are provided for Ubuntu Noble (24.04). The
 Ionic binaries are hosted in the packages.osrfoundation.org repository.
 To install all of them, the metapackage `gz-ionic` can be installed.
 

diff --git a/ionic/install_windows.md b/ionic/install_windows.md
@@ -7,7 +7,6 @@ WARNING: Current Windows support is experimental.
 Most Gazebo packages are available in Windows 10 using the [conda-forge package manager](https://conda-forge.org/),
 and the Gazebo feedstock recipes can be found [here](https://github.com/search?q=org:conda-forge+libgz&type=code).
 
-Additionally, command line tools, the DART physics engine, and some tests are not currently supported in Windows.
 
 In order to use `conda-forge`, you will need to
 1. Install a [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html).

diff --git a/ionic/install_windows_src.md b/ionic/install_windows_src.md
@@ -4,10 +4,10 @@ WARNING: Current Windows support is experimental.
 
 # Source Installation on Windows 10 or 11
 
-OGRE2 rendering capabilities are not currently supported in Windows, and Gazebo GUI
+OGRE2 rendering capabilities are supported in Windows, and Gazebo GUI
 works in a limited fashion. These functionalities correspond to the currently
 building packages `gz-rendering` and `gz-sim`, respectively. The packages will build,
-but you can expect runtime failures when using their functionalities.
+without any failures when using their functionalities.
 
 > **NOTE**
 > You should be able to use `ogre` as a rendering engine instead of the default `ogre2`.
@@ -139,31 +139,33 @@ call install\setup.bat
 .\install\setup.ps1
 ```
 
+You should now be able to launch gazebo:
+
+```bash
+# Launch server in one terminal 
+gz sim -s
+
+# In separate terminal, launch gui
+gz sim -g
+```
+
 This is the end of the source install instructions; head back to the [Getting started](getstarted)
 page to start using Gazebo!
 
-> **NOTE**
-> As Gazebo GUI is not yet working, running `gz sim` will not work. You can run only the server with
-> ```batch
-> gz sim -s -v
-> ```
-
 > **NOTE**
 > If your username contains spaces (which is quite common on Windows), you will probably get errors
 >  saying `Invalid partition name [Computer:My User With Spaces]`. Fix this by changing `GZ_PARTITION`
 >  to something else:
-> ```batch
+> ```bat
 > set GZ_PARTITION=test
 > ```
 > Remember to set the same partition in all other consoles.
 
 ### Gazebo GUI workaround
 
 Although running `gz sim` without arguments is not supported on Windows,
-and `gz sim -g` is also not supported, there is a workaround you can apply
-to be able to launch `gz sim -g` on Windows.
+ the `gz sim -g` command is  supported, and you can use it to launch the graphical interface on Windows.
 
-> Manually comment [these lines](https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.5.0/src/cmd/cmdsim.rb.in#L497-L501) and [these lines](https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.5.0/src/cmd/cmdsim.rb.in#L558-L562) in file `install\lib\ruby\gz\cmdsim9.rb`.
 
 This should allow you to run the GUI in a separate console, connecting to the server running in another console.
 

diff --git a/ionic/moving_robot.md b/ionic/moving_robot.md
@@ -63,7 +63,7 @@ After the `-p` option we specify the content (value) of the message: linear spee
 
 **Hint:** You can know what every topic option does using this command: `gz topic -h`
 
-For more information about `Topics` and `Messages` in Gazebo check the [Transport library tutorials](https://gazebosim.org/api/transport/9.0/tutorials.html)
+For more information about `Topics` and `Messages` in Gazebo check the [Transport library tutorials](https://gazebosim.org/api/transport/14/tutorials.html)
 
 ## Moving the robot using the keyboard
 

diff --git a/ionic/ros2_integration.md b/ionic/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](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.