..  _coordination:

Component Coordination
======================

.. _TaskState: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-communicationpatterns.html#rst.communicationpatterns.TaskState
.. _ResourceAllocation: http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-communicationpatterns.html#rst.communicationpatterns.ResourceAllocation
.. _Ini files: https://en.wikipedia.org/wiki/INI_file#Format

While in the apartment's architecture every component can trigger each other component,
there is also the possibility to exhibit behaviors in a cooridnated matter. For that purpose,
there are a number of coordination services.

All of these services allow for exclusive access to interactive functionality by using the
:ref:`allocation` that is able to assign resources to components sequentially based on priorities.
Furthermore, all coordination components can be triggered via the listener/informer mechanism.
Thereby, they are able to monitor the request and report it back to the component that triggered it
by following the `TaskState`_ communication pattern (cf. :ref:`tasks`). In particular, only `TaskState`_
objects are regarded as valid input. Additionally, requesters are informed about the scenario's
status also on that scope with `TaskState`_ objects that use the initial request's event id as a
cause id. As an alternative trigger, there is a :ref:`buttons` inside the apartment that can be used to
initiate scenes, scenarios, or tasks.

There are three different coordination services that provide interfaces to apartment functions on separate interactive levels:

================ ==============
Service          Description
================ ==============
:ref:`scenes`    (static) configurations of the apartment's infrastructure
:ref:`scenarios` interactive routines with a certain extent
:ref:`tasks`     (simple) short-lived services or (other component's) functions
================ ==============

`Ini files`_ are used to configure these three main coordination services :ref:`scenes`, :ref:`scenarios`,
and :ref:`tasks`. They specify which resources they occupy at the :ref:`resources` and how they communicate
with other components inside the apartment. See each component's documentation for a list of allowed values.

Shared repository for coordination components (except :ref:`allocation`):
 - web: `scenario-coordination-cfg <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/scenario-coordination-cfg/>`_
 - ``git clone https://projects.cit-ec.uni-bielefeld.de/git/lsp-csra.scenario-coordination-cfg.git/``

System startup:
 - web: `system-startup <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/system-startup>`_
 - ``git clone https://projects.cit-ec.uni-bielefeld.de/git/lsp-csra.system-startup.git/``
 - All coordination components can be found in ``lsp-csra-base.sh`` on the ``coordination`` tab:
  - ``component_allocation-service``
  - ``component_scenario-service``
  - ``component_scene-service``
  - ``component_task-service``
  - ``component_button-service``

.. toctree::
   :caption: Coordination-related components
   :maxdepth: 2

   coordination/resources
   coordination/scenes
   coordination/scenarios
   coordination/tasks
   coordination/buttons