Add basic support for Modifiers

docs/libraries.rst

@@ -209,7 +209,7 @@ For debugging purposes, log a string using the available log mechanism.
      - String to log
 
 ``run_process()``
-""""""""""""""""""""""""""
+"""""""""""""""""
 
 Run a process. Reports `running` while the process has not finished.
 
@@ -241,38 +241,82 @@ If ``wait_for_shutdown`` is ``false`` and the process is still running on scenar
      - ``10s``
      - (Only used if ``wait_for_shutdown`` is ``false``) time to wait between ``shutdown_signal`` and SIGKILL getting sent, if process is still running on scenario shutdown
 
-OS
---
 
-The library contains actions to interact with the operating system. Import it with ``import osc.os``. It is provided by the package :repo_link:`libs/scenario_execution_os`.
+Modifiers
+^^^^^^^^^
 
-Actions
-^^^^^^^
+``inverter()``
+""""""""""""""
 
-``check_file_exists()``
-"""""""""""""""""""""""
+Modifier to invert the action result. A failing action will report ``success``, a succeeding action will report ``failure``.
 
-Report success if a file exists.
+``repeat()``
+""""""""""""
+Modifier to repeat a sub-tree. If any of the included children report ``failure``, the repetition stops and ``failure`` is reported.
 
 .. list-table:: 
    :widths: 15 15 5 65
    :header-rows: 1
    :class: tight-table   
-   
+
    * - Parameter
      - Type
      - Default
      - Description
-   * - ``file_name``
-     - ``string``
-     -
-     - File to check
+   * - ``count``
+     - ``int``
+     - ``-1``
+     - Repeat this many times (-1 to repeat indefinitely)
+
+``retry()``
+"""""""""""
+Modifier to retry a sub-tree until it succeeds.
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``count``
+     - ``int``
+     - 
+     - Maximum number of permitted failures
+
+``timeout()``
+"""""""""""""
+Modifier to set a timeout for a sub-tree.
 
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
 
-``check_file_not_exists()``
-"""""""""""""""""""""""""""
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``count``
+     - ``int``
+     - 
+     - Maximum number of permitted failures
 
-Report success if a file does not exist.
+
+OS
+--
+
+The library contains actions to interact with the operating system. Import it with ``import osc.os``. It is provided by the package :repo_link:`libs/scenario_execution_os`.
+
+Actions
+^^^^^^^
+
+``check_file_exists()``
+"""""""""""""""""""""""
+
+Report success if a file exists.
 
 .. list-table:: 
    :widths: 15 15 5 65

docs/openscenario2.rst

@@ -14,7 +14,31 @@ The `standard library of
 OSC2 <https://www.asam.net/static_downloads/public/asam-openscenario/2.0.0/domain-model/standard_library.html>`__
 was adapted to be usable by the current parsing support of scenario execution.
 
-In the following the supported features are described.
+
+Mapping to py-trees
+-------------------
+
+.. list-table:: 
+   :widths: 15 25 60
+   :header-rows: 1
+   :class: tight-table   
+
+   - * OpenScenario2  
+     * py-trees
+     * Comment
+   - * ``action``
+     * ``Behaviour``
+     * Actions are derived from ``scenario_execution.actions.base_action.BaseAction`` which is derived from ``py_trees.behaviour.Behaviour``
+   - * ``event``
+     * blackboard entry and ``Behaviour``
+     * ``Behaviour`` is used to read and write blackboard variable
+   - * ``modifier``
+     * ``Decorator``
+     *
+   - * ``var``
+     * blackboard entry
+     * Variables are stored within the blackboard
+
 
 .. role:: raw-html(raw)
    :format: html
@@ -87,13 +111,13 @@ Composition Types
 
 Composition types are ``struct``, ``actor``, ``action``, ``scenario``.
 
-============== ==================== =========
+============== ==================== ===========================
 Element Type   Support              Notes
-============== ==================== =========
+============== ==================== ===========================
 Event          :raw-html:`&#9989;`      
 Field          :raw-html:`&#9989;`     
 Constraint     :raw-html:`&#9989;`  partially
-Method         :raw-html:`&#10060;`       
+Method         :raw-html:`&#9989;`       
 Coverage       :raw-html:`&#10060;`       
-Modifier       :raw-html:`&#10060;`       
-============== ==================== =========
+Modifier       :raw-html:`&#9989;`  partially (only predefined)     
+============== ==================== ===========================

docs/tutorials.rst

@@ -48,17 +48,14 @@ screen. After the ``log`` action is invoked, the ``wait`` directive makes the sc
    Scenario execution uses the predefined events ``end`` and ``fail`` to detect success or failure of a scenario. If no ``emit end`` or ``emit fail`` is defined, a success is assumed.
 
 .. note::
-    It is good practice to define a timeout action in parallel to the expected actions within a scenario.
+    It is good practice to define a timeout modifier within a scenario or sub-tree or action.
 
     .. code-block::
 
         scenario example:
-            do parallel:
-                serial:
-                    ...
-                serial:
-                    wait elapsed(60s)
-                    emit fail
+            timeout(60s)
+            do serial:
+                ...
 
 Use this code to see a launch of this tutorial:
 
@@ -442,4 +439,4 @@ Use this code to see a launch of this tutorial:
 .. code-block:: bash
 
    colcon build --packages-up-to example_external_method && source install/setup.bash \
-   && ros2 run scenario_execution scenario_execution examples/example_external_method/scenarios/example_external_method.osc
+   && ros2 run scenario_execution scenario_execution examples/example_external_method/scenarios/example_external_method.osc

examples/example_multi_robot/README.md

@@ -13,24 +13,10 @@ source install/setup.bash
 ```
 The Following example spawns 2 robots. The first robot is initialised with nav2 and moves in a straight line. Once it reaches a specific point a velocity command is sent to the second robot which will position itsel in front of the first one. The first robot then replans its path and moves around the second robot.
 
-To actually run the scenario, run the following commands.
-Note: due to an [issue](https://github.com/turtlebot/turtlebot4_simulator/issues/60) with the turtlebot simulation when running multiple robots, some launch commands need to run in separate terminals.
-Launch the simulation and spawn the first robot by running the following command:
+To actually run the scenario, run the following command.
 
 ```bash
-ros2 launch tb4_sim_scenario sim_nav_scenario_launch.py scenario_execution:=False scenario:=foo yaw:=3.14
-```
-
-To spawn the second robot, run the following command in a new terminal:
-
-```bash
-ros2 launch tb4_sim_scenario ignition_robot_launch.py namespace:=turtlebot2 x:=-3.0 y:=1.5 yaw:=-1.57
-```
-
-To run the actual scenario, run the following command in a third terminal:
-
-```bash
-ros2 launch scenario_execution scenario_launch.py scenario:=examples/example_multi_robot/example_multi_robot.osc
+ros2 launch tb4_sim_scenario sim_nav_scenario_launch.py scenario:=examples/example_multi_robot/example_multi_robot.osc
 ```
 
 For a more detailed understanding of the code structure and scenario implementation please refer to the [tutorial documentation](https://intellabs.github.io/scenario_execution/tutorials.html).