..  _scenes:

Scene Configuration
===================

.. _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 scene configuration service can be used to put the apartment into a certain mode, aka scene. Scenes can be set
up by sending `TaskState`_ objects to the following scope: ``SCOPE_SCENE=/coordination/request/scene/<ID>``
(for examples see :ref:`tasks`), or by using the :ref:`buttons`. The scene service internally uses the :ref:`allocation`
for the arbitration of possibly conflicting scene layouts and only sets up a scene if it can allocate all needed resources.

Apartment scenes are defined as a set of configuration commands that are issued duringe the initial setup of each scene.
After initialization, the scene service keeps the configured resources allocated for a certain amount of time in order
to prevent external components from altering the intended design. For each scene, there is a configuration file that
specifies needed resources and configuration commands that could be an informer message, rpc call, or `TaskState`_ communication.

Scene settings typically involve a home-automation configuration, robot scenario, display content, and music playlist (or silence).
Furthermore, scenes can define :ref:`tasks <tasks>` and :ref:`scenarios <scenarios>` that are allowed to share allocated resources,
so that they can be executed while the scene is active even though they access the same resources.

Available scenes
----------------

Currently, the following scenes are available:

.. figure:: /images/coordination/Scenes.png
    :width: 650px
    :figclass: align-center
    :alt:   Available scenes in the apartment


Scene specification
-------------------

All available scenes are read from a configuration file that resides inside the
`main coordination repository <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/scenario-coordination-cfg/>`_.
If you want to add a new scene, you have to create a new `Ini file`_ containing an optional **[resources]** and a number of **[remote:<ID>]**
sections. These files are evaluated at runtime and trigger the remotes in chronological order after the resources have been
allocated sucessfully. Several remotes can be specified as inofmer, task, or rpc and given a payload. The following code-block illustrates
an example scene with the default resources that are allocated for scenes, a remote, and two allowed scenarios that are referenced
by their name. A home-automation scene with the same name is triggered automatically with each scene to configure the apartments
devices and thus does not have to be configured explicitly. Please refer to :ref:`resource_ini` for an overview of allowed values
for the **[resources]** section.

.. code-block:: INI

    [resources]
    ; these are the default values for scene resources
    policy=PRESERVE
    priority=HIGH
    initiator=HUMAN
    duration=600000
    ids=/coordination/request/scene/
    description="scene: <ID>"

    [remote:silence]
    ; these are the default values for delay/timeout
    delay=0
    timeout=5000
    type=rpc
    scope=/home/audio/control/manager/stop
    payload="my life for aiur!"

    [remote:something]
    type=informer
    scope=/someother/interval/
    payload=".rst.timing.Interval:{begin:{time:10000}end:{time:120000}}"

    [scenarios]
    learn=true
    register=true

A **[remote]** section specifies an interaction with another component via `TaskState`_,
remote procedure call (rpc), or simple message (informer). Types, scopes, and payloads are mandatory for a remote seciton.
The **scope** field has to follow the RSB `Scope`_ definition. The **type** field can be any of *task*, *rpc*, or *informer*.
The **payload** are evaluated as numbers, booleans, or `RST`_  data types. Additionally, all these parameters can be overridden
by using a `Dictionary`_ as the `TaskState`_ payload when requesting a scene. **delay** and **timeout** fields are optional,
default to *0* and *5000*, and are evaluated as millisecond values.

In contrast to :ref:`tasks <tasks>`, in scenes multiple remote sections can be specified. Each remote has to be referenced by a
unique identifier in the section name, seperated by a colon, i.e., **[remote:<ID>]**.

In the **[scenarios]** and **[tasks]** sections, :ref:`scenarios <scenarios>` or :ref:`tasks <tasks>` that do not conflict with
the scene (and thus are allowed to execute during the scene) can be specified. The scenario's or task's name acts as a key and a
*true* or *false* value define whether the scenario is accepted or not during the scene's activation.


Scenes and their effects 
------------------------


**Party**

- party pictures are displayed with projector and on TV
- sun-blinds down
- loud music
- alternating light


**Debug**

- Grafana is displayed on TV
- map is displayed with projector
- mikrophone amplitudes are displayed with projector
- between-ceiling light is on 
- music is turned off 
- all lights (and handles) are on and white


**Meeting**

- calender is displayed on TV
- CITEC logo (or rather nothing distracting) is displayed with projector
- music is turned off 
- all lights (and handles) are on and white 


**Reading**

- pictures are displayed with projector and on TV
- relaxing music is turned on
- warm/cozy light is on
- sofa lamp is on


**Socializing**

- youtube channel is shown on TV
- funny pictures are displayed with projector
- lights are normal


**Cinema**

- video is shown on TV
- picture is displayed with projector
- sun-blinds down
- lights in living room are switched off (dimmed everywhere else) 


**Demo**

- map is shown with projector
- Flobi is visible and responsive


**Studies**

- study (results) are displayed on TV