Mon, 31 Dec 2018 14:41:08 +0100
Backport water treatment to the product editor (inluding the bugs).
<!-- 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>