Eurydike 0.1.8
Eurydike is a simple event detection. Reacts to above-threshold, below-thershold, and outside value-band.
License: MIT license
Keywords: mqtt device driver rpi raspberry pi

Εὐρυδίκη/Eurydike
[`wiki <https://de.wikipedia.org/wiki/Eurydike_(Tochter_des_Pelops)>`__]
is a simple event detection. Reacts to above-threshold, below-threshold,
and outside value-band.

.. figure:: img/Microservice%20Overview.png
   :alt: Pelops Overview

   Pelops Overview

``Eurydike`` is part of the collection of mqtt based microservices
`pelops <https://gitlab.com/pelops>`__. An overview on the microservice
architecture and examples can be found at
(http://gitlab.com/pelops/pelops).

For Users
=========

Installation Core-Functionality
-------------------------------

Prerequisites for the core functionality are:

::

    sudo apt install python3 python3-pip
    sudo pip3 install paho-mqtt pyyaml pelops

Install via pip:

::

    sudo pip3 install eurydike

To update to the latest version add ``--upgrade`` as prefix to the
``pip3`` line above.

Install via gitlab (might need additional packages):

::

    git clone git@gitlab.com:pelops/eurydike.git
    cd eurydike
    sudo python3 setup.py install

This will install the following shell scripts: \* ``eurydike``

The script cli arguments are: \* '-c'/'--config' - config file
(mandatory) \* '-v' - verbose output (optional) \* '--version' - show
the version number and exit

YAML-Config
-----------

A yaml [1]_ file must contain four root blocks: \* mqtt - mqtt-address,
mqtt-port, and path to credentials file credentials-file (a file
consisting of two entries: mqtt-user, mqtt-password) \* logger - which
log level and which file to be used \* eventdetectors - parameters for
the controller and the embedded pid

::

    mqtt:
        mqtt-address: localhost
        mqtt-port: 1883
        credentials-file: ~/credentials.yaml
        log-level: INFO

    logger:
        log-level: DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL
        log-file: test_eurydike.log

    eventdetectors:
        - name: above  # unqiue name for event detector
          type: onthreshold  # detector type identifier
          comparator: gt  # GREATERTHAN/GT/>, LOWERTHAN/LT/<, EQUALTO/==
          threshold: 7  # threshold in combintation with comparator and value from topic-sub
          topic-sub: /test/value
          topic-pub: /test/above
          responses:  # leave value empty or remove line for no response
    #          on-violation: event_detected  # on detection of a threshold violation send this value to topic-pub
              on-restoration: event_ended  # on the event of returning to valid values send this value to topic-pub
          active: False  # entry ignored if set to False

        - name: below  # unqiue name for event detector
          type: onthreshold  # detector type identifier
          comparator: lowerthan  # GREATERTHAN/GT/>, LOWERTHAN/LT/<, EQUALTO/==
          threshold: 7  # threshold in combintation with comparator and value from topic-sub
          topic-sub: /test/value
          topic-pub: /test/below
          responses:  # leave value empty or remove line for no response
              on-violation: event_detected  # on detection of a threshold violation send this value to topic-pub
              on-restoration: event_ended  # on the event of returning to valid values send this value to topic-pub
          active: True  # entry ignored if set to False

        - name: equal  # unqiue name for event detector
          type: onthreshold  # detector type identifier
          comparator: ==  # GREATERTHAN/GT/>, LOWERTHAN/LT/<, EQUALTO/==
          threshold: 7  # threshold in combintation with comparator and value from topic-sub
          topic-sub: /test/value
          topic-pub: /test/equal
          responses:  # leave value empty or remove line for no response
              on-violation: event_detected  # on detection of a threshold violation send this value to topic-pub
              on-restoration:  # on the event of returning to valid values send this value to topic-pub
          active: False  # entry ignored if set to False

        - name: outside  # unqiue name for event detector
          type: onband  # detector type identifier
          upper-threshold: 8  # upper threshold for on band detection
          lower-threshold: 7  # lower threshold for on band detection
          topic-sub: /test/value
          topic-pub: /test/band
          responses:  # leave value empty or remove line for no response
              on-violation: event_detected  # on detection of a threshold violation send this value to topic-pub
              on-restoration: event_ended  # on the event of returning to valid values send this value to topic-pub
          active: True  # entry ignored if set to False

systemd
-------

-  add systemd example.

For Developers
==============

Getting Started
---------------

The project consists of two main modules:

-  ``eventdetectionmanager`` - manages all configured event detectors
-  ``abstracteventdetector`` - base class for all event detectors

Todos
-----

-  ... ?

Misc
----

The code is written for ``python3`` (and tested with python 3.5 on an
Raspberry Pi Zero with Raspbian Stretch).

`Merge requests <https://gitlab.com/pelops/eurydike/merge_requests>`__ /
`bug reports <https://gitlab.com/pelops/eurydike/issues>`__ are always
welcome.

.. [1]
   Currently, pyyaml is yaml 1.1 compliant. In pyyaml On/Off and Yes/No
   are automatically converted to True/False. This is an unwanted
   behavior and deprecated in yaml 1.2. In copreus this autoconversion
   is removed. Thus, On/Off and Yes/No are read from the yaml file as
   strings (see module baseclasses.myconfigtools).