.. _scenarios: Scenario Coordination ===================== .. _TaskState: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-communicationpatterns.html#rst.communicationpatterns.TaskState .. _Dictionary: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-generic.html#rst.generic.Dictionary .. _RST: http://docs.cor-lab.de//rst-manual/trunk/html/index.html .. _Ini file: https://en.wikipedia.org/wiki/INI_file The scenario coordination service can be used to trigger and arbitrate various interactive subroutines of the apartment, aka scenarios. Scenarios can be executed by sending `TaskState`_ objects to the following scope: ``SCOPE_SCENARIO=/coordination/request/scenario/`` (for examples see :ref:`tasks`), or by using the :ref:`buttons`. The scenario coordination internally uses the :ref:`allocation` for the arbitration of parallel interactions and only executes a scenario if it can allocate all needed resources. Interactive scenarios are modeled as SCXML state-machines that can be generated with a set of domain-specific languages, executed with an rsb-aware executor (see related components) and vizualized with the :ref:`state_engine_viewer` which is part of the coordination. For each scenario, there is a configuration file that specifies default runtime parameters and needed resources. Related resources ----------------- The scenario coordination (historically) shares a repository with the :ref:`auto_recording`. As they both are SCXML state-machines, they are started with the same executable and vdemo component but with a different (xml) configuration file. Furthermore, they share the same visualization, called :ref:`state_engine_viewer`. Related projects: - DSL IDE project: `rsb-dsl `_ - SCXML Executor: `rsb-scxml-engine `_ Available scenarios ------------------- Currently, the following scenarios can be triggered: ================== ================================================ =================== ID Requested routine/scenario Involved components ================== ================================================ =================== ``cleanup`` kitchen interaction (offer drink, then clean) :ref:`dialog_manager` ``email`` remember e-mail address (associate with id-card) :ref:`long_term_memory` ``fsmt`` run all fsm tests *jenkins* ``lastname`` remember last name (associate with id-card) :ref:`long_term_memory` ``learnface`` remember a person's face (learn face model) *face id* ``mekagrasp`` tell meka bot to perform grasping demonstration *meka robot* ``mekaintro`` call meka bot to introduce the apartment *meka robot* ``register`` register new id-card, store given name in ltm :ref:`long_term_memory` ``reset`` reset apartment (legacy, use default scene) *-* ================== ================================================ =================== Scenario specification ---------------------- Scenarios are specified as SCXML files that can described in MPS. A set of `domain-specific languages `_ that cover SCXML, plantUML, and RSB is used to generate files that are then executed by the `rsb-scxml-engine `_. For development using the DSLs, an `IDE `_ used to be available but is not usable at the moment. Instead, the set of languages has to be opened in MPS prior to opening the coordination model. An archive containing the correct versions can be found `here `_. Scenario configuration ---------------------- All available scenarios are read from a configuration file that resides inside the `main coordination repository `_. If you want to add a new scenario, you have to create a new `Ini file`_ containing an optional **[resources]** and a **[parameters]** section. These files are evaluated at runtime and trigger the SCXML state-machine specified in the parameters section after the resources have been allocated sucessfully. Additional variables can be specified as parameters and are fed into the datamodel of the SCXML file before execution. Please refer to :ref:`resource_ini` for an overview of allowed values for the **[resources]** section.The following default values for scenario resources are taken into account but can be overridden: .. code-block:: INI [resources] ; these are the default values for scenario resources policy=PRESERVE priority=HIGH initiator=HUMAN duration=600000 ids=/coordination/request/scenario/ description="scenario: " [parameters] ; default (filenames are case-sensitive and start with a capital letter) scxml=.xml ; the following are not default values but parameter examples feedback=true location=Kitchen example=".rst.dialog.DialogManagerCommand:{command:RESET_INTERACTION}" Inside the **[parameters]** section, a state-machine that should be executed can be specified using the **scxml** key. Furthermore, arbitrary key/value pairs can be specified to be stored inside the SCXML data model. Values are evaluated as numbers, booleans, or `RST`_ data types. Additionally, these parameters can be overridden by using a `Dictionary`_ as the `TaskState`_ payload when requesting a scenario. Some scenarios have a **feedback** parameter that enables text-to-speech output at ``/home//saytask/SAY`` in case the scenario has not been triggered verbally via the :ref:`dialog_manager`. Also, some scenarios use the **location** field to trigger a virtual keyboard by calling ``/home//virtualkeyboard/command`` or set a location's illumination using ``/home/locationlight/(power|preset)``. Details can be found in the respective SCXML files. Execution properties -------------------- An ABORTED signal is sent to the execution engine if allocated resources are lost, the state-machine should enter a final state with the name TaskState::Aborted as soon as possible. In total, there are are the following special states that are evaluated by the scenario coordination that resemble the `TaskState`_ communication pattern (cf. :ref:`tasks`): ==================== ================================= ============== State Meaning Properties ==================== ================================= ============== TaskState::Rejected Scenario execution refused *final* TaskState::Accepted Scenario execution started *-* TaskState::Completed Scenario finished successfully *final* TaskState::Failed Scenario finished with an error *final* TaskState::Aborted Scenario aborted externally *final* (e.g., resources superseded) ==================== ================================= ==============