--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/bms-ch3.sgml Sat Aug 04 21:19:15 2018 +0200
@@ -0,0 +1,304 @@
+<!--
+ vim:syntax=docbksgml
+-->
+
+<chapter id="protocols">
+<title>Protocollen.</title>
+<para>
+De netwerk protocollen.
+</para>
+
+<sect1 id="prototopic">
+<title>MQTT topic formaat.</title>
+<para>De topics zijn als volgt gedefinieerd:</para>
+<programlisting>
+mbv1.0/<code>group_id</code>/<code>message_type</code>/<code>edge_node</code>/<code>device_id</code>
+</programlisting>
+
+<itemizedlist>
+<listitem><para><code>group_id</code> geeft het type apparaat aan zoals <code>fermenters</code>
+en <code>brewcontrol</code>.</para></listitem>
+<listitem><para><code>message_type</code> geeft het bericht type aan zoals
+<code>NBIRTH</code>, <code>DDATA</code>.</para></listitem>
+<listitem><para><code>edge_node</code> is de hostnaam van de node die het bericht stuurt. Dit is
+de naam zonder domain toevoeging.</para></listitem>
+<listitem><para><code>device_id</code> is de verkorte naam van het apparaat module waarvan dit
+bericht komt zoals de naam van een vergisting controller. Dit is niet aanwezig met NODE berichten.</para></listitem>
+</itemizedlist>
+
+<para>
+De volgende <code>group_id</code> namen zijn gedefinieerd:
+</para>
+<orderedlist>
+<listitem><para>brewery is voor de bms applicatie zelf. Nog uitwerken.</para></listitem>
+<listitem><para>fermenters is voor vergisting controllers.</para></listitem>
+<listitem><para>brewcontrol is een brouw controller. Deze controller kan een deel
+of geheel brouwproces uitvoeren.</para></listitem>
+<listitem><para>pressure is een drukmeter om bijvoorbeeld hergisting op de fles
+te monitoren.</para></listitem>
+</orderedlist>
+
+<para>De volgende <code>message_type</code> namen zijn gedefinieerd:</para>
+<orderedlist>
+<listitem><para>NBIRTH geeft aan wanneer een node opstart en met het netwerk
+verbonden is. Dit is een zogenaamd persistent bericht, het blijft voor nieuwe
+MQTT clients altijd zichtbaar. Bij het starten van een node wordt er een payload
+verzonden, zie het payload formaat voor een node. Als een node afsluit wordt juist geen
+payload verzonden zodat het bericht verdwijnt.</para></listitem>
+<listitem><para>NDATA wordt verstuurd als er veranderingen zijn voor de node,
+maar ook iedere vijf minuten om aan te geven dat de node nog "levend" en aanwezig
+is.</para></listitem>
+<listitem><para>NDEATH wordt verstuurd als een node offline gaat. Maar het kan ook
+ontvangen worden als de MQTT verbinding verbroken wordt met een node, het NDEATH
+bericht is ook het `last will' bericht van een node.</para></listitem>
+<listitem><para>NCMD uitwerken.</para></listitem>
+<listitem><para>DBIRTH is een of meer berichten van een apparaat wat online komt
+en ingeschakeld is. Bij het opstarten van de node is er geen <code>device_id</code>
+omdat alle apparaten is een keer verstuurd worden. Indien er later een enkel apparaat
+ingeschakeld wordt dan is er wel een geldige <code>device_id</code> aanwezig.
+Hier ook weer, er is een payload bij opstarten en geen payload bij afsluiten om het
+persistente bericht goed te houden.</para></listitem>
+<listitem><para>DDATA heeft altijd een payload, maar deze hoeft niet volledig te zijn,
+enkel de gewijzigde data moet in het bericht zitten.</para></listitem>
+<listitem><para>DDEATH wordt verstuurd als een node offline gaat, of als het apparaat
+uitgeschakelt wordt.</para></listitem>
+<listitem><para>DLOG is een data log. Hier bestaat de payload uit gegevens die de
+bms applicatie in de database zet.</para></listitem>
+<listitem><para>DCMD uitwerken.</para></listitem>
+</orderedlist>
+
+</sect1>
+
+
+<sect1 id="payloadnode">
+<title>Netwerk payload formaat voor een node</title>
+<para>
+De payload zoals die door een node verstuurd wordt. Het wordt in json formaat
+verzonder zonder extra spaties en opmaak zoals hieronder is te zien. Het timestamp
+is de unix tijd sinds 1 januari 1970. Het `seq' nummer wordt met ieder bericht met 1
+verhoogd.</para>
+
+<programlisting>
+{
+ "timestamp": 1532201089,
+ "seq": 0,
+ "metric": {
+ "uuid": "b508f01c-1f82-4e8b-b0d2-d88ecfb53031",
+ "properties": {
+ "hardwaremake": "Raspberry",
+ "hardwaremodel": "Unknown",
+ "os": "Linux",
+ "os_version": "4.1.19+",
+ "FW": "0.8.2"
+ },
+ "THB": {
+ "temperature": 20.0,
+ "humidity": 50.0,
+ "barometer": 1002
+ },
+ "GPS": {
+ "latitude": 1.2345,
+ "longitude": 2.3456,
+ "altitude": 20
+ },
+ "net": {
+ "address": "10.126.151.11",
+ "ifname": "eth0",
+ "rssi": 0
+ }
+ }
+}
+</programlisting>
+</sect1>
+
+<sect1 id="cmdnode">
+<title>Netwerk kommando payload formaat voor nodes.</title>
+<para>De volgende kommando's kunnen gestuurd worden naar nodes:</para>
+<programlisting>
+{
+ "timestamp":1532201089,
+ "metric": {
+ "Node Control/Reboot":true
+ }
+}
+
+{
+ "timestamp":1532201089,
+ "metric": {
+ "Node Control/Rebirth":true
+ }
+}
+</programlisting>
+</sect1>
+
+<sect1 id="payloadfermdata">
+<title>Netwerk payload data formaat voor vergisting controllers</title>
+<para>
+Dit is het meest uitgebreide formaat wat getoond is. Indien er bijvoorbeeld geen
+chiller aanwezig is, dan wordt eem `null' gestuurd in plaats van een json blok
+met gegevens. De werkelijke uitvoering van de hardware en de configuratie daarvan
+bepaald dus het uiteindelijke payload formaat.
+</para>
+<programlisting>
+{
+ "uuid": "48c9ae27-3f58-41c9-ae4b-1d57b249c45a",
+ "alias": "unit1",
+ "product": {
+ "code": "CB0063",
+ "name": "Schot voor de boeg"
+ },
+ "product": {
+ "uuid": "1eb0c7bf-bf06-491c-a086-ac5478d521b9",
+ "code": "CB0001",
+ "name": "Hoppy Housebeer"
+ },
+ "air": {
+ "address": "70d60411-3ec8-40ab-998a-81fead83025f",
+ "state": "OK",
+ "temperature": 21.562
+ },
+ "beer": {
+ "address": "8ec36f9d-f382-4e32-a47f-732642e1018d",
+ "state": "OK",
+ "temperature": 22.125
+ },
+ "chiller": {
+ "address": "e81265b8-07f7-4b22-96c1-6f55a4b66a83",
+ "state": "OK",
+ "temperature": 12.437
+ },
+ "heater": {
+ "address": "d2f2d6bc-4d12-4852-9462-95f4c2476034",
+ "state": 0,
+ "usage": 10710793
+ },
+ "cooler": {
+ "address": "a9f30140-812c-4ec1-9e98-3a9d47deff7c",
+ "state": 0,
+ "usage": 920504
+ },
+ "fan": {
+ "address": "ae9f9887-8209-4810-9f58-ddfb34ee142f",
+ "state": 100,
+ "usage": 62889739
+ },
+ "light": {
+ "address": "cc6353cf-9c97-41b9-b6cf-00cea312e478",
+ "state": 0,
+ "usage": 29647290
+ },
+ "door": {
+ "address": "ad8746d1-0549-485a-a215-41e5cdde9e75",
+ "state": 1
+ },
+ "psu": {
+ "address": "e1bb7182-883d-4977-a1c0-76e214072fc5",
+ "state": 1
+ },
+ "stage": "PRIMARY",
+ "mode": "BEER",
+ "setpoint": {
+ "low": 21.0,
+ "high": 21.0
+ },
+ "alarm": 0,
+ "profile": {
+ "uuid": "c93ad1bb-0446-4788-9c43-83990c5f8b82",
+ "name": "Witbier methode Cellis",
+ "state": "OFF",
+ "percent": 0,
+ "inittemp": {
+ "low": 17.9,
+ "high": 18.1
+ },
+ "fridgemode": 0,
+ "steps": [
+ {
+ "resttime": 2,
+ "steptime": 0,
+ "target": {
+ "low": 18.0,
+ "high": 18.0
+ },
+ "fridgemode": 0
+ },
+ {
+ "resttime": 0,
+ "steptime": 24,
+ "target": {
+ "low": 18.0,
+ "high": 22.0
+ },
+ "fridgemode": 0
+ },
+ {
+ "resttime": 48,
+ "steptime": 96,
+ "target": {
+ "low": 26.0,
+ "high": 26.0
+ },
+ "fridgemode": 0
+ }
+ ]
+ }
+}
+</programlisting>
+<para>Temperature states can be: OK, MISSING or ERROR.<para>
+<para>The general `mode' can be: OFF, NONE, FRIDGE, BEER or PROFILE.</para>
+<para>The profile `state' can be: OFF, PAUSE, RUN, DONE or ABORT.</para>
+</sect1>
+
+
+<sect1 id="payloadfermlog">
+<title>Netwerk payload log formaat voor vergisting controllers</title>
+<para>
+Dit is het meest uitgebreide formaat wat getoond is. Indien er bijvoorbeeld geen
+chiller aanwezig is, dan wordt geen data hiervoor verstuurd.
+De werkelijke uitvoering van de hardware en de configuratie daarvan
+bepaald dus het uiteindelijke payload formaat.
+</para>
+<programlisting>
+{
+ "timestamp": 1532201089,
+ "seq": 0,
+ "metric": {
+ "product": {
+ "uuid": "1eb0c7bf-bf06-491c-a086-ac5478d521b9",
+ "code": "CB0001",
+ "name": "Hoppy Housebeer"
+ },
+ "stage": "PRIMARY",
+ "mode": "BEER",
+ "temperature": {
+ "air": 20.125,
+ "beer": 20.062,
+ "chiller": -3.000,
+ "room": 20.1
+ },
+ "setpoint": {
+ "low": 19.8,
+ "high": 20.1
+ },
+ "heater": {
+ "power": 100,
+ "usage": 1234
+ },
+ "cooler": {
+ "power": 0,
+ "usage": 27273
+ },
+ "fan": {
+ "power": 100,
+ "usage": 8273772
+ },
+ "sg": 1.023,
+ "event": "Something to mark",
+ "fermenter_uuid": "48c9ae27-3f58-41c9-ae4b-1d57b249c45a"
+ }
+}
+</programlisting>
+</sect1>
+
+
+</chapter>