Create doc file for chained controllers (#985)

Co-authored-by: Bence Magyar <[email protected]>
Co-authored-by: Christoph Fröhlich <[email protected]>
(cherry picked from commit 185fbea)

# Conflicts:
#	controller_manager/doc/controller_chaining.rst

controller_manager/doc/controller_chaining.rst

@@ -63,6 +63,7 @@ After configuring a chainable controller, controller manager calls ``input_inter
 This is the same process as done by ``ResourceManager`` and hardware interfaces.
 Controller manager maintains "claimed" status of interface in a vector (the same as done in ``ResourceManager``).
 
+<<<<<<< HEAD
 
 Activation and Deactivation Chained Controllers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -71,6 +72,50 @@ Chained controllers must be activated and deactivated together or in the proper
 This means you must first activate all following controllers to have the preceding one activated.
 For the deactivation there is the inverse rule - all preceding controllers have to be deactivated before the following controller is deactivated.
 One can also think of it as an actual chain, you can not add a chain link or break the chain in the middle.
+=======
+Activation and Deactivation Chained Controllers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Controller Manager has an additional parameter that describes how controllers are chained.
+In the first version, the parameter-structure would have some semantic meaning embedded into it, as follows:
+
+
+.. code-block:: yaml
+
+  controller_manager:
+    ros__parameters:
+      chained_controllers:
+
+        - parallel_group_1:
+          - controller1_1
+          - controller1_2
+
+        - parallel_group_2:
+          - controller2_1
+
+        - parallel_group_3:
+          - controller3_1
+          - controller3_2
+          - controller3_3
+
+        ...
+
+        - parallel_group_N:
+          - controllerN_1
+          - ...
+          - controllerN_M
+
+
+
+This structure is motivated by ``filter_chain`` structure from `ros/filters repository <https://github.com/ros/filters/tree/ros2>`__, see `this file for implementation <https://github.com/ros/filters/blob/ros2/include/filters/filter_chain.hpp>`__.
+
+This structure is stored internally by controller manager into an ordered map (``std::map<std::string, std::vector<std::string>>``) with group name as key.
+When a controller should be deactivated, the controller manager deactivates all the controllers in the preceding groups first.
+All other controllers from the group stay active, as well as all controllers in the following groups.
+NOTE: In the future this could be done more intelligently, i.e., deactivate only controllers in the preceding groups that actually precede the controller that should be deactivated.
+
+On the other hand, the controller should be manually activated in the reverse order, i.e., from the those closer to the hardware toward those preceding them.
+>>>>>>> 185fbea (Create doc file for chained controllers (#985))
 
 
 Debugging outputs

doc/index.rst

@@ -6,6 +6,8 @@
 ros2_control
 #################
 
+This is the documentation of the ros2_control framework core.
+
 `GitHub Repository <https://github.com/ros-controls/ros2_control>`_
 
 =================
@@ -14,15 +16,12 @@ API Documentation
 
 API documentation is parsed by doxygen and can be found `here <../../api/index.html>`_
 
-
-
 =========
 Features
 =========
 
 * :ref:`Command Line Interface (CLI) <ros2controlcli_userdoc>`
 
-
 ========
 Concepts
 ========
@@ -31,5 +30,6 @@ Concepts
    :titlesonly:
 
    Controller Manager <../controller_manager/doc/userdoc.rst>
+   Controller Chaining / Cascade Control <../controller_manager/doc/controller_chaining.rst>
    Hardware Components <../hardware_interface/doc/hardware_components_userdoc.rst>
    Mock Components <../hardware_interface/doc/mock_components_userdoc.rst>