Add more information to example docs (#263)

coming from https://github.com/ros-controls/roadmap/blob/master/design_drafts/components_architecture_and_urdf_examples.md

Author: christophfroehlich

example_1/doc/userdoc.rst

@@ -3,11 +3,23 @@
 Example 1: RRBot
 =====================
 
+*RRBot*, or ''Revolute-Revolute Manipulator Robot'', is a simple 3-linkage, 2-joint arm that we will
+use to demonstrate various features.
+
+It is essentially a double inverted pendulum and demonstrates some fun control concepts within a
+simulator and was originally introduced for Gazebo tutorials.
+
+For *example_1*, the hardware interface plugin is implemented having only one interface.
+
+- The communication is done using proprietary API to communicate with the robot control box.
+- Data for all joints is exchanged at once.
+- Examples: KUKA RSI
 
-*RRBot*, or ''Revolute-Revolute Manipulator Robot'', is a simple 3-linkage, 2-joint arm that we will use to demonstrate various features.
-It is essentially a double inverted pendulum and demonstrates some fun control concepts within a simulator and was originally introduced for Gazebo tutorials.
 The *RRBot* URDF files can be found in the ``description/urdf`` folder.
 
+Tutorial steps
+--------------------------
+
 1. To check that *RRBot* descriptions are working properly use following launch commands
 
    .. code-block:: shell

example_2/doc/userdoc.rst

@@ -6,8 +6,17 @@ DiffBot
 
 *DiffBot*, or ''Differential Mobile Robot'', is a simple mobile base with differential drive.
 The robot is basically a box moving according to differential drive kinematics.
+
+For *example_2*, the hardware interface plugin is implemented having only one interface.
+
+- The communication is done using proprietary API to communicate with the robot control box.
+- Data for all joints is exchanged at once.
+
 The *DiffBot* URDF files can be found in ``description/urdf`` folder.
 
+Tutorial steps
+--------------------------
+
 1. To check that *DiffBot* description is working properly use following launch commands
 
    .. code-block:: shell

example_3/doc/userdoc.rst

@@ -5,7 +5,18 @@ Example 3: Robots with multiple interfaces
 ************************************************
 
 The example shows how to implement multi-interface robot hardware taking care about interfaces used.
-The two illegal controllers demonstrate how hardware interface declines faulty claims to access joint command interfaces.
+
+For *example_3*, the hardware interface plugin is implemented having multiple interfaces.
+
+- The communication is done using proprietary API to communicate with the robot control box.
+- Data for all joints is exchanged at once.
+- Examples: KUKA FRI, ABB Yumi, Schunk LWA4p, etc.
+
+Two illegal controllers demonstrate how hardware interface declines faulty claims to access joint command interfaces.
+
+
+Tutorial steps
+--------------------------
 
 1. To check that *RRBot* descriptions are working properly use following launch commands
 
@@ -128,7 +139,7 @@ The two illegal controllers demonstrate how hardware interface declines faulty c
    - ``robot_controller:=forward_illegal1_controller`` or
    - ``robot_controller:=forward_illegal2_controller``
 
-   You will see the following error messages
+   You will see the following error messages, because the hardware interface enforces all joints having the same command interface
 
    .. code-block:: shell
 

example_4/doc/userdoc.rst

@@ -4,8 +4,19 @@
 Example 4: Industrial robot with integrated sensor
 ***************************************************
 
-This example shows how a sensor can be integrated in a hardware interface of system-type:
-A 2D Force-Torque Sensor (FTS) is simulated by generating random sensor readings.
+This example shows how a sensor can be integrated in a hardware interface:
+
+- The communication is done using proprietary API to communicate with the robot control box.
+- Data for all joints is exchanged at once.
+- Sensor data are exchanged together with joint data
+- Examples: KUKA RSI with sensor connected to KRC (KUKA control box) or a prototype robot (ODRI interface).
+
+A 2D Force-Torque Sensor (FTS) is simulated by generating random sensor readings via a hardware interface of
+type ``hardware_interface::SystemInterface``.
+
+
+Tutorial steps
+--------------------------
 
 1. To check that *RRBot* descriptions are working properly use following launch commands
 

example_5/doc/userdoc.rst

@@ -4,9 +4,18 @@
 Example 5: Industrial robot with externally connected sensor
 *************************************************************
 
-This example shows how an externally connected sensor can be accessed via a hardware interface of
-type ``hardware_interface::SensorInterface``: A 3D Force-Torque Sensor (FTS) is simulated by
-generating random sensor readings.
+This example shows how an externally connected sensor can be accessed:
+
+- The communication is done using proprietary API to communicate with the robot control box.
+- Data for all joints is exchanged at once.
+- Sensor data are exchanged independently of joint data.
+- Examples: KUKA RSI and FTS connected to independent PC with ROS 2.
+
+A 3D Force-Torque Sensor (FTS) is simulated by generating random sensor readings via a hardware interface of
+type ``hardware_interface::SensorInterface``.
+
+Tutorial steps
+--------------------------
 
 1. To check that *RRBot* descriptions are working properly use following launch commands
 

example_6/doc/userdoc.rst

@@ -4,8 +4,16 @@
 Example 6: Modular Robots with separate communication to each actuator
 ***********************************************************************
 
-The example shows how to implement robot hardware with separate communication to each actuator. This
-is implemented with a hardware interface of type ``hardware_interface::ActuatorInterface``.
+The example shows how to implement robot hardware with separate communication to each actuator:
+
+- The communication is done on actuator level using proprietary or standardized API (e.g., canopen_402, Modbus, RS232, RS485).
+- Data for all actuators is exchanged separately from each other.
+- Examples: Mara, Arduino-based-robots
+
+This is implemented with a hardware interface of type ``hardware_interface::ActuatorInterface``.
+
+Tutorial steps
+--------------------------
 
 1. To check that *RRBot* descriptions are working properly use following launch commands
 

example_8/doc/userdoc.rst

@@ -5,8 +5,14 @@ Example 8: Industrial Robots with an exposed transmission interface
 ********************************************************************************
 
 *RRBot*, or ''Revolute-Revolute Manipulator Robot'', is a simple 3-linkage, 2-joint arm that we will use to demonstrate various features.
-In this example, both joints use an exposed transmission interface.
 
+In this example, both joints use an exposed transmission interface:
+
+- The communication is done using proprietary API to communicate with the robot control box.
+- Data for all joints is exchanged at once.
+
+Tutorial steps
+--------------------------
 
 1. To check that *RRBot* descriptions are working properly use following launch commands