Remodel component interfaces (#203)

* introducing handles
* component interfaces & tests

Signed-off-by: Karsten Knese <[email protected]>
Co-authored-by: Bence Magyar <[email protected]>
Co-authored-by: Denis Štogl <[email protected]>

Author: 3 people

hardware_interface/CMakeLists.txt

@@ -103,6 +103,9 @@ if(BUILD_TESTING)
   target_link_libraries(test_joint_handle hardware_interface)
   ament_target_dependencies(test_joint_handle rcpputils)
 
+  ament_add_gmock(test_component_interfaces test/test_component_interfaces.cpp)
+  target_link_libraries(test_component_interfaces hardware_interface)
+
   ament_add_gmock(test_component_parser test/test_component_parser.cpp)
   target_link_libraries(test_component_parser component_parser)
   ament_target_dependencies(test_component_parser TinyXML2)

hardware_interface/include/hardware_interface/actuator_handle.hpp

@@ -18,22 +18,14 @@
 #include <string>
 
 #include "hardware_interface/handle.hpp"
-#include "hardware_interface/macros.hpp"
-#include "hardware_interface/visibility_control.h"
 
 namespace hardware_interface
 {
 /** A handle used to get and set a value on a given actuator interface. */
-class ActuatorHandle : public Handle<ActuatorHandle>
+class ActuatorHandle : public ReadWriteHandle<ActuatorHandle>
 {
 public:
-  HARDWARE_INTERFACE_PUBLIC
-  ActuatorHandle(
-    const std::string & name, const std::string & interface_name,
-    double * value_ptr = nullptr)
-  : Handle(name, interface_name, value_ptr)
-  {
-  }
+  using ReadWriteHandle<ActuatorHandle>::ReadWriteHandle;
 };
 
 }  // namespace hardware_interface

hardware_interface/include/hardware_interface/components/actuator.hpp

@@ -16,7 +16,9 @@
 #define HARDWARE_INTERFACE__COMPONENTS__ACTUATOR_HPP_
 
 #include <memory>
+#include <vector>
 
+#include "hardware_interface/handle.hpp"
 #include "hardware_interface/hardware_info.hpp"
 #include "hardware_interface/types/hardware_interface_return_values.hpp"
 #include "hardware_interface/types/hardware_interface_status_values.hpp"
@@ -34,18 +36,35 @@ class Actuator final
 public:
   Actuator() = default;
 
+  HARDWARE_INTERFACE_PUBLIC
   explicit Actuator(std::unique_ptr<ActuatorInterface> impl);
 
   ~Actuator() = default;
 
+  HARDWARE_INTERFACE_PUBLIC
   return_type configure(const HardwareInfo & actuator_info);
 
+  HARDWARE_INTERFACE_PUBLIC
+  std::vector<StateHandle> export_state_handles();
+
+  HARDWARE_INTERFACE_PUBLIC
+  std::vector<CommandHandle> export_command_handles();
+
+  HARDWARE_INTERFACE_PUBLIC
   return_type start();
 
+  HARDWARE_INTERFACE_PUBLIC
   return_type stop();
 
+  HARDWARE_INTERFACE_PUBLIC
   status get_status() const;
 
+  HARDWARE_INTERFACE_PUBLIC
+  return_type read();
+
+  HARDWARE_INTERFACE_PUBLIC
+  return_type write();
+
 private:
   std::unique_ptr<ActuatorInterface> impl_;
 };

hardware_interface/include/hardware_interface/components/actuator_interface.hpp

@@ -16,11 +16,12 @@
 #define HARDWARE_INTERFACE__COMPONENTS__ACTUATOR_INTERFACE_HPP_
 
 #include <memory>
+#include <vector>
 
+#include "hardware_interface/handle.hpp"
 #include "hardware_interface/hardware_info.hpp"
 #include "hardware_interface/types/hardware_interface_return_values.hpp"
 #include "hardware_interface/types/hardware_interface_status_values.hpp"
