Improve documentation

CHANGES.rst

@@ -17,10 +17,12 @@ Breaking changes
    We have been too lazy in the past. Sorry.
 
 
-Packaging
----------
-- Improve Docker image building
-- Add packaging for Ubuntu 18 Bionic Beaver
+Features & Bugfixes
+-------------------
+- Honor "Time" field submitted by devices running Tasmota
+- Make Tasmota decoder grok double-nested payloads from Wemos devices
+- Fix logger
+- Refactor decoder subsystem
 
 Documentation
 -------------
@@ -30,12 +32,10 @@ Documentation
   :ref:`grafana-vs-export` and :ref:`weewx-mqtt-faq`.
 - Add FAQ section about :ref:`processing-tags`
 
-Features & Bugfixes
--------------------
-- Honor "Time" field submitted by devices running Tasmota
-- Make Tasmota decoder grok double-nested payloads from Wemos devices
-- Fix logger
-- Refactor decoder subsystem
+Packaging
+---------
+- Improve Docker image building
+- Add packaging for Ubuntu 18 Bionic Beaver
 
 Tests
 -----

CONTRIBUTORS.rst

@@ -13,7 +13,6 @@ contributed to Kotori in one way or another.
 * Anne-Julia Scheuermann <annejulia@gmail.com>
 * Carolin Johannsen <caro@hiverize.org>
 * Clemens Gruber <clemens@hiveeyes.org>
-* Dewieinns <https://github.com/Dewieinns>
 * Georges Gagliano <https://github.com/ggeorges39>
 * Géraldine Farcy-Merlo <https://www.mellisphera.com/>
 * Jan Hoffmann <j.hoffmann@isarengineering.de>

README.rst

@@ -108,16 +108,23 @@ Examples
 ********
 Data acquisition is easy, both MQTT and HTTP are supported.
 
+First, let's define a data acquisition channel::
+
+    CHANNEL=amazonas/ecuador/cuyabeno/1
+
+and some data to submit::
+
+    DATA='{"temperature": 42.84, "humidity": 83.1}'
+
 MQTT::
 
-    CHANNEL_BROKER=daq.example.org
-    CHANNEL_TOPIC=amazonas/ecuador/cuyabeno/1/data.json
-    mosquitto_pub -h $CHANNEL_BROKER -t $CHANNEL_TOPIC -m '{"temperature": 42.84, "humidity": 83.1}'
+    MQTT_BROKER=daq.example.org
+    echo "$DATA" | mosquitto_pub -h $MQTT_BROKER -t $CHANNEL/data.json -l
 
 HTTP::
 
-    CHANNEL_URI=https://daq.example.org/api/amazonas/ecuador/cuyabeno/1/data
-    echo '{"temperature": 42.84, "humidity": 83.1}' | curl --request POST --header 'Content-Type: application/json' --data @- $CHANNEL_URI
+    HTTP_URI=https://daq.example.org/api/
+    echo "$DATA" | curl --request POST --header 'Content-Type: application/json' --data @- $HTTP_URI/$CHANNEL/data
 
 
 ****************

doc/source/development/backlog.rst

@@ -25,6 +25,48 @@ Backlog
 - Tests: Bulk upload via CSV.
 - Tests: Time filtering and more for HTTP API export.
 - New: Bulk upload via InfluxDB line protocol.
+- Add support for Homie 2.x::
+
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$homie 2.0.1
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$name hive-teststand
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$mac 84:F3:EB:B2:FB:1A
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$localip 192.168.178.61
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$nodes temperature0,temperature1,temperature2,temperature3,weight,battery,data
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$stats/interval 0
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$stats/signal 62
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$stats/uptime 66
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$fw/name node-wifi-mqtt-homie
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$fw/version 0.10.0
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$fw/checksum 98816d2088bead73b35c38a4db28acb4
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$implementation esp8266
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$implementation/config {"wifi":{"ssid":"Ponyhof"},"mqtt":{"host":"swarm.hiveeyes.org","port":1883,"base_topic":"hiveeyes/testdrive/area-42/node-1/message-json","auth":false},"name":"hive-teststand","ota":{"enabled":true},"device_id":"hive-teststand","settings":{"sendInterval":60,"weightOffset":33840,"kilogramDivider":20.85,"vccAdjust":0,"tempsensorsAmount":4}}
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$implementation/version 2.0.0
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$implementation/ota/enabled true
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature0/$type temperature
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature0/$properties unit,degrees
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature0/unit C
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature1/$type temperature
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature1/$properties unit,degrees
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature1/unit C
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature2/$type temperature
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature2/$properties unit,degrees
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature3/$type temperature
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/temperature3/$properties unit,degrees
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/weight/$type weight
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/weight/$properties unit,kilogram
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/battery/$type battery
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/battery/$properties unit,volt
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/battery/volt 3.02
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/data/$type __json__
+    hiveeyes/testdrive/area-42/node-1/message-jsonhive-teststand/$online true
+
+- Support batch readings (jsonl?)
+  https://community.hiveeyes.org/t/more-data-acquisition-payload-formats-for-kotori/1421/3
+
+- Investigate switching to Klein
+  - https://stackoverflow.com/questions/33283869/match-an-arbitrary-path-or-the-empty-string-without-adding-multiple-flask-rout/33296155#33296155
+  - https://github.com/twisted/klein/blob/master/src/klein/_app.py#L84-L85
+
 
 
 ****

doc/source/development/tests.rst

@@ -43,11 +43,15 @@ or run specific tests with maximum verbosity::
 
     export PYTEST_OPTIONS="--verbose --verbose --log-level DEBUG --log-cli-level DEBUG --capture=no"
 
-    # Run all tests starting with "test_tasmota".
+    # Run tests starting with "test_tasmota".
     pytest test ${PYTEST_OPTIONS} -k test_tasmota
 
-    # Run all tests marked with "hiveeyes".
-    pytest test ${PYTEST_OPTIONS} -m hiveeyes
+    # Run tests marked with "mqtt".
+    pytest test ${PYTEST_OPTIONS} -m mqtt
+
+    # Run tests marked with "tasmota", "homie" or "airrohr".
+    pytest test ${PYTEST_OPTIONS} -m 'tasmota or homie or airrohr'
+
 
 To see available markers, type::
 

doc/source/handbook/acquisition/events.rst

@@ -8,9 +8,10 @@ Events API
 
 
 .. _daq-mqtt-annotation:
+.. _daq-mqtt-events:
 
-MQTT annotations
-================
+MQTT events
+===========
 `Grafana Annotations`_ can be created through MQTT at the ``/event.json`` topic suffix.
 While arbitrary fields can be submitted, Grafana_ evaluates the fields ``title``, ``text`` and ``tags``.
 It is possible to use HTML inside the ``text`` field, for example to link this event to another web application.
@@ -32,11 +33,11 @@ Annotations can also be submitted retroactively, just add a ``time`` field::
 See also the whole list of :ref:`daq-timestamp-formats`.
 
 
-
 .. _daq-http-annotation:
+.. _daq-http-events:
 
-HTTP annotations
-================
+HTTP events
+===========
 `Grafana Annotations`_ can be created through the HTTP interface at the ``/event`` endpoint.
 While arbitrary fields can be submitted, Grafana_ evaluates the fields ``title``, ``text`` and ``tags``.
 It is possible to use HTML inside the ``text`` field, for example to link this event to another web application.

doc/source/handbook/acquisition/protocol/http.rst

@@ -112,6 +112,14 @@ Example::
 See also the whole list of :ref:`daq-timestamp-formats`.
 
 
+Events
+======
+Events can be submitted to HTTP at the endpoint URI suffix ``/event``.
+`Grafana Annotations`_ will be created automatically. Read more
+about it at :ref:`daq-http-events`.
+
+
+
 .. _daq-http-csv:
 
 **********

doc/source/handbook/acquisition/protocol/mqtt.rst

@@ -59,6 +59,14 @@ Publish sensor reading with timestamp in `ISO 8601`_ format::
 See also the whole list of :ref:`daq-timestamp-formats`.
 
 
+Events
+======
+Events can be published to the MQTT topic suffix ``/event.json``.
+`Grafana Annotations`_ will be created automatically. Read more
+about it at :ref:`daq-mqtt-events`.
+
+
+
 .. _daq-mqtt-csv:
 
 **********

etc/examples/forwarders/http-to-mqtt.ini

@@ -16,18 +16,18 @@
 ;         - Receive payloads formatted as JSON or in urlencoded format
 ;         - Forward payloads to the MQTT bus
 ;
-; Manual:   Please specify forwarding source and target parameters in uri format.
-;           The MQTT topic path is derived from the http uri path by interpolating
-;           the appropriate part of the context uri.
+; Manual:   Please specify forwarding source and target parameters in URI format.
+;           The MQTT topic path is derived from the HTTP URI path by interpolating
+;           the appropriate part of the context URI.
 ;
 ; Example:  In the example below, given the "address" part of the resource URI
 ;           is "testdrive/area-42/node-1", data sent to the full URI
 ;
-;           /api/mqttkit-1/testdrive/area-42/node-1/data
+;               /api/mqttkit-1/testdrive/area-42/node-1/data
 ;
 ;           will be republished to the MQTT topic
 ;
-;                mqttkit-1/testdrive/area-42/node-1/data.json
+;               mqttkit-1/testdrive/area-42/node-1/data.json
 ;
 ; ------------------------------------------