From e945ae92fe56dd2161bcb30049394876d102c9a5 Mon Sep 17 00:00:00 2001 From: Sai Kishor Kothakota Date: Thu, 19 Dec 2024 17:18:00 +0100 Subject: [PATCH 1/4] Add asynchronous hardware components documentation --- .../doc/asynchronous_components.rst | 88 +++++++++++++++++++ .../doc/hardware_components_userdoc.rst | 1 + 2 files changed, 89 insertions(+) create mode 100644 hardware_interface/doc/asynchronous_components.rst diff --git a/hardware_interface/doc/asynchronous_components.rst b/hardware_interface/doc/asynchronous_components.rst new file mode 100644 index 0000000000..c1a48c8401 --- /dev/null +++ b/hardware_interface/doc/asynchronous_components.rst @@ -0,0 +1,88 @@ +:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/different_update_rates_userdoc.rst + +.. _asynchronous_components: + +Running Hardware Components Asynchronously +============================================ + +The ``ros2_control`` framework allows to run hardware components asynchronously. This is useful when some of the hardware components need to run in a separate thread or executor. For example, a sensor takes longer to read data that affects the periodicity of the ``controller_manager`` control loop. In this case, the sensor can be run in a separate thread or executor to avoid blocking the control loop. + + +Examples +*********** + +The following examples show how to use the different hardware interface types synchronously and asynchronously with ``ros2_control`` URDF. +They can be combined together within the different hardware component types (system, actuator, sensor) (:ref:`see detailed documentation `) as follows + +For a RRBot with Multimodal gripper and external sensor: + +.. code-block:: xml + + + + ros2_control_demo_hardware/RRBotSystemPositionOnlyHardware + 2.0 + 3.0 + 2.0 + + + + -1 + 1 + + + + + + -1 + 1 + + + + + + + + + + + + + + + ros2_control_demo_hardware/MultimodalGripper + + + + 0 + 100 + + + + + + + ros2_control_demo_hardware/ForceTorqueSensor2DHardware + 0.43 + + + + + kuka_tcp + 100 + 100 + + + + + + + + + + +In the above example, the following components are defined: + +* A system hardware component named ``RRBotSystemMutipleGPIOs`` with two joints and a GPIO component that runs synchronously. +* An actuator hardware component named ``MultimodalGripper`` with a joint that runs asynchronously with a thread priority of 30. +* A sensor hardware component named ``RRBotForceTorqueSensor2D`` with two sensors and a GPIO component that runs asynchronously with the default thread priority of 50. diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst index 0a980cad4e..3870433ef0 100644 --- a/hardware_interface/doc/hardware_components_userdoc.rst +++ b/hardware_interface/doc/hardware_components_userdoc.rst @@ -17,6 +17,7 @@ Guidelines and Best Practices Hardware Interface Types Writing a Hardware Component Different Update Rates + Asynchronous Execution Handling of errors that happen during read() and write() calls From 250c02d99ecb344f30e720c4371699b647ba727c Mon Sep 17 00:00:00 2001 From: Sai Kishor Kothakota Date: Fri, 20 Dec 2024 13:26:27 +0100 Subject: [PATCH 2/4] Update hardware_interface/doc/asynchronous_components.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christoph Fröhlich --- hardware_interface/doc/asynchronous_components.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hardware_interface/doc/asynchronous_components.rst b/hardware_interface/doc/asynchronous_components.rst index c1a48c8401..fe3bdbfd0a 100644 --- a/hardware_interface/doc/asynchronous_components.rst +++ b/hardware_interface/doc/asynchronous_components.rst @@ -14,7 +14,7 @@ Examples The following examples show how to use the different hardware interface types synchronously and asynchronously with ``ros2_control`` URDF. They can be combined together within the different hardware component types (system, actuator, sensor) (:ref:`see detailed documentation `) as follows -For a RRBot with Multimodal gripper and external sensor: +For a RRBot with multimodal gripper and external sensor: .. code-block:: xml From 11b1da173ecaa8ab1dbe0d82c8b3be58078244a1 Mon Sep 17 00:00:00 2001 From: Sai Kishor Kothakota Date: Fri, 20 Dec 2024 13:32:28 +0100 Subject: [PATCH 3/4] Update documentation as per suggestions + release_notes --- doc/release_notes.rst | 1 + hardware_interface/doc/asynchronous_components.rst | 13 ++++++++++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/doc/release_notes.rst b/doc/release_notes.rst index 69c282b051..9c5eb64e18 100644 --- a/doc/release_notes.rst +++ b/doc/release_notes.rst @@ -158,6 +158,7 @@ hardware_interface * With (`#1421 `_) a key-value storage is added to InterfaceInfo. This allows to define extra params with per Command-/StateInterface in the ``.ros2_control.xacro`` file. * With (`#1763 `_) parsing for SDF published to ``robot_description`` topic is now also supported. * With (`#1567 `_) all the Hardware components now have a fully functional asynchronous functionality, by simply adding ``is_async`` tag to the ros2_control tag in the URDF. This will allow the hardware components to run in a separate thread, and the controller manager will be able to run the controllers in parallel with the hardware components. +* Add documentation for asynchronous hardware components (`#1961 `_) joint_limits ************ diff --git a/hardware_interface/doc/asynchronous_components.rst b/hardware_interface/doc/asynchronous_components.rst index fe3bdbfd0a..c73281c3fe 100644 --- a/hardware_interface/doc/asynchronous_components.rst +++ b/hardware_interface/doc/asynchronous_components.rst @@ -7,9 +7,20 @@ Running Hardware Components Asynchronously The ``ros2_control`` framework allows to run hardware components asynchronously. This is useful when some of the hardware components need to run in a separate thread or executor. For example, a sensor takes longer to read data that affects the periodicity of the ``controller_manager`` control loop. In this case, the sensor can be run in a separate thread or executor to avoid blocking the control loop. +Parameters +----------- + +The following parameters can be set in the ``ros2_control`` hardware configuration to run the hardware component asynchronously: + +* ``is_async``: (optional) If set to ``true``, the hardware component will run asynchronously. Default is ``false``. +* ``thread_priority``: (optional) The priority of the thread that runs the hardware component. The priority is an integer value between 0 and 99. The default value is 50. + +.. note:: + The thread priority is only used when the hardware component is run asynchronously. + When the hardware component is run asynchronously, it uses the FIFO scheduling policy. Examples -*********** +--------- The following examples show how to use the different hardware interface types synchronously and asynchronously with ``ros2_control`` URDF. They can be combined together within the different hardware component types (system, actuator, sensor) (:ref:`see detailed documentation `) as follows From b11062cc42e6d8388d23ee7f3f74cb2c2f77651d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Fr=C3=B6hlich?= Date: Fri, 20 Dec 2024 21:37:39 +0100 Subject: [PATCH 4/4] Update doc/release_notes.rst --- doc/release_notes.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/release_notes.rst b/doc/release_notes.rst index 9c5eb64e18..69c282b051 100644 --- a/doc/release_notes.rst +++ b/doc/release_notes.rst @@ -158,7 +158,6 @@ hardware_interface * With (`#1421 `_) a key-value storage is added to InterfaceInfo. This allows to define extra params with per Command-/StateInterface in the ``.ros2_control.xacro`` file. * With (`#1763 `_) parsing for SDF published to ``robot_description`` topic is now also supported. * With (`#1567 `_) all the Hardware components now have a fully functional asynchronous functionality, by simply adding ``is_async`` tag to the ros2_control tag in the URDF. This will allow the hardware components to run in a separate thread, and the controller manager will be able to run the controllers in parallel with the hardware components. -* Add documentation for asynchronous hardware components (`#1961 `_) joint_limits ************