-#include "hardware_interface/visibility_control.h"
 
 namespace hardware_interface
 {
@@ -46,16 +47,38 @@ class ActuatorInterface
    * \return return_type::OK if required data are provided and can be parsed,
    * return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type configure(const HardwareInfo & actuator_info) = 0;
 
+  /// Exports all state handles for this actuator.
+  /**
+   * The state handles have to be created and transfered according
+   * to the actuator info passed in for the configuration.
+   *
+   * Note the ownership over the state handles must be released.
+   *
+   * \return vector of state handles
+   */
+  virtual
+  std::vector<StateHandle> export_state_handles() = 0;
+
+  /// Exports all command handles for this actuator.
+  /**
+   * The command handles have to be created and transfered according
+   * to the actuator info passed in for the configuration.
+   *
+   * Note the ownership over the command handles must be released.
+   *
+   * \return vector of command handles
+   */
+  virtual
+  std::vector<CommandHandle> export_command_handles() = 0;
+
   /**
    * \brief Start exchange data with the hardware.
    *
    * \return return_type:OK if everything worked as expected, return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type start() = 0;
 
@@ -64,7 +87,6 @@ class ActuatorInterface
    *
    * \return return_type:OK if everything worked as expected, return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type stop() = 0;
 
@@ -73,9 +95,29 @@ class ActuatorInterface
    *
    * \return status current status.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   status get_status() const = 0;
+
+  /// Read the current state values from the actuator.
+  /**
+   * The data readings from the physical hardware has to be updated
+   * and reflected accordingly in the exported state handles.
+   * That is, the data pointed by the handles shall be updated.
+   *
+   * \return return_type::OK if the read was successful, return_type::ERROR otherwise.
+   */
+  virtual
+  return_type read() = 0;
+
+  /// Write the current command values to the actuator.
+  /**
+   * The physical hardware shall be updated with the latest value from
+   * the exported command handles.
+   *
+   * \return return_type::OK if the read was successful, return_type::ERROR otherwise.
+   */
+  virtual
+  return_type write() = 0;
 };
 
 }  // namespace components

hardware_interface/include/hardware_interface/components/sensor.hpp

@@ -20,6 +20,7 @@
 #include <utility>
 #include <vector>
 
+#include "hardware_interface/handle.hpp"
 #include "hardware_interface/hardware_info.hpp"
 #include "hardware_interface/types/hardware_interface_return_values.hpp"
 #include "hardware_interface/types/hardware_interface_status_values.hpp"
@@ -37,13 +38,17 @@ class Sensor final
 public:
   Sensor() = default;
 
+  HARDWARE_INTERFACE_PUBLIC
   explicit Sensor(std::unique_ptr<SensorInterface> impl);
 
   ~Sensor() = default;
 
   HARDWARE_INTERFACE_PUBLIC
   return_type configure(const HardwareInfo & sensor_info);
 
+  HARDWARE_INTERFACE_PUBLIC
+  std::vector<StateHandle> export_state_handles();
+
   HARDWARE_INTERFACE_PUBLIC
   return_type start();
 
@@ -53,6 +58,9 @@ class Sensor final
   HARDWARE_INTERFACE_PUBLIC
   status get_status() const;
 
+  HARDWARE_INTERFACE_PUBLIC
+  return_type read();
+
 private:
   std::unique_ptr<SensorInterface> impl_;
 };

hardware_interface/include/hardware_interface/components/sensor_interface.hpp

@@ -47,16 +47,26 @@ class SensorInterface
    * \return return_type::OK if required data are provided and can be parsed,
    * return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type configure(const HardwareInfo & sensor_info) = 0;
 
