diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst index 6b6d40914b..05e99e2197 100644 --- a/hardware_interface/doc/hardware_components_userdoc.rst +++ b/hardware_interface/doc/hardware_components_userdoc.rst @@ -21,6 +21,49 @@ 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 the lifecycle transition is unsuccessful. +* ``CallbackReturn::ERROR`` critical error has happened that should be managed in + ``on_error`` method. + +The hardware transitions to the following state after each method: + +* **UNCONFIGURED** (``on_init``, ``on_cleanup``): + + Hardware is only initialized, but communication is not started and no interfaces are imported into ``ResourceManager``. + +* **INACTIVE** (``on_configure``, ``on_deactivate``): + + 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``): + + 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 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 871b575b4c..e4cf083063 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. @@ -61,9 +64,10 @@ 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. + * + * 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. @@ -71,12 +75,19 @@ namespace hardware_interface * * 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 f117e6a7d5..44a22049ee 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). @@ -60,22 +63,15 @@ 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; - 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 a448069126..d4d2505849 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,13 +64,14 @@ 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 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. + * + * 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. @@ -74,12 +79,19 @@ namespace hardware_interface * * 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: