Restructuring of the repository for better overview.

.github/workflows/ci-coverage-build.yml

@@ -23,10 +23,13 @@ jobs:
           import-token: ${{ secrets.GITHUB_TOKEN }}
           # build all packages listed in the meta package
           package-name:
-            diffbot_description
-            ros2_control_demo_bringup
-            ros2_control_demo_hardware
-            rrbot_description
+            ros2_control_demo_example_1
+            ros2_control_demo_example_2
+            ros2_control_demo_example_3
+            ros2_control_demo_example_4
+            ros2_control_demo_example_5
+            ros2_control_demo_example_6
+            ros2_control_demo_example_8
 
           vcs-repo-file-url: |
             https://raw.githubusercontent.com/${{ github.repository }}/${{ github.sha }}/ros2_control_demos-not-released.${{ env.ROS_DISTRO }}.repos?token=${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci-ros-lint.yml

@@ -18,11 +18,13 @@ jobs:
         distribution: rolling
         linter: ${{ matrix.linter }}
         package-name:
-          diffbot_description
-          ros2_control_demo_bringup
-          ros2_control_demo_hardware
-          rrbot_description
-
+          ros2_control_demo_example_1
+          ros2_control_demo_example_2
+          ros2_control_demo_example_3
+          ros2_control_demo_example_4
+          ros2_control_demo_example_5
+          ros2_control_demo_example_6
+          ros2_control_demo_example_8
 
   ament_lint_100:
     name: ament_${{ matrix.linter }}
@@ -40,7 +42,10 @@ jobs:
         linter: cpplint
         arguments: "--linelength=100 --filter=-whitespace/newline"
         package-name:
-          diffbot_description
-          ros2_control_demo_bringup
-          ros2_control_demo_hardware
-          rrbot_description
+          ros2_control_demo_example_1
+          ros2_control_demo_example_2
+          ros2_control_demo_example_3
+          ros2_control_demo_example_4
+          ros2_control_demo_example_5
+          ros2_control_demo_example_6
+          ros2_control_demo_example_8

.github/workflows/reusable-ros-tooling-source-build.yml

@@ -32,10 +32,13 @@ jobs:
           target-ros2-distro: ${{ inputs.ros_distro }}
           # build all packages listed in the meta package
           package-name:
-            diffbot_description
-            ros2_control_demo_bringup
-            ros2_control_demo_hardware
-            rrbot_description
+            ros2_control_demo_example_1
+            ros2_control_demo_example_2
+            ros2_control_demo_example_3
+            ros2_control_demo_example_4
+            ros2_control_demo_example_5
+            ros2_control_demo_example_6
+            ros2_control_demo_example_8
 
           vcs-repo-file-url: |
             https://raw.githubusercontent.com/ros2/ros2/${{ inputs.ros_distro }}/ros2.repos

doc/index.rst

@@ -1,110 +1,103 @@
 .. _ros2_control_demos:
 
+#################
 Demos
------
+#################
 
-This repository provides templates for the development of ros2_control-enabled robots and a simple simulations to demonstrate and prove ros2_control concepts.
+This `GitHub Repository <https://github.com/ros-controls/ros2_control_demos>`_
+provides templates for the development of ros2_control-enabled robots and a simple simulations to demonstrate and prove ros2_control concepts.
 
-Repository organization
-^^^^^^^^^^^^^^^^^^^^^^^
+If you want to have a rather step by step manual how to do things with ``ros2_control`` checkout `ros-control/roscon2022_workshop <https://github.com/ros-controls/roscon2022_workshop>`_ repository.
 
-**Note:** the following list is comprehensive.
+==========================================
+What you can find in this repository
+==========================================
 
-The repository is organized in the following packages:
+This repository demonstrates the following ``ros2_control`` concepts:
 
-  - ``ros2_control_demo_hardware`` - implementation of example hardware interfaces,
-  - ``ros2_control_demo_bringup`` - nodes starting hardware interfaces, controllers and GUIs.
-  - ``ros2_control_test_node`` - nodes for testing ros2_control-enabled robots and their integration in the framework.
+* Creating a ``HardwareInterface`` for a System, Sensor, and Actuator.
+* Creating a robot description in the form of URDF files.
+* Loading the configuration and starting a robot using launch files.
+* Control of a differential mobile base *DiffBot*.
+* Control of two joints of *RRBot*.
+* Implementing a controller switching strategy for a robot.
+* Using joint limits and transmission concepts in ``ros2_control``.
 
-Mode switching demo
-^^^^^^^^^^^^^^^^^^^
+=====================
+Goals
+=====================
 