+  /// Exports all state handles for this sensor.
+  /**
+   * The state handles have to be created and transfered according
+   * to the sensor info passed in for the configuration.
+   *
+   * Note the ownership over the state handles must be released.
+   *
+   * \return vector of state handles
+   */
+  virtual
+  std::vector<StateHandle> export_state_handles() = 0;
+
   /**
    * \brief Start exchange data with the hardware.
    *
    * \return return_type:OK if everything worked as expected, return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type start() = 0;
 
@@ -65,7 +75,6 @@ class SensorInterface
    *
    * \return return_type:OK if everything worked as expected, return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type stop() = 0;
 
@@ -74,9 +83,19 @@ class SensorInterface
    *
    * \return status current status.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   status get_status() const = 0;
+
+  /// Read the current state values from the sensor.
+  /**
+   * The data readings from the physical hardware has to be updated
+   * and reflected accordingly in the exported state handles.
+   * That is, the data pointed by the handles shall be updated.
+   *
+   * \return return_type::OK if the read was successful, return_type::ERROR otherwise.
+   */
+  virtual
+  return_type read() = 0;
 };
 
 }  // namespace components

hardware_interface/include/hardware_interface/components/system.hpp

@@ -20,6 +20,7 @@
 #include <utility>
 #include <vector>
 
+#include "hardware_interface/handle.hpp"
 #include "hardware_interface/hardware_info.hpp"
 #include "hardware_interface/types/hardware_interface_return_values.hpp"
 #include "hardware_interface/types/hardware_interface_status_values.hpp"
@@ -43,6 +44,12 @@ class System final
   HARDWARE_INTERFACE_PUBLIC
   return_type configure(const HardwareInfo & system_info);
 
+  HARDWARE_INTERFACE_PUBLIC
+  std::vector<StateHandle> export_state_handles();
+
+  HARDWARE_INTERFACE_PUBLIC
+  std::vector<CommandHandle> export_command_handles();
+
   HARDWARE_INTERFACE_PUBLIC
   return_type start();
 
@@ -52,6 +59,12 @@ class System final
   HARDWARE_INTERFACE_PUBLIC
   status get_status() const;
 
+  HARDWARE_INTERFACE_PUBLIC
+  return_type read();
+
+  HARDWARE_INTERFACE_PUBLIC
+  return_type write();
+
 private:
   std::unique_ptr<SystemInterface> impl_;
 };

hardware_interface/include/hardware_interface/components/system_interface.hpp

@@ -48,16 +48,38 @@ class SystemInterface
    * \return return_type::OK if required data are provided and can be parsed,
    * return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type configure(const HardwareInfo & system_info) = 0;
 
+  /// Exports all state handles for this system.
+  /**
+   * The state handles have to be created and transfered according
+   * to the system info passed in for the configuration.
+   *
+   * Note the ownership over the state handles must be released.
+   *
+   * \return vector of state handles
+   */
+  virtual
+  std::vector<StateHandle> export_state_handles() = 0;
+
+  /// Exports all command handles for this system.
+  /**
+   * The command handles have to be created and transfered according
+   * to the system info passed in for the configuration.
+   *
+   * Note the ownership over the command handles must be released.
+   *
+   * \return vector of command handles
+   */
+  virtual
+  std::vector<CommandHandle> export_command_handles() = 0;
+
   /**
    * \brief Start exchange data with the hardware.
    *
    * \return return_type:OK if everything worked as expected, return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type start() = 0;
 
@@ -66,7 +88,6 @@ class SystemInterface
    *
    * \return return_type:OK if everything worked as expected, return_type::ERROR otherwise.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   return_type stop() = 0;
 
@@ -75,9 +96,29 @@ class SystemInterface
    *
    * \return status current status.
    */
-  HARDWARE_INTERFACE_PUBLIC
   virtual
   status get_status() const = 0;
+
+  /// Read the current state values from the actuators and sensors within the system.
+  /**
+   * The data readings from the physical hardware has to be updated
+   * and reflected accordingly in the exported state handles.
+   * That is, the data pointed by the handles shall be updated.
+   *
+   * \return return_type::OK if the read was successful, return_type::ERROR otherwise.
+   */
+  virtual
+  return_type read() = 0;
+
+  /// Write the current command values to the actuator within the system.
+  /**
+   * The physical hardware shall be updated with the latest value from
+   * the exported command handles.
+   *
+   * \return return_type::OK if the read was successful, return_type::ERROR otherwise.
+   */
+  virtual
+  return_type write() = 0;
 };
 
 }  // namespace components