diff --git a/_docs/concepts/client_library/system_modes/index.md b/_docs/concepts/client_library/system_modes/index.md index facf7c93..dcb7d688 100644 --- 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). \ No newline at end of file