-Start up the multi interface rrbot system:
+The repository has two other goals:
 
-.. code-block:: bash
+1. Implements the example configuration described in the ``ros-controls/roadmap`` repository file `components_architecture_and_urdf_examples <https://github.com/ros-controls/roadmap/blob/master/design_drafts/components_architecture_and_urdf_examples.md>`_.
+2. The repository is a validation environment for ``ros2_control`` concepts, which can only be tested during run-time (e.g., execution of controllers by the controller manager, communication between robot hardware and controllers).
 
-    ros2 launch ros2_control_demo_bringup rrbot_system_multi_interface.launch.py
+=====================
+Example Overview
+=====================
 
-List the available interfaces
+* Example 1: RRBot
 
-.. code-block:: bash
+   *RRBot* - or ''Revolute-Revolute Manipulator Robot'' - a simple position controlled robot with one hardware interface. This example also demonstrates the switching between different controllers.
 
-    $ ros2 control list_hardware_interfaces
-    command interfaces
-        joint1/acceleration [unclaimed]
-        joint1/position [unclaimed]
-        joint1/velocity [unclaimed]
-        joint2/acceleration [unclaimed]
-        joint2/position [unclaimed]
-        joint2/velocity [unclaimed]
-    state interfaces
-         joint1/acceleration
-         joint1/position
-         joint1/velocity
-         joint2/acceleration
-         joint2/position
-         joint2/velocity
 
-Load and configure all controllers
+* Example 2: DiffBot
 
-.. code-block:: bash
+   *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.
 
-    ros2 control load_controller forward_position_controller --set-state configure
-    ros2 control load_controller forward_velocity_controller --set-state configure
-    ros2 control load_controller forward_acceleration_controller --set-state configure
-    ros2 control load_controller forward_illegal1_controller --set-state configure
-    ros2 control load_controller forward_illegal2_controller --set-state configure
-    ros2 control load_controller joint_state_broadcaster --set-state configure
 
+* Example 3: "RRBot with multiple interfaces"
 
-Start the position controller
+   *RRBot* with multiple interfaces.
 
-.. code-block:: bash
 
-    ros2 control set_controller_state forward_position_controller start
+* Example 4: "Industrial robot with integrated sensor"
 
-Check the hardware interfaces, position interfaces should be claimed now
+   *RRBot* with an integrated sensor.
 
-.. code-block:: bash
 
-    $ ros2 control list_hardware_interfaces
-    command interfaces
-        joint1/acceleration [unclaimed]
-        joint1/position [claimed]
-        joint1/velocity [unclaimed]
-        joint2/acceleration [unclaimed]
-        joint2/position [claimed]
-        joint2/velocity [unclaimed]
-    state interfaces
-         joint1/acceleration
-         joint1/position
-         joint1/velocity
-         joint2/acceleration
-         joint2/position
-         joint2/velocity
+* Example 5: "Industrial Robots with externally connected sensor"
 
-Let's switch controllers now to velocity
+   *RRBot* with an externally connected sensor.
 
-.. code-block:: bash
+* Example 6: "Modular Robots with separate communication to each actuator"
 
-    ros2 control switch_controllers --stop forward_position_controller --start forward_velocity_controller
+   The example shows how to implement robot hardware with separate communication to each actuator.
 
-List hardware interfaces again to see that indeed position interfaces have been unclaimed while velocity is claimed now
 
-.. code-block:: bash
+* Example 8: Using transmissions
 
