diff -r 000000000000 -r 033898178630 doc/bms-ch3.sgml
--- /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>