Semantic components docs (#2032)

ros-controls · Feb 4, 2025 · a91619e · a91619e
1 parent 32d1508
commit a91619e
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 5 deletions.
diff --git a/hardware_interface/doc/asynchronous_components.rst b/hardware_interface/doc/asynchronous_components.rst
@@ -1,4 +1,4 @@
-:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/different_update_rates_userdoc.rst
+:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/asynchronous_components.rst
 
 .. _asynchronous_components:
 

diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst
@@ -18,6 +18,7 @@ Guidelines and Best Practices
    Writing a Hardware Component <writing_new_hardware_component.rst>
    Different Update Rates <different_update_rates_userdoc.rst>
    Asynchronous Execution <asynchronous_components.rst>
+   Semantic Components <semantic_components.rst>
 
 
 Handling of errors that happen during read() and write() calls

diff --git a/hardware_interface/doc/hardware_interface_types_userdoc.rst b/hardware_interface/doc/hardware_interface_types_userdoc.rst
@@ -54,10 +54,7 @@ Sensors
 *****************************
 ``<sensor>``-tag groups multiple state interfaces describing, e.g., internal states of hardware.
 
-Depending on the type of sensor, there exist a couple of specific semantic components with broadcasters shipped with ros2_controllers, e.g.
-
-- :ref:`Imu Sensor Broadcaster <imu_sensor_broadcaster_userdoc>`
-- :ref:`Force Torque Sensor Broadcaster <force_torque_sensor_broadcaster_userdoc>`
+Depending on the type of sensor, there exist a couple of specific semantic components with broadcasters shipped with ros2_controllers, see details in the :ref:`semantic_components <semantic_components>`.
 
 GPIOs
 *****************************

diff --git a/hardware_interface/doc/semantic_components.rst b/hardware_interface/doc/semantic_components.rst
@@ -0,0 +1,20 @@
+:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/semantic_components.rst
+
+.. _semantic_components:
+
+Semantic Components
+---------------------------------------------------------
+
+In order to streamline the configuration of commonly used hardware interface, so-called semantic components can be used to wrap mechanisms to claim / release the interfaces. The base components ``semantic_components::SemanticComponentInterface`` and ``semantic_components::SemanticComponentCommandInterface`` are used to define semantic components for read-only and write-only devices, respectively.
+
+List of existing ``SemanticComponentInterface`` `(link to header file) <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/semantic_component_interface.hpp>`__ and associated broadcaster, if any:
+
+   * `IMUSensor <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/imu_sensor.hpp>`__, used by :ref:`IMU Sensor Broadcaster <imu_sensor_broadcaster_userdoc>`
+   * `ForceTorqueSensor <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/force_torque_sensor.hpp>`__, used by :ref:`Force Torque Sensor Broadcaster <force_torque_sensor_broadcaster_userdoc>`
+   * `GPSSensor <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/gps_sensor.hpp>`__
+   * `PoseSensor <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/pose_sensor.hpp>`__, used by :ref:`Pose Broadcaster <pose_broadcaster_userdoc>`
+   * `RangeSensor <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/range_sensor.hpp>`__, used by :ref:`Range Sensor Broadcaster <range_sensor_broadcaster_userdoc>`
+
+List of existing ``SemanticComponentCommandInterface`` `(link to header file) <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/semantic_component_command_interface.hpp>`__ and associated controller, if any:
+
+   * `LedRgbDevice <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/controller_interface/include/semantic_components/led_rgb_device.hpp>`__