.. _`tp2/controller`:

KogniDoor-Controller
====================

:Kontakt: Alexander Neumann <alneuman@techfak.uni-bielefeld.de>
:CITK: `kognihome-doorcontroller <https://opensource.cit-ec.de/projects/citk/repository/revisions/master/entry/projects/kognihome-doorcontroller.project>`_
:Vorbedingung:

    Die KogniHome-Variane von :ref:`guides/rst` wird benötigt, sowie die Python-Pakete ``rsbhsm``, welches jedoch bei
    der Installation mit ``setuptools`` bei Bedarf nachinstalliert wird. Diese Pakete müssen über den ``PYTHONOPATH``
    verfügbar sein.

:Quickstart:

    ``doorcontroller`` benötigt keine weiteren Parameter::

        $ doorcontroller

RSB-Schnittstellen
------------------

.. rsbpubsub:: IN /io/emr/bluetooth/outside rst.door.BluetoothInfo Authentifiziert BLE-Advertising
.. rsbpubsub:: IN /io/emr/bluetooth/inside rst.door.BluetoothInfo Authentifiziert BLE-Advertising
.. rsbpubsub:: IN /service/detection/knock rst.door.KnockStatus Klopfen an der Tür
.. rsbpubsub:: IN /io/actor/lock/status rst.door.LockStatus Status des Türschlosses
.. rsbpubsub:: IN /io/actor/motor/status rst.door.MotorStatus überwacht Motorfahrt
.. rsbpubsub:: IN /service/detection/openingobstacle bool stoppt Motor bei erkanntem Hindernis
.. rsbpubsub:: IN /service/detection/closingobstacle bool stoppt Motor bei erkanntem Hindernis
.. rsbpubsub:: IN /io/emr/radar rst.door.RadarStatus reagiert auf Personen in der Nähe der Tür
.. rsbpubsub:: IN /io/emr/reed rst.door.ContactStatus Überwacht Öffnungszustand der Tür
.. rsbpubsub:: IN /service/door/checkout int Zeigt Erinnerung, falls beim Verlassen des
    Hauses kein Beacon des Nutzers mit ID <int> detektiert wird. Öffnet die Tür automatisch,
    wenn das Beacon in Reichweite kommt.
.. rsbpubsub:: IN /service/door/response rst.kognihome.UserNotification reagiert auf Nutzereingaben
    wenn Nachrichten angezeigt worden sind.

.. rsbpubsublist::
    :type: IN

.. rsbpubsub:: OUT-Intern /io/control/bluetooth/outside bool Aktiviert/Deaktiviert den Ble-Grabber
.. rsbpubsub:: OUT-Intern /io/control/bluetooth/inside bool Aktiviert/Deaktiviert den Ble-Grabber
.. rsbpubsub:: OUT-Pub-1 /service/door/controller/status string Sendet den Namen des aktuellen States

.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/file string Pfad zu einer monochromen Bilddatei
.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/file/1 string .. konkret für Buffer 1
.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/file/2 string .. konkret für Buffer 2
.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/file/3 string .. konkret für Buffer 3

.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/html string HTML-Inhalt zur Anzeige an der Tür
.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/html/1 string .. konkret für Buffer 1
.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/html/2 string .. konkret für Buffer 1
.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/html/3 string .. konkret für Buffer 1

.. rsbpubsub:: OUT-Pub-1 /io/vision/eink/refresh bool zeigt nächsten Buffer an
.. rsbpubsub:: OUT-Pub-1 /io/vision/eink/refresh/1 bool zeigt Buffer 1 an
.. rsbpubsub:: OUT-Pub-1 /io/vision/eink/refresh/2 bool zeigt Buffer 2 an
.. rsbpubsub:: OUT-Pub-1 /io/vision/eink/refresh/3 bool zeigt Buffer 3 an

