From c1647f3ae2c526183a32190f73472a7d78541bc3 Mon Sep 17 00:00:00 2001 From: Christoph Froehlich Date: Fri, 28 Feb 2025 21:33:47 +0000 Subject: [PATCH 1/6] Fix docstrings --- .../include/hardware_interface/actuator_interface.hpp | 9 ++++++--- .../include/hardware_interface/sensor_interface.hpp | 8 ++------ .../include/hardware_interface/system_interface.hpp | 9 ++++++--- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/hardware_interface/include/hardware_interface/actuator_interface.hpp b/hardware_interface/include/hardware_interface/actuator_interface.hpp index 1f693d1d34..37709ad28e 100644 --- a/hardware_interface/include/hardware_interface/actuator_interface.hpp +++ b/hardware_interface/include/hardware_interface/actuator_interface.hpp @@ -61,9 +61,12 @@ namespace hardware_interface * * INACTIVE (on_configure, on_deactivate): * Communication with the hardware is started and it is configured. - * States can be read and non-movement hardware interfaces commanded. - * Hardware interfaces for movement will NOT be available. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. + * States can be read and command interfaces are available. + * + * TODO(anyone): Implement https://github.com/ros-controls/ros2_control/issues/931 + * States can be read and non-movement hardware interfaces commanded. + * Hardware interfaces for movement will NOT be available. + * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. diff --git a/hardware_interface/include/hardware_interface/sensor_interface.hpp b/hardware_interface/include/hardware_interface/sensor_interface.hpp index 58a8b4790a..dd23368470 100644 --- a/hardware_interface/include/hardware_interface/sensor_interface.hpp +++ b/hardware_interface/include/hardware_interface/sensor_interface.hpp @@ -60,18 +60,14 @@ namespace hardware_interface * * INACTIVE (on_configure, on_deactivate): * Communication with the hardware is started and it is configured. - * States can be read and non-movement hardware interfaces commanded. - * Hardware interfaces for movement will NOT be available. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. + * States can be read. * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. * Allocated memory is cleaned up. * * ACTIVE (on_activate): - * Power circuits of hardware are active and hardware can be moved, e.g., brakes are disabled. - * Command interfaces for movement are available and have to be accepted. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. + * States can be read. */ using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; diff --git a/hardware_interface/include/hardware_interface/system_interface.hpp b/hardware_interface/include/hardware_interface/system_interface.hpp index 7577d0ebdc..5364d0c42f 100644 --- a/hardware_interface/include/hardware_interface/system_interface.hpp +++ b/hardware_interface/include/hardware_interface/system_interface.hpp @@ -64,9 +64,12 @@ namespace hardware_interface * * INACTIVE (on_configure, on_deactivate): * Communication with the hardware is started and it is configured. - * States can be read and non-movement hardware interfaces commanded. - * Hardware interfaces for movement will NOT be available. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. + * States can be read and command interfaces are available. + * + * TODO(anyone): Implement https://github.com/ros-controls/ros2_control/issues/931 + * States can be read and non-movement hardware interfaces commanded. + * Hardware interfaces for movement will NOT be available. + * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. From dfb320765b8a1e2b690ad80a9b383c3b50fcdc94 Mon Sep 17 00:00:00 2001 From: Christoph Froehlich Date: Fri, 28 Feb 2025 21:35:19 +0000 Subject: [PATCH 2/6] Improve hardware lifecycle description --- .../doc/hardware_components_userdoc.rst | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst index 6b6d40914b..7f382e460d 100644 --- a/hardware_interface/doc/hardware_components_userdoc.rst +++ b/hardware_interface/doc/hardware_components_userdoc.rst @@ -21,6 +21,48 @@ Guidelines and Best Practices Semantic Components +Lifecycle of a Hardware Component +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Methods return values have type +``rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn`` with the following +meaning: + +* ``CallbackReturn::SUCCESS`` method execution was successful. +* ``CallbackReturn::FAILURE`` method execution has failed and can be called again. +* ``CallbackReturn::ERROR`` critical error has happened that should be managed in + ``on_error`` method. + +The hardware ends after each method in a state with the following meaning: + +* **UNCONFIGURED** (on_init, on_cleanup): + + Hardware is initialized but communication is not started and therefore no interface is + available. + +* **INACTIVE** (on_configure, on_deactivate): + + Communication with the hardware is started and it is configured. + States can be read and command interfaces (System and Actuator only) are available. + + .. note:: + + We plan to implement safety-critical interfaces, see this `PR in the roadmap `__. But currently, all command interfaces are available and will be written, see this `issue `__ describing the situation. + +* **FINALIZED** (on_shutdown): + + Hardware interface is ready for unloading/destruction. + Allocated memory is cleaned up. + +* **ACTIVE** (on_activate): + + States can be read. + + System and Actuator only: + + Power circuits of hardware are active and hardware can be moved, e.g., brakes are disabled. + Command interfaces are available and have to be accepted. + + Handling of errors that happen during read() and write() calls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 2e53de7f73b1c0282a96c11f6f1325e317cf7544 Mon Sep 17 00:00:00 2001 From: Christoph Froehlich Date: Fri, 28 Feb 2025 21:52:59 +0000 Subject: [PATCH 3/6] Fix doxygen syntax --- .../hardware_interface/actuator_interface.hpp | 23 +++++++++------ .../hardware_interface/sensor_interface.hpp | 6 ++-- .../hardware_interface/system_interface.hpp | 28 +++++++++++-------- 3 files changed, 34 insertions(+), 23 deletions(-) diff --git a/hardware_interface/include/hardware_interface/actuator_interface.hpp b/hardware_interface/include/hardware_interface/actuator_interface.hpp index 37709ad28e..75f57ac650 100644 --- a/hardware_interface/include/hardware_interface/actuator_interface.hpp +++ b/hardware_interface/include/hardware_interface/actuator_interface.hpp @@ -40,6 +40,9 @@ namespace hardware_interface { + +using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; + /// Virtual Class to implement when integrating a 1 DoF actuator into ros2_control. /** * The typical examples are conveyors or motors. @@ -63,23 +66,25 @@ namespace hardware_interface * Communication with the hardware is started and it is configured. * States can be read and command interfaces are available. * - * TODO(anyone): Implement https://github.com/ros-controls/ros2_control/issues/931 - * States can be read and non-movement hardware interfaces commanded. - * Hardware interfaces for movement will NOT be available. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. - * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. * Allocated memory is cleaned up. * * ACTIVE (on_activate): * Power circuits of hardware are active and hardware can be moved, e.g., brakes are disabled. - * Command interfaces for movement are available and have to be accepted. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. + * Command interfaces available. + * + * \todo + * Implement + * * https://github.com/ros-controls/ros2_control/issues/931 + * * https://github.com/ros-controls/roadmap/pull/51/files + * * this means in INACTIVE state: + * * States can be read and non-movement hardware interfaces commanded. + * * Hardware interfaces for movement will NOT be available. + * * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and + * HW_IF_EFFORT. */ -using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; - class ActuatorInterface : public rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface { public: diff --git a/hardware_interface/include/hardware_interface/sensor_interface.hpp b/hardware_interface/include/hardware_interface/sensor_interface.hpp index dd23368470..1d9c2baf23 100644 --- a/hardware_interface/include/hardware_interface/sensor_interface.hpp +++ b/hardware_interface/include/hardware_interface/sensor_interface.hpp @@ -39,6 +39,9 @@ namespace hardware_interface { + +using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; + /// Virtual Class to implement when integrating a stand-alone sensor into ros2_control. /** * The typical examples are Force-Torque Sensor (FTS), Interial Measurement Unit (IMU). @@ -69,9 +72,6 @@ namespace hardware_interface * ACTIVE (on_activate): * States can be read. */ - -using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; - class SensorInterface : public rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface { public: diff --git a/hardware_interface/include/hardware_interface/system_interface.hpp b/hardware_interface/include/hardware_interface/system_interface.hpp index 5364d0c42f..601d4ff850 100644 --- a/hardware_interface/include/hardware_interface/system_interface.hpp +++ b/hardware_interface/include/hardware_interface/system_interface.hpp @@ -42,8 +42,12 @@ namespace hardware_interface { -/// Virtual Class to implement when integrating a complex system into ros2_control. + +using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; + /** + * @brief Virtual Class to implement when integrating a complex system into ros2_control. + * * The common examples for these types of hardware are multi-joint systems with or without sensors * such as industrial or humanoid robots. * @@ -60,29 +64,31 @@ namespace hardware_interface * * UNCONFIGURED (on_init, on_cleanup): * Hardware is initialized but communication is not started and therefore no interface is - * available. + *available. * * INACTIVE (on_configure, on_deactivate): * Communication with the hardware is started and it is configured. * States can be read and command interfaces are available. * - * TODO(anyone): Implement https://github.com/ros-controls/ros2_control/issues/931 - * States can be read and non-movement hardware interfaces commanded. - * Hardware interfaces for movement will NOT be available. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. - * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. * Allocated memory is cleaned up. * * ACTIVE (on_activate): * Power circuits of hardware are active and hardware can be moved, e.g., brakes are disabled. - * Command interfaces for movement are available and have to be accepted. - * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and HW_IF_EFFORT. + * Command interfaces available. + * + * \todo + * Implement + * * https://github.com/ros-controls/ros2_control/issues/931 + * * https://github.com/ros-controls/roadmap/pull/51/files + * * this means in INACTIVE state: + * * States can be read and non-movement hardware interfaces commanded. + * * Hardware interfaces for movement will NOT be available. + * * Those interfaces are: HW_IF_POSITION, HW_IF_VELOCITY, HW_IF_ACCELERATION, and + *HW_IF_EFFORT. */ -using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn; - class SystemInterface : public rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface { public: From 72fae56eccf76882bd4d6175e838ee2c7ec05326 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Fr=C3=B6hlich?= Date: Sat, 1 Mar 2025 14:33:50 +0100 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Sai Kishor Kothakota --- .../doc/hardware_components_userdoc.rst | 23 ++++++++++--------- .../hardware_interface/actuator_interface.hpp | 2 ++ .../hardware_interface/system_interface.hpp | 2 ++ 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst index 7f382e460d..646fcc6467 100644 --- a/hardware_interface/doc/hardware_components_userdoc.rst +++ b/hardware_interface/doc/hardware_components_userdoc.rst @@ -28,39 +28,40 @@ Methods return values have type meaning: * ``CallbackReturn::SUCCESS`` method execution was successful. -* ``CallbackReturn::FAILURE`` method execution has failed and can be called again. +* ``CallbackReturn::FAILURE`` method execution has failed and the lifecycle transition is unsuccessful. * ``CallbackReturn::ERROR`` critical error has happened that should be managed in ``on_error`` method. -The hardware ends after each method in a state with the following meaning: +The hardware transitions to the following state after each method: -* **UNCONFIGURED** (on_init, on_cleanup): +* **UNCONFIGURED** (``on_init``, ``on_cleanup``): - Hardware is initialized but communication is not started and therefore no interface is - available. + Hardware is only initialized, but communication is not started and no interfaces are imported into ``ResourceManager``. -* **INACTIVE** (on_configure, on_deactivate): +* **INACTIVE** (``on_configure``, ``on_deactivate``): - Communication with the hardware is started and it is configured. + Communication with the hardware is established and hardware component is configured. States can be read and command interfaces (System and Actuator only) are available. + + As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. .. note:: We plan to implement safety-critical interfaces, see this `PR in the roadmap `__. But currently, all command interfaces are available and will be written, see this `issue `__ describing the situation. -* **FINALIZED** (on_shutdown): +* **FINALIZED** (``on_shutdown``): Hardware interface is ready for unloading/destruction. Allocated memory is cleaned up. -* **ACTIVE** (on_activate): +* **ACTIVE** (``on_activate``): States can be read. System and Actuator only: - Power circuits of hardware are active and hardware can be moved, e.g., brakes are disabled. - Command interfaces are available and have to be accepted. + Power circuits of hardware are active and hardware can be moved, e.g., brakes are disengaged. + Command interfaces are available and the commands should be sent to the hardware Handling of errors that happen during read() and write() calls diff --git a/hardware_interface/include/hardware_interface/actuator_interface.hpp b/hardware_interface/include/hardware_interface/actuator_interface.hpp index 75f57ac650..66235e4e5b 100644 --- a/hardware_interface/include/hardware_interface/actuator_interface.hpp +++ b/hardware_interface/include/hardware_interface/actuator_interface.hpp @@ -66,6 +66,8 @@ using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface * Communication with the hardware is started and it is configured. * States can be read and command interfaces are available. * + * As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. + * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. * Allocated memory is cleaned up. diff --git a/hardware_interface/include/hardware_interface/system_interface.hpp b/hardware_interface/include/hardware_interface/system_interface.hpp index 601d4ff850..e885f02366 100644 --- a/hardware_interface/include/hardware_interface/system_interface.hpp +++ b/hardware_interface/include/hardware_interface/system_interface.hpp @@ -70,6 +70,8 @@ using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface * Communication with the hardware is started and it is configured. * States can be read and command interfaces are available. * + * As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. + * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. * Allocated memory is cleaned up. From e7bb046793c5bc31681d17e978e8034ba3e9f121 Mon Sep 17 00:00:00 2001 From: Christoph Froehlich Date: Sat, 1 Mar 2025 13:39:01 +0000 Subject: [PATCH 5/6] Fix pre-commit --- .../include/hardware_interface/actuator_interface.hpp | 3 ++- .../include/hardware_interface/system_interface.hpp | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/hardware_interface/include/hardware_interface/actuator_interface.hpp b/hardware_interface/include/hardware_interface/actuator_interface.hpp index 0a64bd01da..e4cf083063 100644 --- a/hardware_interface/include/hardware_interface/actuator_interface.hpp +++ b/hardware_interface/include/hardware_interface/actuator_interface.hpp @@ -66,7 +66,8 @@ using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface * Communication with the hardware is started and it is configured. * States can be read and command interfaces are available. * - * As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. + * As of now, it is left to the hardware component implementation to continue using the command + * received from the ``CommandInterfaces`` or to skip them completely. * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. diff --git a/hardware_interface/include/hardware_interface/system_interface.hpp b/hardware_interface/include/hardware_interface/system_interface.hpp index b45d34f64b..d4d2505849 100644 --- a/hardware_interface/include/hardware_interface/system_interface.hpp +++ b/hardware_interface/include/hardware_interface/system_interface.hpp @@ -70,7 +70,8 @@ using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface * Communication with the hardware is started and it is configured. * States can be read and command interfaces are available. * - * As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. + * As of now, it is left to the hardware component implementation to continue using the command + *received from the ``CommandInterfaces`` or to skip them completely. * * FINALIZED (on_shutdown): * Hardware interface is ready for unloading/destruction. From cf730d075abdd08561f67ec94db5d9a03b760112 Mon Sep 17 00:00:00 2001 From: Christoph Froehlich Date: Sat, 1 Mar 2025 13:44:27 +0000 Subject: [PATCH 6/6] Fix whitespaces --- hardware_interface/doc/hardware_components_userdoc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst index 646fcc6467..05e99e2197 100644 --- a/hardware_interface/doc/hardware_components_userdoc.rst +++ b/hardware_interface/doc/hardware_components_userdoc.rst @@ -42,8 +42,8 @@ The hardware transitions to the following state after each method: Communication with the hardware is established and hardware component is configured. States can be read and command interfaces (System and Actuator only) are available. - - As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. + + As of now, it is left to the hardware component implementation to continue using the command received from the ``CommandInterfaces`` or to skip them completely. .. note::