-    $ ros2 control list_hardware_interfaces
-    command interfaces
-        joint1/acceleration [unclaimed]
-        joint1/position [unclaimed]
-        joint1/velocity [claimed]
-        joint2/acceleration [unclaimed]
-        joint2/position [unclaimed]
-        joint2/velocity [claimed]
-    state interfaces
-         joint1/acceleration
-         joint1/position
-         joint1/velocity
-         joint2/acceleration
-         joint2/position
-         joint2/velocity
+   *RRBot* with an exposed transmission interface.
+
+=====================
+Quick Hints
+=====================
+
+These are some quick hints, especially for those coming from a ROS1 control background:
+
+* There are now three categories of hardware components: *Sensor*, *Actuator*, and *System*.
+  *Sensor* is for individual sensors; *Actuator* is for individual actuators; *System* is for any combination of multiple sensors/actuators.
+  You could think of a Sensor as read-only.
+  All components are used as plugins and therefore exported using ``PLUGINLIB_EXPORT_CLASS`` macro.
+* *ros(1)_control* only allowed three hardware interface types: position, velocity, and effort.
+  *ros2_control* allows you to create any interface type by defining a custom string. For example, you might define a ``position_in_degrees`` or a ``temperature`` interface.
+  The most common (position, velocity, acceleration, effort) are already defined as constants in hardware_interface/types/hardware_interface_type_values.hpp.
+* Joint names in <ros2_control> tags in the URDF must be compatible with the controller's configuration.
+* In ros2_control, all parameters for the driver are specified in the URDF.
+  The ros2_control framework uses the **<ros2_control>** tag in the URDF.
+* Joint names in <ros2_control> tags in the URDF must be compatible with the controller's configuration.
+
+=====================
+Examples
+=====================
+.. toctree::
+   :titlesonly:
+
+   Example 1: RRBot <../example_1/doc/userdoc.rst>
+   Example 2: DiffBot <../example_2/doc/userdoc.rst>
+   Example 3: RRBot with multiple interfaces <../example_3/doc/userdoc.rst>
+   Example 4: Industrial robot with integrated sensor <../example_4/doc/userdoc.rst>
+   Example 5: Industrial Robots with externally connected sensor <../example_5/doc/userdoc.rst>
+   Example 6: Modular Robots with separate communication to each actuator <../example_6/doc/userdoc.rst>
+   Example 8: Using transmissions <../example_8/doc/userdoc.rst>

example_1/CMakeLists.txt

@@ -0,0 +1,73 @@
+cmake_minimum_required(VERSION 3.16)
+project(ros2_control_demo_example_1 LANGUAGES CXX)
+
+if(CMAKE_CXX_COMPILER_ID MATCHES "(GNU|Clang)")
+  add_compile_options(-Wall -Wextra)
+endif()
+
+# find dependencies
+set(THIS_PACKAGE_INCLUDE_DEPENDS
+  hardware_interface
+  pluginlib
+  rclcpp
+  rclcpp_lifecycle
+)
+
+# find dependencies
+find_package(ament_cmake REQUIRED)
+foreach(Dependency IN ITEMS ${THIS_PACKAGE_INCLUDE_DEPENDS})
+  find_package(${Dependency} REQUIRED)
+endforeach()
+
+
+## COMPILE
+add_library(
+  ros2_control_demo_example_1
+  SHARED
+  hardware/rrbot.cpp
+)
+target_compile_features(ros2_control_demo_example_1 PUBLIC cxx_std_17)
+target_include_directories(ros2_control_demo_example_1 PUBLIC
+$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/hardware/include>
+$<INSTALL_INTERFACE:include/ros2_control_demo_example_1>
+)
+ament_target_dependencies(
+  ros2_control_demo_example_1 PUBLIC
+  ${THIS_PACKAGE_INCLUDE_DEPENDS}
+)
+
+# Causes the visibility macros to use dllexport rather than dllimport,
+# which is appropriate when building the dll but not consuming it.
+target_compile_definitions(${PROJECT_NAME} PRIVATE "ROS2_CONTROL_DEMO_EXAMPLE_1_BUILDING_DLL")
+
+# Export hardware plugins
+pluginlib_export_plugin_description_file(hardware_interface ros2_control_demo_example_1.xml)
+
+# INSTALL
+install(
+  DIRECTORY hardware/include/
+  DESTINATION include/ros2_control_demo_example_1
+)
+install(
+  DIRECTORY description/launch description/ros2_control description/urdf description/rviz
+  DESTINATION share/ros2_control_demo_example_1
+)
+install(
+  DIRECTORY bringup/launch bringup/config
+  DESTINATION share/ros2_control_demo_example_1
+)
+install(TARGETS ros2_control_demo_example_1
+  EXPORT export_ros2_control_demo_example_1
+  ARCHIVE DESTINATION lib
+  LIBRARY DESTINATION lib
+  RUNTIME DESTINATION bin
+)
+
+if(BUILD_TESTING)
+  find_package(ament_cmake_gtest REQUIRED)
+endif()
+
+## EXPORTS
+ament_export_targets(export_ros2_control_demo_example_1 HAS_LIBRARY_TARGET)
+ament_export_dependencies(${THIS_PACKAGE_INCLUDE_DEPENDS})
+ament_package()

example_1/bringup/config/rrbot_forward_position_publisher.yaml

@@ -0,0 +1,11 @@
+publisher_forward_position_controller:
+  ros__parameters:
+
+    wait_sec_between_publish: 5
+    publish_topic: "/forward_position_controller/commands"
+
+    goal_names: ["pos1", "pos2", "pos3", "pos4"]
+    pos1: [0.785, 0.785]
+    pos2: [0, 0]
+    pos3: [-0.785, -0.785]
+    pos4: [0, 0]