From 69be724886c80005d2c30c167a00bb4337e43c04 Mon Sep 17 00:00:00 2001 From: Yannick Goumaz <61198661+ygoumaz@users.noreply.github.com> Date: Wed, 26 Jul 2023 18:24:49 +0200 Subject: [PATCH] Enhancement Add Ros2Supervisor tutorial (#3790) * Sync fork (#17) * Update launch files to declare WebotsController node (#11) (#3763) * change launch files * Update Setting-Up-Simulation-Webots-Basic.rst * update minimal version tutorial 2 * add upcoming versions * New Reset Handler tutorial (#12) (#3764) * new tutorial Co-authored-by: Olivier Michel * Update macOS-Development-Setup.rst (#3758) - add Xcode App Store link - BASH -> ZSH (default) - make homebrew paths generic Co-authored-by: Philipp Dittmann * Change confusing title between Debian package and Debian platform (#3771) Currently Debian does not offer ROS2 packages. Change the title that can be confusing. * Make the calendar more mobile-friendly. (#3774) * Make the calendar more mobile-friendly. When looking at some of the analytics, it looks like this page is particularly not mobile friendly. That's because the Google calendar embedded on the bottom of the page is of fixed with 800x600, which doesn't work well on many mobile devices. What we do here is to see if a device has 767 or less pixels. If it does, then we just show the agenda, which fits in just 280 pixels. If we have more than that, we have room for the full monthly agenda, so we show the full thing. Signed-off-by: Chris Lalancette Co-authored-by: Tomoya Fujita --------- Signed-off-by: Chris Lalancette Co-authored-by: Olivier Michel Co-authored-by: PhDittmann Co-authored-by: Philipp Dittmann Co-authored-by: Quentin Quadrat Co-authored-by: Chris Lalancette Co-authored-by: Tomoya Fujita * add new tutorial * Update source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst Co-authored-by: Olivier Michel * Update source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst Co-authored-by: Olivier Michel * Update source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst Co-authored-by: Olivier Michel * add new tutorial * Update source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst Co-authored-by: Olivier Michel * Update source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst Co-authored-by: Olivier Michel * Update source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst Co-authored-by: Olivier Michel * Update Simulation-Supervisor.rst * minor --------- Signed-off-by: Chris Lalancette Co-authored-by: Olivier Michel Co-authored-by: PhDittmann Co-authored-by: Philipp Dittmann Co-authored-by: Quentin Quadrat Co-authored-by: Chris Lalancette Co-authored-by: Tomoya Fujita --- .../Webots/Simulation-Supervisor.rst | 144 ++++++++++++++++++ .../Simulators/Webots/Simulation-Webots.rst | 1 + 2 files changed, 145 insertions(+) create mode 100644 source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst diff --git a/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst b/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst new file mode 100644 index 00000000000..d16b4980b6e --- /dev/null +++ b/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst @@ -0,0 +1,144 @@ +The Ros2Supervisor Node +======================= + +**Goal:** Extend the interface with a default Supervisor robot, named ``Ros2Supervisor``. + +**Tutorial level:** Advanced + +**Time:** 10 minutes + +.. contents:: Contents + :depth: 2 + :local: + +Background +---------- + +In this tutorial, you will learn how to enable the ``Ros2Supervisor`` node which enhances the interface by creating additional services and topics to interact with the simulation. +You can, for example, record animations or spawn Webots nodes directly from the ROS 2 interface while the simulation is running. +These instructions list in details the current implemented features and how to use them. + +Prerequisites +------------- + +Before proceeding with this tutorial, make sure you have completed the following: + +- Understanding of ROS 2 nodes and topics covered in the beginner :doc:`../../../../Tutorials`. +- Knowledge of Webots and ROS 2 and its interface package. +- Familiarity with :doc:`./Setting-Up-Simulation-Webots-Basic`. + +The ``Ros2Supervisor`` +---------------------- + +The ``Ros2Supervisor`` is made of two main parts: + +* A Webots Robot node added to the simulation world. Its ``supervisor`` field is set to TRUE. +* A ROS 2 node that connects to the Webots Robot as an extern controller (in a similar way to your own robot plugin). + +The ROS 2 node acts as a controller that calls Supervisor API functions to control or interact with the simulation world. +User interactions with the ROS 2 node are mainly performed through services and topics. + +These nodes can be automatically created at the Webots launch using the ``ros2_supervisor`` parameter in the ``WebotsLauncher``. + +.. code-block:: python + + webots = WebotsLauncher( + world=PathJoinSubstitution([package_dir, 'worlds', world]), + mode=mode, + ros2_supervisor=True + ) + +The ``webots._supervisor`` object must also be included in the ``LaunchDescription`` returned by the launch file. + +.. code-block:: python + + return LaunchDescription([ + webots, + webots._supervisor, + + # This action will kill all nodes once the Webots simulation has exited + launch.actions.RegisterEventHandler( + event_handler=launch.event_handlers.OnProcessExit( + target_action=webots, + on_exit=[ + launch.actions.EmitEvent(event=launch.events.Shutdown()) + ], + ) + ) + ]) + +More information about launch files for ``webots_ros2`` projects can be found in :doc:`./Setting-Up-Simulation-Webots-Basic`. + +Clock topic +----------- + +The ``Ros2Supervisor`` node is responsible to get the time of the Webots simulation and publish it to the ``/clock`` topic. +This means that it is mandatory to spawn the ``Ros2Supervisor`` if some other nodes have their ``use_sim_time`` parameter set to ``true``. +More information about the ``/clock`` topic can be found in the `ROS wiki `_. + +Import a Webots node +-------------------- + +The ``Ros2Supervisor`` node also allows you to spawn Webots nodes from strings through a service. + +The service is named ``/Ros2Supervisor/spawn_node_from_string`` and is of type ``webots_ros2_msgs/srv/SpawnNodeFromString``. +The ``SpawnNodeFromString`` type expects a ``data`` string as input and returns a ``success`` boolean. + +From the given string, the Supervisor node is getting the name of the imported node and adding it to an intern list for potential later removal (see :ref:`Remove a Webots imported node`). + +The node is imported using the ``importMFNodeFromString(nodeString)`` `API function `_. + +Here is an example to import a simple Robot named ``imported_robot``: + +.. code-block:: bash + + ros2 service call /Ros2Supervisor/spawn_node_from_string webots_ros2_msgs/srv/SpawnNodeFromString "data: Robot { name \"imported_robot\" }" + +.. note:: + If you try to import some PROTOs in the node string, their respective URLs must be declared in the .wbt world file as EXTERNPROTO or as IMPORTABLE EXTERNPROTO. + +.. _Remove a Webots imported node: + +Remove a Webots imported node +----------------------------- + +Once a node has been imported with the ``/Ros2Supervisor/spawn_node_from_string`` service, it can also be removed. + +This can be achieved by sending the name of the node to the topic named ``/Ros2Supervisor/remove_node`` of type ``std_msgs/msg/String``. + +If the node is indeed in the imported list, it is removed with the ``remove()`` `API method `_. + +Here is an example on how to remove the ``imported_robot`` Robot: + +.. code-block:: bash + + ros2 topic pub --once /Ros2Supervisor/remove_node std_msgs/msg/String "{data: imported_robot}" + +Record animations +----------------- + +The ``Ros2Supervisor`` node also creates two additional services to record HTML5 animations. + +The ``/Ros2Supervisor/animation_start_recording`` service is of type ``webots_ros2_msgs/srv/SetString`` and allows to start the animation. +The ``SetString`` type expects a ``value`` string as input and returns a ``success`` boolean. +The input ``value`` represents the absolute path to the directory where the animations files should be saved. + +Here is an example on how to start an animation: + +.. code-block:: bash + + ros2 service call /Ros2Supervisor/animation_start_recording webots_ros2_msgs/srv/SetString "{value: "/index.html"}" + + +The ``/Ros2Supervisor/animation_stop_recording`` service is of type ``webots_ros2_msgs/srv/GetBool`` and allows to stop the animation. + +.. code-block:: bash + + ros2 service call /Ros2Supervisor/animation_stop_recording webots_ros2_msgs/srv/GetBool "{ask: True}" + + +Summary +------- + +In this tutorial, you learned how to enable the ``Ros2Supervisor`` and how to extend the interface with the Webots simulation. +The node creates multiple services and topics to interact with and modify the simulation. diff --git a/source/Tutorials/Advanced/Simulators/Webots/Simulation-Webots.rst b/source/Tutorials/Advanced/Simulators/Webots/Simulation-Webots.rst index cff39992de6..6120e8b1456 100644 --- a/source/Tutorials/Advanced/Simulators/Webots/Simulation-Webots.rst +++ b/source/Tutorials/Advanced/Simulators/Webots/Simulation-Webots.rst @@ -16,3 +16,4 @@ This set of tutorials will teach you how to configure the Webots simulator with Setting-Up-Simulation-Webots-Basic Setting-Up-Simulation-Webots-Advanced Simulation-Reset-Handler + Simulation-Supervisor