Update system modes page to reflect state of affairs by end of 2020 (#260)

norro · web-flow · commit 0622cb70049d · 2020-12-10T14:34:49.000+01:00
* Added basic lifecycle (rclc_lifecycle)
* Updated description of error handling and rules, added reference to MROS
* Kicked roadmap (superflous because task ends)

Signed-off-by: Nordmann Arne (CR/ADT3) &lt;arne.nordmann@de.bosch.com&gt;
diff --git a/_docs/concepts/client_library/system_modes/index.md b/_docs/concepts/client_library/system_modes/index.md
@@ -10,16 +10,12 @@ Table of contents
 - [Requirements](#requirements)
 - [Background: ROS 2 Lifecycle](#background-ros-2-lifecycle)
 - [Main Features](#main-features)
+  - [Basic Lifecycle](#basic-lifecycle)
   - [Extended Lifecycle](#extended-lifecycle)
   - [System Hierarchy and Modes](#system-hierarchy-and-modes)
   - [Mode Inference](#mode-inference)
   - [Mode Manager](#mode-manager)
-  - [Error Handling and Rules (Experimental)](#error-handling-and-rules-experimental)
-- [Roadmap](#roadmap)
-  - [2018](#2018)
-  - [2019](#2019)
-  - [2020](#2020)
-  - [2021](#2021)
+  - [Error Handling and Rules](#error-handling-and-rules)
 - [Acknowledgments](#acknowledgments)
 
 ## Introduction and Goal
@@ -52,38 +48,46 @@ The main features of the approach are (detailed in the remainder):
 2. _System Hierarchy and Modes_: Modeling approach for specifying a ROS system in terms of its system hierarchy and _system modes_, i.e. different (sub-)system configurations.
 3. _Mode Manager_: A module to manage and change the system runtime configuration.
 4. _Mode Inference_: A module for deriving the entire system state and mode from observable system information, i.e. states, modes, and parameters of its components.
-5. _Diagnostics_: Diagnosis module for deriving relevant information from the operating systems, the hardware and the functional components.
+5. _Error Handling_: Lightweight concept for specifying an error handling and recovery mechanism.
 
 ## Requirements
 
-The list of requirements is maintained in the doc folder of the micro-ROS system modes repository, at:  
+The list of requirements is maintained in the doc folder of the micro-ROS system modes repository, at:
 https://github.com/micro-ROS/system_modes/blob/master/system_modes/doc/requirements.md
 
 ## Background: ROS 2 Lifecycle
 
 Our approach is based on the ROS 2 Lifecycle. The primary goal of the ROS 2 lifecycle is to allows greater control over the state of a ROS system. It allows consistent initialization, restart and/or replacing of system parts during runtime. It provides a default lifecycle for managed ROS 2 nodes and a matching set of tools for managing lifecycle nodes.
 
-The description of the concept can be found at:  
+The description of the concept can be found at:
 [http://design.ros2.org/articles/node_lifecycle.html](http://design.ros2.org/articles/node_lifecycle.html)
-The implementation of the Lifecycle Node is described at:  
+The implementation of the Lifecycle Node is described at:
 [https://index.ros.org/doc/ros2/Managed-Nodes/](https://index.ros.org/doc/ros2/Managed-Nodes/).
 
 ## Main Features
 
+### Basic Lifecycle
+
+The ROS 2 Lifecycle has been implemented for micro-ROS as part of the C programming language client library *[rclc](https://github.com/ros2/rclc)*, see [rclc_lifecycle](https://github.com/ros2/rclc/tree/master/rclc_lifecycle) for source-code and documentation.
+
+The rclc_lifecycle package is a ROS 2 package that provides convenience functions to bundle a ROS Client Library (rcl) node with the ROS 2 Node Lifecycle state machine in the C programming language, similar to the [rclcpp Lifecycle Node](https://github.com/ros2/rclcpp/blob/master/rclcpp_lifecycle/include/rclcpp_lifecycle/lifecycle_node.hpp) for C++.
+
+An example, how to use the rclc Lifecycle Node is given in the file `lifecycle_node.c` in the [rclc_examples](https://github.com/ros2/rclc/blob/master/rclc_examples/) package.
+
 ### Extended Lifecycle
 
-In micro-ROS, we extend the ROS 2 lifecycle by allowing to specify modes, i.e. substates, specializing the *active* *state based on the standard ROS 2 parameters mechanism. We implemented this concept based on rcl and rclcpp for ROS 2 and micro-ROS.
+In micro-ROS, we extend the ROS 2 lifecycle by allowing to specify modes, i.e. substates, specializing the *active* state based on the standard ROS 2 parameters mechanism. We implemented this concept based on rclc_lifecycle and rclcpp_lifecycle for ROS 2 and micro-ROS.
 
-Documentation and code can be found at:  
+Documentation and code can be found at:
 [github.com:system_modes/README.md#lifecycle](https://github.com/micro-ROS/system_modes/blob/master/system_modes/README.md#lifecycle)
 
 ### System Hierarchy and Modes
 
 We provide a modeling concept for specifying the hierarchical composition of systems recursively from nodes and for specifying the states and modes of systems and (sub-)systems with the extended lifecycle, analogously to nodes. This system modes and hierarchy (SMH) model also includes an application-specific the mapping of the states and modes along the system hierarchy down to nodes.
 
-The description of this model can be found at:  
+The description of this model can be found at:
 [github.com:system_modes/README.md#system-modes](https://github.com/micro-ROS/system_modes/blob/master/system_modes/README.md#system-modes)
-A simple example is provided at:  
+A simple example is provided at:
 [github.com:system_modes_examples/README.md#example-mode-file](https://github.com/micro-ROS/system_modes/blob/master/system_modes_examples/README.md#example-mode-file)
 
 ### Mode Inference
@@ -94,23 +98,23 @@ Based on the lifecycle change events it knows the _actual_ lifecycle state of al
 Based on the SMH model and the inferred states and modes of all nodes, states and modes of all (sub-)systems can be _inferred_ bottom-up along the system hierarchy.
 This can be compared to the latest _requested_ states and modes to detect a deviation.
 
-The documentation and code can be found at:  
+The documentation and code can be found at:
 [github.com:system_modes/README.md#mode-inference](https://github.com/micro-ROS/system_modes/blob/master/system_modes/README.md#mode-inference)
-The mode inference can be best observed in the mode monitor, a console-based debugging tool, see:  
+The mode inference can be best observed in the mode monitor, a console-based debugging tool, see:
 [github.com:system_modes/README.md#mode-monitor](https://github.com/micro-ROS/system_modes/blob/master/system_modes/README.md#mode-monitor)
 
 ### Mode Manager
 
 Building upon the _Mode Inference_ mechanism, the mode manager provides additional services and topics to _manage and adapt_ system states and modes according to the specification in the SMH model.
 
-The documentation and code can be found at:  
+The documentation and code can be found at:
 [github.com:system_modes/README.md#mode-manager](https://github.com/micro-ROS/system_modes/blob/master/system_modes/README.md#mode-manager)
-A simple example is provided at:  
+A simple example is provided at:
 [github.com:system_modes_examples/README.md#setup](https://github.com/micro-ROS/system_modes/blob/master/system_modes_examples/README.md#setup)
 
-### Error Handling and Rules (Experimental)
+### Error Handling and Rules
 
-If the _actual_ state/mode of the system or any of its parts diverges from the _target_ state/mode, we define rules that try to bring the system back to a valid _target_ state/mode, e.g., a degraded mode. Rules work in a bottom-up manner, i.e. starting from correcting nodes before sub-systems before systems. Rules are basically defined in the following way:  
+If the _actual_ state/mode of the system or any of its parts diverges from the _target_ state/mode, we define rules that try to bring the system back to a valid _target_ state/mode, e.g., a degraded mode. Rules work in a bottom-up manner, i.e. starting from correcting nodes before sub-systems before systems. Rules are basically defined in the following way:
 
 ```pseudo
 if:
@@ -119,39 +123,10 @@ then:
  system.target := {specific state/mode}
 ```
 
-if _actual_ state/mode and _target_ state/mode diverge, but there is no rule for this exact situation, the bottom-up rules will just try to return the system/part to its _target_ state/mode.
-*Potentiall dangereous, to be discussed:* what's happening, if the system is already on its way. E.g., a system or part was just commanded to transition to _ACTIVE.foo_, but is currently _activating_ (so doing everything right). In this case we have to avoid that the bottom-up rules will trigger.
-
-*Note:* This feature is still experimental and might be subject to major changes. However, if no rules are specified in the model file, this feature is not used.
-
-## Roadmap
-
-### 2018
-
-- Requirements for behavior system composition in robotics systems
-- Modeling concept to specify system hierarchy as well as system modes of systems, subsystems, and their mapping along the system hierarchy down to nodes
-- Python prototype of system modes concept (ROS-independent)
-
-### 2019
-
-- Extended lifecycle concept and implementation for ROS 2 C++
-- Mode inference and mode manager for ROS 2 C++
-- ROS diagnostics port from ROS 1 to ROS 2 (prerequisite for micro-ROS diagnostics)
-- Lightweight concept for error propagation and recovery mechanisms
-
-### 2020
-
-- Integration of mode manager with real-time executor and/or roslaunch
-- Lightweight implementation for specifying error propagation and recovery mechanisms
-- ROS diagnostics port from ROS 1 to ROS 2 (prerequisite for micro-ROS diagnostics)
-
-_Note: The extension of the ACTIVE state by modes (substates) was originally planned for 2020 but brought forward in 2018._
-
-### 2021
+If _actual_ state/mode and _target_ state/mode diverge, but there is no rule for this exact situation, the bottom-up rules will just try to return the system/part to its _target_ state/mode.
 
-- Diagnostics framework for micro-ROS, interoperating with ROS 2 diagnostics
-- MCU-specific diagnostics functions for resource usage on RTOS layer, latencies, statistics from middleware, etc.
+*Note:* This feature is suited for simple, well-defined rules according to the depicted syntax. For more complex orchestration, integration of system modes with ontological reasoning (*metacontrol*) has been validated and successfully shown in the [MROS project](https://robmosys.eu/mros/), e.g., within a [navigation sub-system of a mobile robot](https://github.com/MROS-RobMoSys-ITP/Pilot-URJC).
 
 ## Acknowledgments
 
-This activity has received funding from the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation programme (grant agreement n° 780785).
+This activity has received funding from the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation programme (grant agreement n° 780785).
