diff --git a/harmonic/index.yaml b/harmonic/index.yaml index 809cecdce..58c07534c 100644 --- a/harmonic/index.yaml +++ b/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 diff --git a/harmonic/ros2_integration.md b/harmonic/ros2_integration.md index b31a9f253..f4330cd29 100644 --- a/harmonic/ros2_integration.md +++ b/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:= +``` + +## 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 `` 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 + + + + + + + + + + + +``` + +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. + ## Publish key strokes to ROS Let's send messages to ROS using the `Key Publisher` an Gazebo plugin. diff --git a/harmonic/ros2_launch_gazebo.md b/harmonic/ros2_launch_gazebo.md new file mode 100644 index 000000000..096c8625e --- /dev/null +++ b/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 `` 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 + + + + + + + + +``` + +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. diff --git a/harmonic/ros2_overview.md b/harmonic/ros2_overview.md new file mode 100644 index 000000000..e89954970 --- /dev/null +++ b/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). diff --git a/harmonic/ros2_spawn_model.md b/harmonic/ros2_spawn_model.md new file mode 100644 index 000000000..52040ed5e --- /dev/null +++ b/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 `` 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 + + + + + + + + + + + + + + + + +``` + +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.