Copreus 0.4.0
This library provides a framework to write device drivers for the raspberry pi that are connected to MQTT.
License: MIT license
Keywords: mqtt device driver rpi raspberry pi

In Greek mythology, Copreus (Κοπρεύς) was King Eurystheus' herald. He
announced Heracles' Twelve Labors.
[`wiki <https://en.wikipedia.org/wiki/Copreus>`__]

This library provides a framework to write a device driver for the
raspberry pi that are connected to MQTT.

Thus, Copreus takes commands from the king (MQTT) and tells the hero
(device) what it labors are. Further, Copreus reports to the king
whatever the hero has to tell him.

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

   Pelops Overview

``Copreus`` 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 RPi.GPIO pelops

Install via pip:

::

    sudo pip3 install copreus

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/copreus.git
    cd copreus
    sudo python3 setup.py install

This will install the following shell scripts: \* ``copreus`` - alias
for ``copreus_drivermanager`` \*
```copreus_drivermanager`` <https://gitlab.com/pelops/copreus/wikis/devicemanager-devicemanager>`__
- driver manager can instantiate several driver \*
```copreus_adc`` <https://gitlab.com/pelops/copreus/wikis/drivers-adc>`__
- analog digital converter via spi \*
```copreus_bme280`` <https://gitlab.com/pelops/copreus/wikis/Drivers-bme_280>`__
- bosch bme280 sensor via SMBus \*
```copreus_dac`` <https://gitlab.com/pelops/copreus/wikis/drivers-dac>`__
- digital analog converter via spi \*
```copreus_dht`` <https://gitlab.com/pelops/copreus/wikis/drivers-dht>`__
- DHT11/DHT22/AM2302 \*
```copreus_epaperdirect`` <https://gitlab.com/pelops/copreus/wikis/drivers-epaperdirect>`__
- Waveshare e-Papers 1.54inch/2.13inch/2.9inch via spi - \*
```copreus_epapersimple`` <https://gitlab.com/pelops/copreus/wikis/drivers-epapersimple>`__
- Waveshare e-Papers 1.54inch/2.13inch/2.9inch via spi \*
```copreus_input`` <https://gitlab.com/pelops/copreus/wikis/drivers-input>`__
- generic gpio input \*
```copreus_output`` <https://gitlab.com/pelops/copreus/wikis/drivers-output>`__
- generic gpio output \*
```copreus_rotaryencoder`` <https://gitlab.com/pelops/copreus/wikis/drivers-rotaryencoder>`__
- rotary encoder like ky-040 with software solutions for debouncing and
direction detection. \*
```copreus_rotaryencoder2`` <https://gitlab.com/pelops/copreus/wikis/drivers-rotaryencoder2>`__
- rotary encoder like ky-040 together with schmitttriggers for
debouncing and a flipflop for direction detection in hardware.

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

Additional Prerequisites for Drivers
------------------------------------

Some drivers like ``Input`` and ``Output`` don't need additional
packages. The others need additional prerequisites to be used (they will
be installed without them).

``ADC`` and ``DAC``
~~~~~~~~~~~~~~~~~~~

::

    sudo pip3 install spidev

``bme280``
~~~~~~~~~~

::

    sudo pip3 install smbus2 RPi.bme280

``DHT``
~~~~~~~

::

    sudo apt install build-essential python-dev
    git clone https://github.com/adafruit/Adafruit_Python_DHT.git
    cd Adafruit_Python_DHT
    sudo python3 setup.py install

``epaperdirect``
~~~~~~~~~~~~~~~~

::

    sudo apt install libopenjp2-7 libtiff5
    sudo pip3 install spidev Pillow

``epapersimple``
~~~~~~~~~~~~~~~~

::

    sudo apt install libopenjp2-7 libtiff5
    sudo pip3 install spidev Pillow

Install Everything at Once
--------------------------

::

    sudo apt install python3 python3-pip build-essential python-dev libopenjp2-7 libtiff5
    sudo pip3 install RPi.GPIO paho-mqtt pyyaml spidev Pillow smbus2 RPi.bme280 pelops
    git clone https://github.com/adafruit/Adafruit_Python_DHT.git
    cd Adafruit_Python_DHT
    sudo python3 setup.py install
    cd ..
    sudo pip3 install copreus

Further ubuntu and python packages may be needed by example and tests.
For example, ``test_epaper.py`` requires that the ubuntu package
``fonts-freefont-ttf`` is installed.

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

A yaml file must contain two 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 - logger
configuration. log level and output file. \* driver or drivers. drivers
is a list of driver entries with two additional parameters per driver:
active and name. a driver entry contains at least (driver implementation
might add additional ones): type, name, topic-pub (list of key/value
pairs), and topic-sub (list of key/value pairs).

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).

Examples
~~~~~~~~

Config for Driver ``Input``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Can be started with ``copreus_input -c config.yaml -v``. More
information in the
`wiki <https://gitlab.com/pelops/copreus/wikis/drivers-input>`__.

config.yaml:

::

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

    logger:
        log-level: DEBUG
        log-file: copreus.log  

    driver:
        type: input
        pin:  23
        topics-pub:
            button_pressed: /test/button/pressed
            button_state:   /test/button/state
        mqtt-translations:
            button_pressed: PRESSED
            button_state-open: OPEN
            button_state-closed: CLOSED        

credentials.yaml:

::

    mqtt:
        mqtt-user: user
        mqtt-password: password

Config for ``DriverManager``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Can be started with ``copreus -c config.yaml -v``. More information at
`wiki <devicemanager-devicemanager>`__,
`wiki <https://gitlab.com/pelops/copreus/wikis/drivers-input>`__, and
`wiki <https://gitlab.com/pelops/copreus/wikis/drivers-output>`__.

config.yaml:

::

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

    logger:
        log-level: DEBUG
        log-file: copreus.log
        
    drivers:
        - name: button1 
          type: input
          pin:  23
          topics-pub:
              button_pressed: /test/button/pressed
              button_state:   /test/button/state
          mqtt-translations:
              button_pressed: PRESSED
              button_state-open: OPEN
              button_state-closed: CLOSED   
          active: true       
        - name: led1
          type: output
          pin: 21
          initially-closed: false
          physical-closed: low      
          topics-sub:
              closed: /test/closed
          mqtt-translations:
              closed-true: ON
              closed-false: OFF
          active: false          

credentials.yaml:

::

    mqtt:
        mqtt-user: user
        mqtt-password: password

systemd
-------

-  add systemd example.

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

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

The project consists of three main packages: \* ``baseclasses`` -
``ADriver`` and additional base- and utilityclasses \* ``drivermanager``
- ``DriverManager`` and ``DriverFactory`` \* ``drivers`` - all
implemented driver

Each driver must be a silbiling of ``ADriver``. A new driver must be
added to the ``DriverFactory``, ``drivers.__init__.py``, ``setup.py``
and ``README.md``. Further, config example must be placed in /tests.

A good starting point is to look at the two generic driver ``Ìnput`` and
``Output`` as well as ``DHT``.

Additional Dependencies
-----------------------

Next to the dependencies listed above, you need to install the
following:

::

    sudo apt install pandoc
    sudo pip3 install pypandoc

Todos
-----

-  Add more driver
-  SMBus base class
-  ...

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/copreus/merge_requests>`__ /
`bug reports <https://gitlab.com/pelops/copreus/issues>`__ are always
welcome.