=============
Introduction
=============

Context
--------
We were asked to monitor Deustotech's power consumption.
We needed to gather the energy usage of each workplace,
as well as conference rooms and printers power waste.

These were all the requirements:

- Monitoring of work place sockets, meeting rooms and printers (meeting rooms and offices we treat them the same).

- Data storage in Influx.

- Specification of the monitored devices, using well-defined identifiers and their locations in Deustotech.

- System and code documentation in Read The Docs.

- RESTful API implementation and specification for data queries.

- RESTful API implementation and specification for device control (turn off, on).

- Specification and documentation of Hooks [#]_ to facilitate integration with different devices and middlewares.

- Implementation of error alerts.

- Backup mechanism implementation.


.. [#] Hook: techniques used to alter or increase the behavior of
  an operating system, applications or other software components
  by intercepting function calls or messages or events passed
  between software components

Proposed solution
-------------------
As a result we created an IoT system where each workplace,
group room and printer is plugged to an SmartPlug_.

.. _SmartPlug: https://www.tp-link.com/en/home-networking/smart-plug/hs110/

The gathered data is stored in a time series database: influxDB.

Also a RESTful API is exposed through which the data can be retrieved, and
SmartPlugs are controlled: turned ON/OFF.

System's overview
------------------
The system architecture is shown in the following diagram:

.. image:: _static/imgs/system-architecture.svg


* **API**: Abstracts data queries and control requests into a
  REST API web server. The API specifications are presented in
  :doc:`API Usage <usage>`. Behind the scenes it is simple its implementation:
  it receives a REST request, it formats the message, and
  it publishes to MQTT, where a *Component* executes the query.
  Finally, it waits for the *Component* response, which is published
  in another MQTT topic.

* **Component**: It is the application that subscribes to a specific
  MQTT topic, where receives data queries. It responsible of
  executing the queries; usually this means to look up in a
  Database. Once the query is executed, it publishes the
  result to a MQTT topic where the *API* is listening.

* **Hook**: It is responsible of reading from an MQTT topic
  the data generated by the devices and taking care of it.
  For example, in case of the SmartPlugs, it stores them into
  InfluxDB database.

* **Agent**: It is the middleware that deals with the devices
  directly. Agents can be classified into two groups: controllers
  and collectors. The controllers send commands to the devices,
  such as "turn ON/OFF". And the collectors are responsible of
  retrieving the data from the devices. Both of them use MQTT
  as the communication techonolgy with other components or
  applications.

Request flow: Influx query
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Client makes HTTP request to :code:`api` and :code:`api` publishes influx query to MQTT
2. :code:`influx_query` reads the command from MQTT
3. :code:`influx_query` sends query to InfluxDB
4. InfluxDB executes query and returns the result to :code:`influx_query`
5. :code:`influx_query` publishes the result to MQTT
6. :code:`api` reads query result from MQTT and returns an HTTP response

.. image:: _static/imgs/flow-influx-query.svg


Request flow: SmartPlug command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Client makes HTTP request to :code:`api` and :code:`api`
   publishes control command to MQTT
2. :code:`sp_command` reads the command from MQTT 
3. :code:`sp_command` sends command to the SmartPlug device(s)
4. SmartPlug executes the command and :code:`sp_command` reads the resonse
5. :code:`sp_command` publishes the response to MQTT
6. :code:`api` reads control command response from MQTT and returns an HTTP response

.. image:: _static/imgs/flow-sp-command.svg