General information about this repository, including legal information, project context, build instructions and known issues/limitations, are given in README.md in the repository root.

ROS 2 System Modes

The system modes concept assumes that a robotics system is built from components with a lifecycle. It adds a notion of (sub-)systems, hiararchically grouping these nodes, as well as a notion of modes that determine the configuration of these nodes and (sub-)systems in terms of their parameter values.

A list of (current and future) requirements for system modes can be found here: requirements.

System Modes Package

The system modes concept is implemented as a package for ROS 2. This package provides a library for system mode inference, a mode manager, and a mode monitor.

System Modes Library

The library consists of the parser of the system modes model and the mode inference mechanism.

Hierarchal System Modeling

We assume the system to comprise of loosely-coupled - potentially distributed - components with a runtime lifecycle; hereinafter referred to as 'nodes'. We call semantic grouping of these nodes a (sub-)system. We assume that these (sub-)systems can again be hierarchically grouped into further (sub-)systems, see system-of-systems. All nodes and (sub-)systems that belong to a (sub-)system S are referred to as parts of (sub-)system S.

The introduced notion of (sub-)systems does not refer to a concrete software entity, but rather a virtual abstraction that allows efficient and consistent handling of node groups.

Note: In a first stage of this concept, we assume that the entire system can be specified up-front. Later revisions of this concept might have to take care of changing systems, i.e. further nodes and/or (sub-)systems joining at runtime.

Lifecycle

Within this package, we assume that nodes are ROS 2 Lifecycle Nodes. We additionally establish the same lifecycle for the (sub-)systems introduced above. Hence, all parts of a system can be assumed to have the same lifecycle.

The illustration on the left shows a simplified version of the standard ROS 2 lifecycle. It is simplified by grouping the ROS 2 states unconfigured and inactive (both subsumed under inactive). We extend this lifecycle (illustration on the right) by the following aspects: 1. We introduce modes that are specializations of the active state, see System Modes. 2. We introduce an optional transition from active to activating to allow changing the mode without deactivating the node.

System Modes

System modes extend the activate state of the ROS 2 lifecycle and allow to specify different configurations of nodes and (sub-)systems:

• Modes of nodes consist of parameter values.
• Modes of (sub-)system) consist of modes of their parts.

For example, a node representing an actuator might provide different modes that specify certain maximum speed or maximum torque values. An actuation sub-system, grouping several actuator nodes, might provide modes that activate/deactivate certain contained actuator nodes and/or change their modes based on its own modes.

Both, the system hierarchy as well as the system modes are specified in a system modes and hierarchy model file (SHM file, yaml format) that can be parsed by the mode inference mechanism. The SMH file adheres to the following format:

{system}:
  ros__parameters:
    type: system
    parts:
      {node}
      […]
    modes:
      __DEFAULT__:
        {node}: {state}[.{MODE}]
        […]
      {MODE}:
        {node}: {state}[.{MODE}]
        […]
      […]
[…]

{node}:
  ros__parameters:
    type: node
    modes:
      __DEFAULT__:
        ros__parameters:
          {parameter}: {value}
          […]
      {MODE}:
        ros__parameters:
          {parameter}: {value}
          […]
      […]
[…]

(curly brackets indicate placeholders, square brackets indicate optional parts, ellipses indicate repeatability)

The system_modes_examples package shows a simple example consisting of modes for one system and two nodes. The model file of the example can be found here.

Mode Inference

Since the introduced (sub-)systems are not concrete software entities, their state and mode has to be inferred from the states and modes of their parts. This inference mechanism is part of the system modes library and is used by the mode manager and mode monitor that are also included in this package. We can show that system states and modes can be deterministically inferred under the following conditions: 1. Nodes can be asked for their state, mode, and parameters
This is true, since the lifecycle nodes provide the according lifecycle state service (GetState) and the mode manager provides the according mode service (GetMode). 1. Target states and modes are known
Before attempting a state or mode change for a system or node, the mode manager publishes information about the request.
The according topics might need to be latched in order to allow nodes to do the inference after joining a running system.

Mode Manager

The mode manager is a ROS node that accepts an SHM file (see above) as command line parameter. It parses the SHM file and creates the according services, publishers, and subscribers to manage the system and its modes.

• For (sub-)systems, it mirrors the lifecycle services that are available for ROS 2 lifecycle nodes, i.e.
  • /{system}/get_available_states - lifecycle_msgs/GetAvailableStates
  • /{system}/get_state - lifecycle_msgs/GetState
  • /{system}/change_state - lifecycle_msgs/ChangeState
• For (sub-)systems and nodes, it provides similar services for modes, i.e.
  • /{system_or_node}/get_available_modes - system_modes/GetAvailableModes
  • /{system_or_node}/get_mode - system_modes/GetMode
  • /{system_or_node}/change_mode - system_modes/ChangeMode
• Service calls to these services publish information on the requested state change or mode change before attempting them. These are published on the following topics:
  • /{system_or_node}/transition_request_info - lifecycle_msgs/TransitionEvent
  • /{system_or_node}/mode_request_info - system_modes/ModeEvent

Running the manager:
$ mode-manager path/to/modelfile.yaml

Mode Monitor

The mode monitor is a ROS node that accepts an SHM file (see above) as command line parameter. It continuously monitors and displays the entire system state and mode based on the mode inference introduced above. It monitors the following topics: * /{system_or_node}/transition_request_info for all known (sub-)systems and nodes from the model file to monitor their target states * /{system_or_node}/mode_request_info for all known (sub-)systems and nodes from the model file to monitor their target modes * /parameter_events to infer the current modes for all known nodes based on their parameter values

Running the monitor:
$ mode-monitor path/to/modelfile.yaml

Changelog for package system_modes

0.1.2 (2019-03-18)

• fixed dependencies in package.xml

0.1.1 (2019-03-08)

• first public release for ROS 2 system modes