From bb4db3c53f31439706cfaf469a2a0b6399659957 Mon Sep 17 00:00:00 2001
From: Christoph Froehlich <christoph.froehlich@ait.ac.at>
Date: Sat, 5 Aug 2023 21:43:08 +0000
Subject: [PATCH] Add list_hardware_components section to docs

---
 example_4/doc/userdoc.rst | 24 ++++++++++++++++++++++++
 example_5/doc/userdoc.rst | 25 +++++++++++++++++++++++++
 example_6/doc/userdoc.rst | 29 +++++++++++++++++++++++++++--
 3 files changed, 76 insertions(+), 2 deletions(-)

diff --git a/example_4/doc/userdoc.rst b/example_4/doc/userdoc.rst
index 6c70870f5..167c3eb97 100644
--- a/example_4/doc/userdoc.rst
+++ b/example_4/doc/userdoc.rst
@@ -66,6 +66,30 @@ Tutorial steps
 
    Marker ``[claimed]`` by command interfaces means that a controller has access to command *RRBot*.
 
+   Now, lets introspect the hardware components with
+
+   .. code-block:: shell
+
+    ros2 control list_hardware_components -v
+
+   There is a single hardware component for the robot providing the command and state interfaces:
+
+   .. code-block:: shell
+
+    Hardware Component 1
+        name: RRBotSystemWithSensor
+        type: system
+        plugin name: ros2_control_demo_example_4/RRBotSystemWithSensorHardware
+        state: id=3 label=active
+        command interfaces
+                joint1/position [available] [claimed]
+                joint2/position [available] [claimed]
+        state interfaces
+                joint1/position [available]
+                joint2/position [available]
+                tcp_fts_sensor/force.x [available]
+                tcp_fts_sensor/torque.z [available]
+
 4. Check if controllers are running
 
    .. code-block:: shell
diff --git a/example_5/doc/userdoc.rst b/example_5/doc/userdoc.rst
index 2e6266f86..c437e45de 100644
--- a/example_5/doc/userdoc.rst
+++ b/example_5/doc/userdoc.rst
@@ -69,6 +69,31 @@ Tutorial steps
 
    Marker ``[claimed]`` by command interfaces means that a controller has access to command *RRBot*.
 
+   Now, lets introspect the hardware components with
+
+   .. code-block:: shell
+
+    ros2 control list_hardware_components
+
+   There are two hardware components, one for the robot and one for the sensor:
+
+   .. code-block:: shell
+
+    Hardware Component 1
+            name: ExternalRRBotFTSensor
+            type: sensor
+            plugin name: ros2_control_demo_example_5/ExternalRRBotForceTorqueSensorHardware
+            state: id=3 label=active
+            command interfaces
+    Hardware Component 2
+            name: RRBotSystemPositionOnly
+            type: system
+            plugin name: ros2_control_demo_example_5/RRBotSystemPositionOnlyHardware
+            state: id=3 label=active
+            command interfaces
+                    joint1/position [available] [claimed]
+                    joint2/position [available] [claimed]
+
 4. Check if controllers are running
 
    .. code-block:: shell
diff --git a/example_6/doc/userdoc.rst b/example_6/doc/userdoc.rst
index 9f6de521d..2c7a858fb 100644
--- a/example_6/doc/userdoc.rst
+++ b/example_6/doc/userdoc.rst
@@ -62,6 +62,31 @@ Tutorial steps
 
    Marker ``[claimed]`` by command interfaces means that a controller has access to command *RRBot*.
 
+   Now, lets introspect the hardware components with
+
+   .. code-block:: shell
+
+    ros2 control list_hardware_components
+
+   There are two hardware components, one for each actuator and one for each sensor:
+
+   .. code-block:: shell
+
+    Hardware Component 1
+            name: RRBotModularJoint2
+            type: actuator
+            plugin name: ros2_control_demo_example_6/RRBotModularJoint
+            state: id=3 label=active
+            command interfaces
+                    joint2/position [available] [claimed]
+    Hardware Component 2
+            name: RRBotModularJoint1
+            type: actuator
+            plugin name: ros2_control_demo_example_6/RRBotModularJoint
+            state: id=3 label=active
+            command interfaces
+                    joint1/position [available] [claimed]
+
 4. Check if controllers are running
 
    .. code-block:: shell
@@ -70,8 +95,8 @@ Tutorial steps
 
    .. code-block:: shell
 
-    forward_position_controller[forward_command_controller/ForwardCommandController]
-    joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster]
+    forward_position_controller[forward_command_controller/ForwardCommandController] active
+    joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active
 
 5. If you get output from above you can send commands to *Forward Command Controller*, either: