diff --git a/harmonic/GUI_tutorial.md b/harmonic/GUI_tutorial.md index 6183e0a58..5c6accdc6 100644 --- a/harmonic/GUI_tutorial.md +++ b/harmonic/GUI_tutorial.md @@ -119,7 +119,7 @@ Along the bottom edge of the scene, you'll notice several buttons: ![Playback buttons](tutorials/gui/playback.png) -From left to right, the options are `Play`, `Steps` and `RTF` (real time factor). +From left to right, the options are `Play`, `Steps`, `Reset`, `RTF` (real time factor). Pressing `Play` will start the simulation. You can use the same button to pause the simulation as well. @@ -129,6 +129,8 @@ You can customize step size by hovering over the button. ![hover steps](tutorials/gui/hover_steps.png) +Pressing `Reset` will clear any unsaved modification to the scene. Clicking it will remove the newly inserted shapes `box_0`, `sphere_0` and `capsule_0`. + At the furthest right end of the scene, you can expand `RTF` to see not only the percentage value that compares real time with sim time, but also those individual values themselves, as well as iteration count. ![RTF expanded](tutorials/gui/rtf_expanded.png) diff --git a/harmonic/Model_insertion_fuel.md b/harmonic/Model_insertion_fuel.md index aea3c99ae..f08fea01a 100644 --- a/harmonic/Model_insertion_fuel.md +++ b/harmonic/Model_insertion_fuel.md @@ -32,31 +32,31 @@ Check that the file size on the right is reasonable for your application before There are a few different ways to spawn a model into the simulation. -1. **Spawn from 'Fuel Resource' using the Resource Spawner plugin.** +1. **Spawn from 'Fuel resources' using the Resource Spawner plugin.** Select the Resource Spawner plugin from the plugin menu (top right corner). The plugin will appear in the right panel, you might need to scroll down to be able to see the plugin. - Wait until the resource are loaded under the 'Fuel Resource' panel. + Wait until the resources are loaded under the 'Fuel resources' panel. Select a resource owner (e.g. openrobotics), you can now search for the model name in the right panel. Click on the cloud icon to download the model. When the model has been downloaded, you can click on the model and insert it into your simulation scene. - ![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_cloud.png) + ![Resource Spawner - Fuel resources](tutorials/fuel_insert/resource_spawner_cloud.png) 2. **Download model files from Fuel and spawn from local sources using the Resource Spawner plugin.** - Download the model files from [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models). - - Extract the files and places them under your local model directory (e.g. `~/my-local-models/model-name`). + - 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/` - Open the Gazebo Simulator and add the Resource Spawner Plugin, the model should now show up under your local resources. - ![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_local.png) + ![Resource Spawner - Fuel resources](tutorials/fuel_insert/resource_spawner_local.png) 3. **Copying the SDF snippet and adding it to your custom world SDF file.** - With the `<>` button you can directly copy a SDF snippet to paste into your world SDF file. + With the `<>` button you can directly copy an SDF snippet to paste into your world SDF file. The SDF snippet will look something like this: ``` @@ -72,10 +72,10 @@ There are a few different ways to spawn a model into the simulation. ![spawn](tutorials/fuel_insert/husky.gif) -4. **Downloading the code to permanently add a Fuel model to your custum SDF file.** +4. **Downloading the code to permanently add a Fuel model to your custom SDF file.** If you prefer to add a Fuel model permanently to an `sdf` file, you can just as easily download the code by clicking the download-arrow icon to the right of the model's image. - Kook at the tutorial on [SDF Worlds](sdf_worlds) for more information on how to construct a custom world SDF file. + Look at the tutorial on [SDF Worlds](sdf_worlds) for more information on how to construct a custom world SDF file. Now you can add more models, or even load in any one of the plugins you learned about to interact with the model the same way you could with the shapes in the previous tutorial. diff --git a/harmonic/install_ubuntu_src.md b/harmonic/install_ubuntu_src.md index 04de05108..6982ca650 100644 --- a/harmonic/install_ubuntu_src.md +++ b/harmonic/install_ubuntu_src.md @@ -29,32 +29,17 @@ sudo apt install python3-pip lsb-release gnupg curl ## vcstool and colcon from pip -PIP is available on all platforms: +PIP is available on all platforms. Using a PIP workspace to install the tools: ```bash -pip install vcstool || pip3 install vcstool +python3 -m venv $HOME/vcs_colcon_installation +. $HOME/vcs_colcon_installation/bin/activate +pip3 install vcstool colcon-common-extensions ``` -```bash -pip install -U colcon-common-extensions || pip3 install -U colcon-common-extensions -``` - -Check that no errors were printed while installing with PIP. If your system is not recognising the commands, and you're using a system that is compatible with Debian or Ubuntu packages, see the instructions below to install using `apt`. - -After installing `vcstool` and `colcon` with PIP, you may need to add their executables to your `$PATH`. -Check where the installation of these packages took place: - -```bash -pip show vcstool || pip3 show vcstool | grep Location - -pip show colcon-common-extensions || pip3 show colcon-common-extensions | grep Location -``` - -If your install path is prefixed with `$HOME/.local`, you'll probably need to add the executables within this directory to your `$PATH` in order to avoid "command not found" errors when using `vcstool` and `colcon` later on: - -```bash -export PATH=$PATH:$HOME/.local/bin/ -``` +`vcs` and `colcon` are now available from the PIP workspace in the current +terminal. For using them in other terminals run the `activate` script as +done above. ## vcstool and colcon from apt @@ -143,6 +128,15 @@ colcon graph If that is the case, then you are ready to build the whole set of libraries: +:::{warning} + +Compilation can take up to 16Gb of RAM memory. Use MAKEFLAGS with +colcon as detailed in its instructions to reduce the number of +compilation threads if needed. + +::: + + ```bash colcon build --merge-install ``` @@ -150,7 +144,7 @@ colcon build --merge-install To speed up the build process, you could also disable tests by using ```bash -colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install +colcon build --cmake-args ' -DBUILD_TESTING=OFF' --merge-install ``` To use debuggers activate debug symbols. Gazebo will run slower, but you'll be able to use GDB: @@ -228,7 +222,7 @@ To perform QML debugging you'll need: You will need to build Gazebo with: ```bash -colcon build --cmake-args -DQT_QML_DEBUG --merge-install +colcon build --cmake-args ' -DQT_QML_DEBUG' --merge-install ``` > **Note:** Advanced users may note that only the `gz-sim` project needs this flag. diff --git a/harmonic/install_windows_src.md b/harmonic/install_windows_src.md index 812cd65af..cf54e4bf1 100644 --- a/harmonic/install_windows_src.md +++ b/harmonic/install_windows_src.md @@ -15,10 +15,22 @@ without any failures when using their functionalities. ## Install dependencies -1. Install a conda distribution. As Gazebo uses all dependencies from the conda-forge channel, - we suggest to install miniforge following [the official miniforge installation docs](https://github.com/conda-forge/miniforge#windows) - You will likely want to check the box to add `conda` to your `PATH` - during the installation process so that you won't have to do this step manually. +1. If you do not have the conda package manager installed in your system, install a conda distribution. + As Gazebo uses all dependencies from the conda-forge channel, we suggest to install miniforge following [the official miniforge installation docs](https://github.com/conda-forge/miniforge#windows) by executing the following commands in a "Command Prompt" terminal: + ```cmd + curl.exe -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe + start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3 + %UserProfile%\Miniforge3\condabin\conda init + %UserProfile%\Miniforge3\condabin\conda config --set auto_activate_base false + del Miniforge3-Windows-x86_64.exe + ``` + If you followed this step correctly, you should be able to access `conda` in any new "Command Prompt" terminal you open. + To verify that, check that if you open a new terminal and execute `conda info`, the output begins with: + ```cmd + active environment : None + shell level : 0 + [..] + ``` 2. Install [Visual Studio 2019 or 2022](https://visualstudio.microsoft.com/downloads/). The Community version is free for students, open-source developers, and personal @@ -27,21 +39,24 @@ without any failures when using their functionalities. cmake via Conda. All other checkboxes can be left unchecked. 3. Open a Visual Studio Command Prompt (search for "x64 Native Tools Command Prompt - for VS" in the Windows search field near the Windows button). Optionally, + for VS" in the Windows search field near the Windows button) or Developer PowerShell + for VS (search for "developer powershell"). Optionally, right-click and pin to the task bar for quick access in the future. - If you did not add Conda to your `PATH` environment variable during Conda installation, - you may need to navigate to the location of `condabin` in order to use the `conda` command. - To find `condabin`, search for "Anaconda Prompt" in the Windows search field near the - Windows button, open it, run `where conda`, and look for a line containing the directory `condabin`. + If you chose PowerShell, you need to do a few steps to be able to use Conda and Gazebo in it: + ```bash + conda init powershell + # Restart the PowerShell + Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser + ``` -4. Navigate to your `condabin`, if necessary, and then create and activate a Conda environment: +4. Create and activate a Conda environment: ```bash conda create -n gz-ws conda activate gz-ws ``` Once you have activated an environment, a prefix like `(gz-ws)` will be prepended to - your prompt, and you can use the `conda` command outside of the `condabin` directory. + your prompt. You can use `conda info --envs` to see all of your environments. @@ -65,8 +80,8 @@ without any failures when using their functionalities. conda install cmake git vcstool curl pkg-config ^ colcon-common-extensions dartsim eigen freeimage gdal gts ^ glib dlfcn-win32 ffmpeg ruby tinyxml2 tinyxml ^ - libprotobuf urdfdom zeromq cppzmq ogre=1.10 ogre-next jsoncpp ^ - libzip qt pybind11 --channel conda-forge + protobuf urdfdom zeromq cppzmq ogre=1.10 ogre-next jsoncpp ^ + libzip qt pybind11 boost --channel conda-forge ``` This can take tens of minutes (or less when using libmamba solver). @@ -104,7 +119,7 @@ colcon graph If that is the case, then you are ready to build the whole set of libraries: ```bash -colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install --packages-up-to gz-sim8 gz-tools2 +colcon build --cmake-args -DBUILD_TESTING=OFF -DSKIP_SWIG=ON --merge-install --packages-up-to gz-sim8 gz-tools2 ``` Tests are turned off as they are not currently supported on Windows. @@ -129,13 +144,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 ( and Conda environment activated before that). -Run the following command to source the workspace: +The overall instructions for setting up a new terminal to use the built +workspace are: ```bash # CMD +conda activate gz-ws call install\setup.bat # PowerShell +conda activate gz-ws .\install\setup.ps1 ``` diff --git a/harmonic/moving_robot.md b/harmonic/moving_robot.md index e5c72a868..59462cabf 100644 --- a/harmonic/moving_robot.md +++ b/harmonic/moving_robot.md @@ -88,7 +88,26 @@ The last command will display all messages sent on `/keyboard/keypress` topic. In the Gazebo window press different keys and you should see data (numbers) on the terminal where you run the `gz topic -e -t /keyboard/keypress` command. -![KeyPublisher](tutorials/moving_robot/keypublisher_data.png) +``` +$ gz topic -e -t /keyboard/keypress +data: 68 + +data: 85 + +data: 72 + +data: 74 + +data: 81 + +data: 16777235 + +data: 16777234 + +data: 16777237 + +data: 16777236 +``` We want to map these keystrokes into messages of type `Twist` and publish them to the `/cmd_vel` topic which our model listens to. The `TriggeredPublisher` plugin will do this. diff --git a/harmonic/ros2_integration.md b/harmonic/ros2_integration.md index d504d8101..5dcc82291 100644 --- a/harmonic/ros2_integration.md +++ b/harmonic/ros2_integration.md @@ -76,7 +76,7 @@ Launching with composition: ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge config_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#composition) +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) from the source code to know all the different parameters accepted by this diff --git a/harmonic/ros2_launch_gazebo.md b/harmonic/ros2_launch_gazebo.md index ee5b3db9d..30d265323 100644 --- a/harmonic/ros2_launch_gazebo.md +++ b/harmonic/ros2_launch_gazebo.md @@ -137,4 +137,4 @@ ros2 launch ros_gz_sim ros_gz_sim.launch.py world_sdf_file:=empty.sdf bridge_nam In the above launch files you may notice that the `create_own_container` argument for `ros_gz_bridge` is hardcoded to `False`. This has been done to prevent two duplicate containers from getting created (one for `gz_server` and another one for `ros_gz_bridge`), and instead make `ros_gz_bridge` use the container created by `gz_server`. More info about this can be viewed [here](https://github.com/gazebosim/ros_gz/pull/620#issue-2595570189) More info about `ros_gz_bridge` can be viewed [here](ros2_integration). -More info about composition can be viewed [here](ros2_overview#composition). +More info about composition can be viewed [here](ros2_overview.md#composition). diff --git a/harmonic/sensors.md b/harmonic/sensors.md index cbdb35082..cbc3e4a17 100644 --- a/harmonic/sensors.md +++ b/harmonic/sensors.md @@ -322,17 +322,18 @@ You can download the finished node for this demo from [here](https://github.com/ #### The lidar_node ```cpp -gz::transport::Node node; std::string topic_pub = "/cmd_vel"; -gz::msgs::Twist data; +gz::transport::Node node; auto pub = node.Advertise(topic_pub); ``` -We declare a `node` which will publish to `cmd_vel` topic and defined the message type `Twist`. Then advertise our node. +We declare a `node` which will publish to `cmd_vel` topic. Then advertise our node. ```cpp void cb(const gz::msgs::LaserScan &_msg) { + gz::msgs::Twist data; + bool allMore = true; for (int i = 0; i < _msg.ranges_size(); i++) { @@ -362,11 +363,11 @@ If so we publish a message to our car to move forward. Otherwise we make the rob ```cpp int main(int argc, char **argv) { - std::string topic = "/lidar"; + std::string topic_sub = "/lidar"; // Subscribe to a topic by registering a callback. - if (!node.Subscribe(topic, cb)) + if (!node.Subscribe(topic_sub, cb)) { - std::cerr << "Error subscribing to topic [" << topic << "]" << std::endl; + std::cerr << "Error subscribing to topic [" << topic_sub << "]" << std::endl; return -1; } diff --git a/harmonic/troubleshooting.md b/harmonic/troubleshooting.md index 8bd89918b..0c639fbe2 100644 --- a/harmonic/troubleshooting.md +++ b/harmonic/troubleshooting.md @@ -19,6 +19,23 @@ GZ_CONFIG_PATH=/share/gz/ ## macOS +### Maximum number of open files reached `ulimit` error +When installing using homebrew, you may see the following error message: + +```bash +Error: The maximum number of open files on this system has been reached. Use 'ulimit -n' to increase this limit. +``` + +As suggested in the error message, run the command below and check the output. The default value is set to `256` which is too low. +```bash +ulimit -n +``` + +Run the following command to increase the open files `ulimit` and then proceed with the homebrew install: +```bash +ulimit -n 10240 +``` + ### Unable to find `urdf_model.h` error After installing all the dependencies and starting the build process, you may encounter an error that looks like this: @@ -233,3 +250,36 @@ foreach { } popd ``` + +### Many errors from setuptools when running colcon +When calling `colcon` to build the packages, you may face a wall of Python errors similar to this one: + +``` +> colcon graph +Traceback (most recent call last): + File "", line 1, in +ModuleNotFoundError: No module named 'setuptools.extern' +[10.385s] colcon.colcon_core.package_identification ERROR Exception in package identification extension 'python_setup_py' in 'conda\Lib\site-packages\adodbapi': Command '['D:\\programovani\\gz-ws\\conda\\python.exe', '-c', "import sys;from setuptools.extern.packaging.specifiers import SpecifierSet;from distutils.core import run_setup;dist = run_setup( 'setup.py', script_args=('--dry-run',), stop_after='config');skip_keys = ('cmdclass', 'distclass', 'ext_modules', 'metadata');data = { key: value for key, value in dist.__dict__.items() if ( not key.startswith('_') and not callable(value) and key not in skip_keys and key not in dist.display_option_names )};data['metadata'] = { k: v for k, v in dist.metadata.__dict__.items() if k not in ('license_files', 'provides_extras')};sys.stdout.buffer.write(repr(data).encode('utf-8'))"]' returned non-zero exit status 1. +``` + +The messages are quite cryptic and do not point at the root cause. The root cause is that you have probably created a conda env directory in the same directory where you have the `src` directory containing the Gazebo sources (you have probably used `conda create --prefix ...` to create the env directory at a non-default destination). + +The solution is to move the conda env directory one level up. + +E.g., this is the problematic folder structure: + +``` +gz-ws\ + conda\ # The conda env + src\ # The Gazebo sources + gz-sim\ +``` + +To fix it, change the structure to something like this: + +``` +gz-ws\ + src\ + gz-sim\ +conda\ +``` diff --git a/harmonic/tutorials/gui/entity_select.png b/harmonic/tutorials/gui/entity_select.png index 30fcea17f..76b166365 100644 Binary files a/harmonic/tutorials/gui/entity_select.png and b/harmonic/tutorials/gui/entity_select.png differ diff --git a/harmonic/tutorials/gui/grid_config.png b/harmonic/tutorials/gui/grid_config.png index 2243a63f3..6e16417ae 100644 Binary files a/harmonic/tutorials/gui/grid_config.png and b/harmonic/tutorials/gui/grid_config.png differ diff --git a/harmonic/tutorials/gui/shape_insertion.png b/harmonic/tutorials/gui/shape_insertion.png index 2263701b5..15a9b1d92 100644 Binary files a/harmonic/tutorials/gui/shape_insertion.png and b/harmonic/tutorials/gui/shape_insertion.png differ diff --git a/harmonic/tutorials/gui/toolbars.png b/harmonic/tutorials/gui/toolbars.png index 616693080..586e6b4f0 100644 Binary files a/harmonic/tutorials/gui/toolbars.png and b/harmonic/tutorials/gui/toolbars.png differ diff --git a/harmonic/tutorials/moving_robot/keypublisher_data.png b/harmonic/tutorials/moving_robot/keypublisher_data.png deleted file mode 100644 index 0b357dbbd..000000000 Binary files a/harmonic/tutorials/moving_robot/keypublisher_data.png and /dev/null differ diff --git a/ionic/Model_insertion_fuel.md b/ionic/Model_insertion_fuel.md index bce0e43a5..f08fea01a 100644 --- a/ionic/Model_insertion_fuel.md +++ b/ionic/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) diff --git a/ionic/ros2_integration.md b/ionic/ros2_integration.md index f4330cd29..16f689c3c 100644 --- a/ionic/ros2_integration.md +++ b/ionic/ros2_integration.md @@ -65,13 +65,24 @@ 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:= +``` +Launching with composition: ```bash -ros2 launch ros_gz_bridge ros_gz_bridge.launch.py name:=ros_gz_bridge config_file:= +ros2 launch ros_gz_bridge ros_gz_bridge.launch.py bridge_name:=ros_gz_bridge config_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#L27-L34) +from the source code to know all the different parameters accepted by this +launch file. -## Launching the bridge from a custom launch file. +## 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 `` tag that can be used from you @@ -80,17 +91,19 @@ within this tag. Here's an example: ```xml - - + + + - + - ` 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: +```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 diff --git a/ionic/ros2_launch_gazebo.md b/ionic/ros2_launch_gazebo.md index 8afe673d0..0213a8de7 100644 --- a/ionic/ros2_launch_gazebo.md +++ b/ionic/ros2_launch_gazebo.md @@ -37,11 +37,13 @@ within this tag. Here's an example for launching Gazebo server: - + + @@ -49,7 +51,7 @@ within this tag. Here's an example for launching Gazebo server: In this case the `` 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. +values or not even use all the parameters. ### Python Python launch files provide more low-level customization and logic compared to XML launch files. @@ -91,12 +93,48 @@ def generate_launch_description(): 'on_exit_shutdown': 'True' }.items(), ), - Node( - package='ros_gz_bridge', - executable='parameter_bridge', - arguments=[], - remappings=[], - output='screen' + ]) +``` + +Here's another example using a higher level action from Python to launch `gzserver`: +```python +from launch import LaunchDescription +from launch.actions import DeclareLaunchArgument +from launch.substitutions import LaunchConfiguration +from ros_gz_sim.actions import GzServer + + +def generate_launch_description(): + + declare_world_sdf_file_cmd = DeclareLaunchArgument( + 'world_sdf_file', default_value='', + description='Path to the SDF world file') + + # Create the launch description and populate + ld = LaunchDescription([ + GzServer( + world_sdf_file=LaunchConfiguration('world_sdf_file') ), ]) + + # Declare the launch options + ld.add_action(declare_world_sdf_file_cmd) + + return ld +``` + + +## Launching with ros_gz_bridge + +An example launch file for XML can be viewed [here](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_sim/launch/ros_gz_sim.launch) +An example launch file for Python can be viewed [here](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_sim/launch/ros_gz_sim.launch.py) + +Example command for directly using these launch files from the terminal: +```bash +ros2 launch ros_gz_sim ros_gz_sim.launch.py world_sdf_file:=empty.sdf bridge_name:=ros_gz_bridge config_file:= use_composition:=True create_own_container:=True ``` + +In the above launch files you may notice that the `create_own_container` argument for `ros_gz_bridge` is hardcoded to `False`. This has been done to prevent two duplicate containers from getting created (one for `gz_server` and another one for `ros_gz_bridge`), and instead make `ros_gz_bridge` use the container created by `gz_server`. More info about this can be viewed [here](https://github.com/gazebosim/ros_gz/pull/620#issue-2595570189) + +More info about `ros_gz_bridge` can be viewed [here](ros2_integration). +More info about composition can be viewed [here](ros2_overview.md#composition). diff --git a/ionic/ros2_overview.md b/ionic/ros2_overview.md index a5d8ab62b..1bb52fc4d 100644 --- a/ionic/ros2_overview.md +++ b/ionic/ros2_overview.md @@ -26,18 +26,56 @@ 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. +Important: Most of this functionality is only available in ROS 2 Rolling. +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. - -You can learn more about ROS composition in [this tutorial](https://docs.ros.org/en/galactic/Tutorials/Intermediate/Composition.html). +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 you 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 using the bridge. +The center diagram represents the scenario where we can use composition with a ROS container created by a `ros_gz` launch file containing both Gazebo and the bridge, and an additional +consumer node outside that we cannot control. All communication between Gazebo +and the bridge is intraprocess and interprocess between the external consumer +node and the bridge. +The diagram on the right side is using composition across all nodes but the +`ros_gz` launch file doesn't start its own container directly. This setup by itself will +not work until you start an external ROS container (manually or via a separate launch file). In this diagram, the external ROS consumer node starts the +container. We're using the Nav2 logo as an example of external ROS 2 consumer +node. + +You can learn more about ROS composition in [this tutorial](https://docs.ros.org/en/jazzy/Tutorials/Intermediate/Composition.html). + +## What's next? + +Here are the next follow-up tutorials that you can check to learn more about +Gazebo/ROS integration. + +* [How to launch Gazebo from ROS 2](ros2_launch_gazebo). +* [How to use ROS 2 to interact with Gazebo](ros2_integration). +* [Example of using ROS 2 to load a model and interact with it in Gazebo](ros2_interop). +* [How to spawn a Gazebo model from ROS 2](ros2_spawn_model). diff --git a/ionic/ros2_spawn_model.md b/ionic/ros2_spawn_model.md index 52040ed5e..d68cc3f2c 100644 --- a/ionic/ros2_spawn_model.md +++ b/ionic/ros2_spawn_model.md @@ -5,13 +5,14 @@ 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`. +*Currently only available in Rolling.* 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 +`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 +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 entity_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) @@ -29,9 +30,9 @@ within this tag. Here's an example: - + - + @@ -42,9 +43,9 @@ within this tag. Here's an example: ` 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 of the parameters. + + +## Spawning a model alongside launching ros_gz_bridge + +An example launch file for XML can be viewed [here](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_sim/launch/ros_gz_spawn_model.launch) +An example launch file for Python can be viewed [here](https://github.com/gazebosim/ros_gz/blob/jazzy/ros_gz_sim/launch/ros_gz_spawn_model.launch.py) + +Example command for directly using these launch files from the terminal: +```bash +ros2 launch ros_gz_sim ros_gz_spawn_model.launch.py world:=empty file:=$(ros2 pkg prefix --share ros_gz_sim_demos)/models/vehicle/model.sdf entity_name:=my_vehicle x:=5.0 y:=5.0 z:=0.5 bridge_name:=ros_gz_bridge config_file:= +``` + +More info about `ros_gz_bridge` can be viewed [here](ros2_integration).