General information about this repository, including legal information, build instructions and known issues/limitations, can be found in the README of the repository root.

The system_modes_examples package

This ROS 2 package provides a simple example for the use of the system_modes package. It contains two ROS 2 LifecycleNodes, a drive_base node and a manipulator node, as well as simple a model file (yaml).

Example Model File

The SMH file example_modes.yaml specifies an actuation system consisting of the drive_base node and the manipulator node, system modes for the actuation system, as well as system modes for the two nodes: * The manipulator node has a default mode, a STRONG mode, and a WEAK mode, configuring different values for its max_torque. * The drive_base node has a default mode, a FAST mode, and a SLOW mode, configuring different values for its max_speed and its controller (PID or MPC). * The actuation system comprises of these two nodes. It has a default mode, a PERFORMANCE mode, and a MODERATE mode, changing the modes of its two nodes accordingly.

Running the Example

Setup

Until this package provies a proper launch configruation, open 3 terminals to set up your example system: 1. terminal 1: start the drive_base node:
$ drive_base
1. terminal 2: start the manipulator node:
$ manipulator
1. terminal 3: start the mode-manager with the provided example model file:
$ mode-manager --help
$ mode-manager system_modes_examples/share/example_modes.yaml
The mode manager parses the provided SHM model file and creates the necessary services and topics to manage the system modes of the two nodes as well as services and topics to manage the system modes and the lifecycle of the actuation system.

In an additional fourth terminal, start the mode-monitor to see the system modes inference in action: * $ mode-monitor --help
* $ mode-monitor system_modes_examples/share/example_modes.yaml The monitor updates every second and displays the current lifecycle states and modes of the example system.

Now that you set up the system and you are able to monitor it, play around with it.

Change System States and System Modes

In an additional fifth terminal, you may mimic a planning/executive component to change the state and mode of your system or its components.

1. Start by initializing your system to inactive. The ROS 2 command
   $ ros2 service call /actuation/change_state lifecycle_msgs/ChangeState "{transition: {id: 1, label: configure}}"
   will call the according service on the mode manager, which will change the state of the two nodes to inactive accordingly. Observe the console output of the mode manager and the two nodes as well as the mode monitor. The mode monitor should display the following system state:
   
2. Activate your system with the following ROS 2 command:
   $ ros2 service call /actuation/change_state lifecycle_msgs/ChangeState "{transition: {id: 3, label: activate}}"
   To change the actuation system into active and its default mode (since no explicit mode was requested), the mode manager will set the drive_base to active and leave the manipulator inactive, as specified in the model file. The mode monitor should display the following system state:
   
3. Set your system into PERFORMANCE mode with the following ROS 2 command:
   $ ros2 service call /actuation/change_mode system_modes/ChangeMode "{node_name: 'actuation', mode_name: 'PERFORMANCE'}"
   To change the actuation system into its PERFORMANCE mode, the mode manager will change the drive_base to FAST mode and activate the manipulator node in its STRONG mode. The mode monitor should display the following system state:
   
   Note, that the system state and mode as well as the node modes are indicated to be inferred, as explained in the mode inference section of the system_modes package.
4. You can further play around with the mode inference. For example, change the mode of the two nodes explicitly so that the target mode and actual mode of the actuation system diverge. Execute the following two ROS 2 commands:
   $ ros2 service call /drive_base/change_mode system_modes/ChangeMode "{node_name: 'drive_base', mode_name: 'SLOW'}"
   and
   $ ros2 service call /manipulator/change_mode system_modes/ChangeMode "{node_name: 'manipulator', mode_name: 'WEAK'}"
   The mode monitor should display the following system state:
   
   Note, that the mode monitor is able to infer that the system's actual mode is now MODERATE. This is based on the fact that both its nodes are active, the drive_base is in its SLOW mode, and the manipulator is in its WEAK mode. However, the last requested mode for the actuation system is PERFORMANCE, so the monitor infers that the system is still transitioning into its target mode, indicating that the actual system state is activating (see lifecycle).

Changelog for package system_modes_examples

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 examples