.. rsbpubsub:: OUT-Pub-0 /io/vision/eink/backlight/set rst.door.LEDStrip setzt eInk-Beleuchtung
.. rsbpubsub:: OUT-Pub-0 /io/vision/led/rgba rst.vision.Color setzt LED-Zargenfarbe
.. rsbpubsub:: OUT-Pub-0 /io/vision/led/ir int setzt IR-LED-Intensität in der Zarge
.. rsbpubsub:: OUT-Pub-1 /io/actor/lock/get bool Fragt Schlossstatus ab
.. rsbpubsub:: OUT-Pub-1 /io/actor/lock/set rst.door.LockStatus Öffnet Schloss
.. rsbpubsub:: OUT-Pub-1 /io/actor/motor/set rst.door.MotorStatus Fährt Motor auf und zu

.. rsbpubsub:: OUT-Pub-1 /kognidoor/io/display/model/notification rst.kognihome.UserNotification Sendet Erinnerungsnachricht bei checkout


.. rsbpubsublist::
    :type: OUT


.. rsbrpc:: CALLS /service/kognidb/ register_app string string Registriert Anwendung 'door'
.. rsbrpc:: CALLS /service/kognidb/door get_user_tokens int rst.kognihome.db.IdentificationTokens Fragt mögliche Identifizierungstokens an, um sicherzustellen,
    dass beim Verlassen des Hauses Nutzer mit der ID <int> ein valides Token mit sich führen

.. rsbrpclist::
    :type: CALLS


FSM-Logik
---------

Um auf Ereignisse angemessen reagieren zu können, ist ``doorcontroller`` als
:term:`State Machine` bzw. endlicher Automat konzipiert. Zu jedem Zeitpunkt wird einer
der folgenden Status angenommen:

:Initial: Der Zustand wird während der Initiliesierung eingenommen und danach sofort verlassen.
:AccessDenied: Wir nach einem fehlgeschlagenen Authentifizierungsversuch betreten.
:BlockedInside: Wenn die Tür aufgrund eines Hindernisses auf der Innenseite der Tür nicht Öffnen kann.
:BlockedOutside: Wenn aufgrund eines Hindernisses beim Zufahren der Tür Einklemmen droht.
:CLosingDoor: Während die Tür automatisch zugefahren wird.
:DetectBeacon: Es wird für die Authentifizierung auf ein Token/Beacon gewartet.
:DetectPerson: Platzhalter-Status für weitere Detektionsschritte. Wird im Moment sofort wieder (erfolgreich) verlassen.
:DoorClosed: Die Tür gilt als geschlossen.
:DoorLockedAndClosed: Die Tür wird als geschlossen und verriegelt angenommen.
:DoorNotClosed: Die Tür ist (zumindest einen Spalt weit) offen.
:LockLock: Schließt das Türschloss.
:LockUnlock: Entriegelt das Türschloss.
:OpeningAutomatic: Fährt die Tür auf.
:OpeningManual: Wartet auf manuelle Öffnung der Tür oder (wie momentan konfiguriert) leitet den Übergang zum automatischen Öffnen ein.
:PendingCheckout: Eine Person hat das Verlassen des Hauses angekündigt. Die Tür wartet auf weitere Ereignisse, um zu Öffnen.

Funktionslose Status
^^^^^^^^^^^^^^^^^^^^

Einige Status wurden konzipiert, sind jedoch bisher nicht in die Kontrolllogik integriert:

:PersonEngage: Löst eigeninitiativ Aktionen aus, um Personen vor der Tür anzusprechen.
:PersonPresent: Wird eingenommen, wenn eine Person sich vor der Tür aufhält, aber keine weiteren Ereignisse auslöst.
:RecordMessage: Aufnahme eine Sprach-/Videonachricht bei Abwesenheit der Bewohner.
:WaitingForResponse: Wird nach dem Klopfen eingenommen, wenn ein Bewohner benachrichtigt wird.
  Dieser Schritt ist obsolet, da Klopfereignisse direkt an den Nutzer mitteln Smartphone-App übermittelt werden.

Aktueller Stategraph
^^^^^^^^^^^^^^^^^^^^

.. figure:: images/doorcontroller.svg
    :width: 90%