.. include:: _resources.rst
.. _mqttwarn-alerts:
###########################
Schwarmalarm using mqttwarn
###########################
************
Introduction
************
mqttwarn
========
`mqttwarn`_ is a great tool by `Jan-Piet Mens`_ and `Ben Jones`_.
For an intro, please have a look at `Introducing mqttwarn, a pluggable MQTT notifier`_
or `MQTTwarn, Ein Rundum-Sorglos-Notifier`_ (german).
Kudos to Jan-Piet and Ben for conceiving this, it is an exceptional
powerful and versatile swiss-army knife style tool.
We are using mqttwarn as an alerting and notification subsystem,
started adding foundation functionality a while ago (`incorporate topic names into topic targets`_)
and finally managed to provide a simple yet complete implementation for delivering
alert notifications to beekeepers based on measurement data arriving on the MQTT_ bus.
Read on, my dear.
Weight-loss events
==================
Beekeepers usually want to know their colony is swarming, to come catch it back
to their own beehives. To get a feeling about what we are after, a picture is
worth a thousand words:
.. raw:: html
This is a weight-loss event from :ref:`hiveeyes-scale-beutenkarl`
recorded on May 20, 2016 between 10:11 and 10:26 hours CEST after a
bee colony started swarming at the
:ref:`Hiveeyes labs beehive ` in Berlin Wedding.
.. _data-loss events:
Data-loss events
================
As a matter of fact, batteries are always draining. If capacity is too low
and sensor nodes stop transmitting due to shortage on power, a software
watchdog with a configurable timeout will recognize and notify beekeepers
about data-loss events.
*****
Setup
*****
While we are operating an instance of this setup on our :ref:`Hiveeyes platform`,
you can always setup an instance on your own machine.
Installation
============
.. highlight:: bash
Setup dependencies::
pip install xmpppy==0.5.0rc1 jinja2==2.8
Setup mqttwarn::
git clone https://github.com/jpmens/mqttwarn
cd mqttwarn
Configuration
=============
.. highlight:: ini
Please configure ``examples/hiveeyes/hiveeyes.ini`` accordingly.
MQTT
----
Use the MQTT broker ``swarm.hiveeyes.org``::
[defaults]
hostname = 'swarm.hiveeyes.org'
Notification targets
--------------------
For setting up notification targets, please configure the left-hand side
of the ``targets`` mapping to match your Hiveeyes user identifier UUID
(here: "testdrive" for demonstration purposes) and the right-hand side
to match email or xmpp addresses of your choice.
Setup email notification delivery::
[config:smtp]
server = 'localhost:25'
sender = "hiveeyes-alerts "
username = None
password = None
starttls = False
targets = {
'testdrive' : ['testdrive@beekeepersclub.org'],
}
Setup XMPP notification delivery (you have to register an XMPP account first)::
[config:xmpp]
sender = 'hiveeyes@xmpp.beekeepersclub.org'
password = 'yourcatsname'
targets = {
'testdrive' : ['testdrive@xmpp.beekeepersclub.org'],
}
***
Run
***
.. highlight:: bash
Run mqttwarn::
export MQTTWARNINI=examples/hiveeyes/hiveeyes.ini
./mqttwarn.py
****
Test
****
Trigger an alarm by simulating a weight loss event::
echo '{"wght2": 43.0}' | mosquitto_pub -h swarm.hiveeyes.org -t hiveeyes/testdrive/area-42/beehive-1/data.json -l
echo '{"wght2": 42.0}' | mosquitto_pub -h swarm.hiveeyes.org -t hiveeyes/testdrive/area-42/beehive-1/data.json -l
You should be seeing and receiving an alert message like::
2016-05-30 14:47:47,692 CRITICAL [log] Alarm from beehive beehive-1.
------------------------------------------
Network..............: testdrive
Gateway..............: area-42
Node.................: beehive-1
Timestamp............: 2016-05-30T12:47:47.677973Z
Original payload.....: {"wght2": 42}
Current data.........: {u'wght2': 42}
History data.........: {u'wght2': 43}
------------------------------------------
----
.. hint::
We are still working on this alerting subsystem to improve all details of its implementation
including the format of the message reported to beekeepers and its overall robustness.
Please consider the current state as a working prototype.