comparison: doc/bms-ch3.sgml
doc/bms-ch3.sgml
- changeset 0
- 033898178630
- child 325
- 9a8c650972ca
equal
deleted
inserted
replaced
| -1:000000000000 | 0:033898178630 |
|---|---|
| 1 <!-- | |
| 2 vim:syntax=docbksgml | |
| 3 --> | |
| 4 | |
| 5 <chapter id="protocols"> | |
| 6 <title>Protocollen.</title> | |
| 7 <para> | |
| 8 De netwerk protocollen. | |
| 9 </para> | |
| 10 | |
| 11 <sect1 id="prototopic"> | |
| 12 <title>MQTT topic formaat.</title> | |
| 13 <para>De topics zijn als volgt gedefinieerd:</para> | |
| 14 <programlisting> | |
| 15 mbv1.0/<code>group_id</code>/<code>message_type</code>/<code>edge_node</code>/<code>device_id</code> | |
| 16 </programlisting> | |
| 17 | |
| 18 <itemizedlist> | |
| 19 <listitem><para><code>group_id</code> geeft het type apparaat aan zoals <code>fermenters</code> | |
| 20 en <code>brewcontrol</code>.</para></listitem> | |
| 21 <listitem><para><code>message_type</code> geeft het bericht type aan zoals | |
| 22 <code>NBIRTH</code>, <code>DDATA</code>.</para></listitem> | |
| 23 <listitem><para><code>edge_node</code> is de hostnaam van de node die het bericht stuurt. Dit is | |
| 24 de naam zonder domain toevoeging.</para></listitem> | |
| 25 <listitem><para><code>device_id</code> is de verkorte naam van het apparaat module waarvan dit | |
| 26 bericht komt zoals de naam van een vergisting controller. Dit is niet aanwezig met NODE berichten.</para></listitem> | |
| 27 </itemizedlist> | |
| 28 | |
| 29 <para> | |
| 30 De volgende <code>group_id</code> namen zijn gedefinieerd: | |
| 31 </para> | |
| 32 <orderedlist> | |
| 33 <listitem><para>brewery is voor de bms applicatie zelf. Nog uitwerken.</para></listitem> | |
| 34 <listitem><para>fermenters is voor vergisting controllers.</para></listitem> | |
| 35 <listitem><para>brewcontrol is een brouw controller. Deze controller kan een deel | |
| 36 of geheel brouwproces uitvoeren.</para></listitem> | |
| 37 <listitem><para>pressure is een drukmeter om bijvoorbeeld hergisting op de fles | |
| 38 te monitoren.</para></listitem> | |
| 39 </orderedlist> | |
| 40 | |
| 41 <para>De volgende <code>message_type</code> namen zijn gedefinieerd:</para> | |
| 42 <orderedlist> | |
| 43 <listitem><para>NBIRTH geeft aan wanneer een node opstart en met het netwerk | |
| 44 verbonden is. Dit is een zogenaamd persistent bericht, het blijft voor nieuwe | |
| 45 MQTT clients altijd zichtbaar. Bij het starten van een node wordt er een payload | |
| 46 verzonden, zie het payload formaat voor een node. Als een node afsluit wordt juist geen | |
| 47 payload verzonden zodat het bericht verdwijnt.</para></listitem> | |
| 48 <listitem><para>NDATA wordt verstuurd als er veranderingen zijn voor de node, | |
| 49 maar ook iedere vijf minuten om aan te geven dat de node nog "levend" en aanwezig | |
| 50 is.</para></listitem> | |
| 51 <listitem><para>NDEATH wordt verstuurd als een node offline gaat. Maar het kan ook | |
| 52 ontvangen worden als de MQTT verbinding verbroken wordt met een node, het NDEATH | |
| 53 bericht is ook het `last will' bericht van een node.</para></listitem> | |
| 54 <listitem><para>NCMD uitwerken.</para></listitem> | |
| 55 <listitem><para>DBIRTH is een of meer berichten van een apparaat wat online komt | |
| 56 en ingeschakeld is. Bij het opstarten van de node is er geen <code>device_id</code> | |
| 57 omdat alle apparaten is een keer verstuurd worden. Indien er later een enkel apparaat | |
| 58 ingeschakeld wordt dan is er wel een geldige <code>device_id</code> aanwezig. | |
| 59 Hier ook weer, er is een payload bij opstarten en geen payload bij afsluiten om het | |
| 60 persistente bericht goed te houden.</para></listitem> | |
| 61 <listitem><para>DDATA heeft altijd een payload, maar deze hoeft niet volledig te zijn, | |
| 62 enkel de gewijzigde data moet in het bericht zitten.</para></listitem> | |
| 63 <listitem><para>DDEATH wordt verstuurd als een node offline gaat, of als het apparaat | |
| 64 uitgeschakelt wordt.</para></listitem> | |
| 65 <listitem><para>DLOG is een data log. Hier bestaat de payload uit gegevens die de | |
| 66 bms applicatie in de database zet.</para></listitem> | |
| 67 <listitem><para>DCMD uitwerken.</para></listitem> | |
| 68 </orderedlist> | |
| 69 | |
| 70 </sect1> | |
| 71 | |
| 72 | |
| 73 <sect1 id="payloadnode"> | |
| 74 <title>Netwerk payload formaat voor een node</title> | |
| 75 <para> | |
| 76 De payload zoals die door een node verstuurd wordt. Het wordt in json formaat | |
| 77 verzonder zonder extra spaties en opmaak zoals hieronder is te zien. Het timestamp | |
| 78 is de unix tijd sinds 1 januari 1970. Het `seq' nummer wordt met ieder bericht met 1 | |
| 79 verhoogd.</para> | |
| 80 | |
| 81 <programlisting> | |
| 82 { | |
| 83 "timestamp": 1532201089, | |
| 84 "seq": 0, | |
| 85 "metric": { | |
| 86 "uuid": "b508f01c-1f82-4e8b-b0d2-d88ecfb53031", | |
| 87 "properties": { | |
| 88 "hardwaremake": "Raspberry", | |
| 89 "hardwaremodel": "Unknown", | |
| 90 "os": "Linux", | |
| 91 "os_version": "4.1.19+", | |
| 92 "FW": "0.8.2" | |
| 93 }, | |
| 94 "THB": { | |
| 95 "temperature": 20.0, | |
| 96 "humidity": 50.0, | |
| 97 "barometer": 1002 | |
| 98 }, | |
| 99 "GPS": { | |
| 100 "latitude": 1.2345, | |
| 101 "longitude": 2.3456, | |
| 102 "altitude": 20 | |
| 103 }, | |
| 104 "net": { | |
| 105 "address": "10.126.151.11", | |
| 106 "ifname": "eth0", | |
| 107 "rssi": 0 | |
| 108 } | |
| 109 } | |
| 110 } | |
| 111 </programlisting> | |
| 112 </sect1> | |
| 113 | |
| 114 <sect1 id="cmdnode"> | |
| 115 <title>Netwerk kommando payload formaat voor nodes.</title> | |
| 116 <para>De volgende kommando's kunnen gestuurd worden naar nodes:</para> | |
| 117 <programlisting> | |
| 118 { | |
| 119 "timestamp":1532201089, | |
| 120 "metric": { | |
| 121 "Node Control/Reboot":true | |
| 122 } | |
| 123 } | |
| 124 | |
| 125 { | |
| 126 "timestamp":1532201089, | |
| 127 "metric": { | |
| 128 "Node Control/Rebirth":true | |
| 129 } | |
| 130 } | |
| 131 </programlisting> | |
| 132 </sect1> | |
| 133 | |
| 134 <sect1 id="payloadfermdata"> | |
| 135 <title>Netwerk payload data formaat voor vergisting controllers</title> | |
| 136 <para> | |
| 137 Dit is het meest uitgebreide formaat wat getoond is. Indien er bijvoorbeeld geen | |
| 138 chiller aanwezig is, dan wordt eem `null' gestuurd in plaats van een json blok | |
| 139 met gegevens. De werkelijke uitvoering van de hardware en de configuratie daarvan | |
| 140 bepaald dus het uiteindelijke payload formaat. | |
| 141 </para> | |
| 142 <programlisting> | |
| 143 { | |
| 144 "uuid": "48c9ae27-3f58-41c9-ae4b-1d57b249c45a", | |
| 145 "alias": "unit1", | |
| 146 "product": { | |
| 147 "code": "CB0063", | |
| 148 "name": "Schot voor de boeg" | |
| 149 }, | |
| 150 "product": { | |
| 151 "uuid": "1eb0c7bf-bf06-491c-a086-ac5478d521b9", | |
| 152 "code": "CB0001", | |
| 153 "name": "Hoppy Housebeer" | |
| 154 }, | |
| 155 "air": { | |
| 156 "address": "70d60411-3ec8-40ab-998a-81fead83025f", | |
| 157 "state": "OK", | |
| 158 "temperature": 21.562 | |
| 159 }, | |
| 160 "beer": { | |
| 161 "address": "8ec36f9d-f382-4e32-a47f-732642e1018d", | |
| 162 "state": "OK", | |
| 163 "temperature": 22.125 | |
| 164 }, | |
| 165 "chiller": { | |
| 166 "address": "e81265b8-07f7-4b22-96c1-6f55a4b66a83", | |
| 167 "state": "OK", | |
| 168 "temperature": 12.437 | |
| 169 }, | |
| 170 "heater": { | |
| 171 "address": "d2f2d6bc-4d12-4852-9462-95f4c2476034", | |
| 172 "state": 0, | |
| 173 "usage": 10710793 | |
| 174 }, | |
| 175 "cooler": { | |
| 176 "address": "a9f30140-812c-4ec1-9e98-3a9d47deff7c", | |
| 177 "state": 0, | |
| 178 "usage": 920504 | |
| 179 }, | |
| 180 "fan": { | |
| 181 "address": "ae9f9887-8209-4810-9f58-ddfb34ee142f", | |
| 182 "state": 100, | |
| 183 "usage": 62889739 | |
| 184 }, | |
| 185 "light": { | |
| 186 "address": "cc6353cf-9c97-41b9-b6cf-00cea312e478", | |
| 187 "state": 0, | |
| 188 "usage": 29647290 | |
| 189 }, | |
| 190 "door": { | |
| 191 "address": "ad8746d1-0549-485a-a215-41e5cdde9e75", | |
| 192 "state": 1 | |
| 193 }, | |
| 194 "psu": { | |
| 195 "address": "e1bb7182-883d-4977-a1c0-76e214072fc5", | |
| 196 "state": 1 | |
| 197 }, | |
| 198 "stage": "PRIMARY", | |
| 199 "mode": "BEER", | |
| 200 "setpoint": { | |
| 201 "low": 21.0, | |
| 202 "high": 21.0 | |
| 203 }, | |
| 204 "alarm": 0, | |
| 205 "profile": { | |
| 206 "uuid": "c93ad1bb-0446-4788-9c43-83990c5f8b82", | |
| 207 "name": "Witbier methode Cellis", | |
| 208 "state": "OFF", | |
| 209 "percent": 0, | |
| 210 "inittemp": { | |
| 211 "low": 17.9, | |
| 212 "high": 18.1 | |
| 213 }, | |
| 214 "fridgemode": 0, | |
| 215 "steps": [ | |
| 216 { | |
| 217 "resttime": 2, | |
| 218 "steptime": 0, | |
| 219 "target": { | |
| 220 "low": 18.0, | |
| 221 "high": 18.0 | |
| 222 }, | |
| 223 "fridgemode": 0 | |
| 224 }, | |
| 225 { | |
| 226 "resttime": 0, | |
| 227 "steptime": 24, | |
| 228 "target": { | |
| 229 "low": 18.0, | |
| 230 "high": 22.0 | |
| 231 }, | |
| 232 "fridgemode": 0 | |
| 233 }, | |
| 234 { | |
| 235 "resttime": 48, | |
| 236 "steptime": 96, | |
| 237 "target": { | |
| 238 "low": 26.0, | |
| 239 "high": 26.0 | |
| 240 }, | |
| 241 "fridgemode": 0 | |
| 242 } | |
| 243 ] | |
| 244 } | |
| 245 } | |
| 246 </programlisting> | |
| 247 <para>Temperature states can be: OK, MISSING or ERROR.<para> | |
| 248 <para>The general `mode' can be: OFF, NONE, FRIDGE, BEER or PROFILE.</para> | |
| 249 <para>The profile `state' can be: OFF, PAUSE, RUN, DONE or ABORT.</para> | |
| 250 </sect1> | |
| 251 | |
| 252 | |
| 253 <sect1 id="payloadfermlog"> | |
| 254 <title>Netwerk payload log formaat voor vergisting controllers</title> | |
| 255 <para> | |
| 256 Dit is het meest uitgebreide formaat wat getoond is. Indien er bijvoorbeeld geen | |
| 257 chiller aanwezig is, dan wordt geen data hiervoor verstuurd. | |
| 258 De werkelijke uitvoering van de hardware en de configuratie daarvan | |
| 259 bepaald dus het uiteindelijke payload formaat. | |
| 260 </para> | |
| 261 <programlisting> | |
| 262 { | |
| 263 "timestamp": 1532201089, | |
| 264 "seq": 0, | |
| 265 "metric": { | |
| 266 "product": { | |
| 267 "uuid": "1eb0c7bf-bf06-491c-a086-ac5478d521b9", | |
| 268 "code": "CB0001", | |
| 269 "name": "Hoppy Housebeer" | |
| 270 }, | |
| 271 "stage": "PRIMARY", | |
| 272 "mode": "BEER", | |
| 273 "temperature": { | |
| 274 "air": 20.125, | |
| 275 "beer": 20.062, | |
| 276 "chiller": -3.000, | |
| 277 "room": 20.1 | |
| 278 }, | |
| 279 "setpoint": { | |
| 280 "low": 19.8, | |
| 281 "high": 20.1 | |
| 282 }, | |
| 283 "heater": { | |
| 284 "power": 100, | |
| 285 "usage": 1234 | |
| 286 }, | |
| 287 "cooler": { | |
| 288 "power": 0, | |
| 289 "usage": 27273 | |
| 290 }, | |
| 291 "fan": { | |
| 292 "power": 100, | |
| 293 "usage": 8273772 | |
| 294 }, | |
| 295 "sg": 1.023, | |
| 296 "event": "Something to mark", | |
| 297 "fermenter_uuid": "48c9ae27-3f58-41c9-ae4b-1d57b249c45a" | |
| 298 } | |
| 299 } | |
| 300 </programlisting> | |
| 301 </sect1> | |
| 302 | |
| 303 | |
| 304 </chapter> |
