Mercurial > bms / file comparison

comparison: doc/bms-ch8.sgml

doc/bms-ch8.sgml

branch
stable
changeset 366
a14a31bfc73b
parent 364
487274c2e9dc
child 506
8ab0e87d579e
equal deleted inserted replaced
365:9f27c822b14d 366:a14a31bfc73b
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>NDEATH wordt verstuurd als een node offline gaat. Maar het kan ook
49 ontvangen worden als de MQTT verbinding verbroken wordt met een node, het NDEATH
50 bericht is ook het `last will' bericht van een node. Maar als het echt fout gaat
51 dan zal er mogenlijk nooit een NDEATH bericht gezien worden.</para></listitem>
52 <listitem><para>NCMD is een commando bestemd voor een node.
53 Dit kan bijvoorbeeld een reboot commando zijn.</para></listitem>
54 <listitem><para>NDATA wordt verstuurd als er veranderingen zijn voor de node,
55 maar ook iedere vijf minuten om aan te geven dat de node nog "levend" en aanwezig
56 is.</para></listitem>
57
58 <listitem><para>DBIRTH is een of meer berichten van een apparaat wat online komt
59 en ingeschakeld is. Een apparaat is een deel van een node.
60 Bij het opstarten van de node is er geen <code>device_id</code>
61 omdat alle apparaten is een keer verstuurd worden. Indien er later een enkel apparaat
62 ingeschakeld wordt dan is er wel een geldige <code>device_id</code> aanwezig.
63 Hier ook weer, er is een payload bij opstarten en geen payload bij afsluiten om het
64 persistente bericht goed te houden.</para></listitem>
65 <listitem><para>DDEATH wordt verstuurd als een node offline gaat, of als het apparaat
66 uitgeschakelt wordt.</para></listitem>
67 <listitem><para>DDATA heeft altijd een payload, maar deze hoeft niet volledig te zijn,
68 enkel de gewijzigde data moet in het bericht zitten.</para></listitem>
69 <listitem><para>DLOG is een data log. Hier bestaat de payload uit gegevens die de
70 bms applicatie in de database zet.</para></listitem>
71 <listitem><para>DCMD is een commando voor een apparaat wat op een node geinstalleerd is.
72 Dit zullen voornamelijk instellingen voor dat enkele apparaat zijn.</para></listitem>
73 </orderedlist>
74
75 </sect1>
76
77
78 <sect1 id="payloadnode">
79 <title>Netwerk payload formaat voor een node</title>
80 <para>
81 De payload zoals die door een node verstuurd wordt. Het wordt in json formaat
82 verzonder zonder extra spaties en opmaak zoals hieronder is te zien. Het timestamp
83 is de unix tijd sinds 1 januari 1970. Het `seq' nummer wordt met ieder bericht met 1
84 verhoogd.</para>
85
86 <programlisting>
87 {
88 "timestamp": 1532201089,
89 "seq": 0,
90 "metric": {
91 "uuid": "b508f01c-1f82-4e8b-b0d2-d88ecfb53031",
92 "properties": {
93 "hardwaremake": "Raspberry",
94 "hardwaremodel": "Unknown",
95 "os": "Linux",
96 "os_version": "4.1.19+",
97 "FW": "0.8.2"
98 },
99 "THB": {
100 "temperature": 20.0,
101 "humidity": 50.0,
102 "barometer": 1002
103 },
104 "GPS": {
105 "latitude": 1.2345,
106 "longitude": 2.3456,
107 "altitude": 20
108 },
109 "net": {
110 "address": "10.126.151.11",
111 "ifname": "eth0",
112 "rssi": 0
113 }
114 }
115 }
116 </programlisting>
117 </sect1>
118
119 <sect1 id="cmdnode">
120 <title>Netwerk kommando payload formaat voor nodes.</title>
121 <para>De volgende kommando's kunnen gestuurd worden naar nodes:</para>
122 <programlisting>
123 {
124 "timestamp":1532201089,
125 "metric": {
126 "Node Control/Reboot":true
127 }
128 }
129 </programlisting>
130 <para>Dit commando reboot niet de computer maar de applicatie die op een
131 computer zoals een Raspberry Pi geinstalleerd is. Een uitzondering zijn de
132 controllers zoals Arduino's en andere eenvoudige systemen.</para>
133 <programlisting>
134 {
135 "timestamp":1532201089,
136 "metric": {
137 "Node Control/Rebirth":true
138 }
139 }
140 </programlisting>
141 <para>Dit commando zorgt er voor dat alle NBIRTH en DBIRTH berichten opnieuw
142 verzonden worden alsof de computer net is opgestart. Dit kan nuttig zijn na
143 een herstart van de bms applicatie zelf zodat de juiste nodes informatie weer
144 beschikbaar is.</para>
145 </sect1>
146
147 <sect1 id="payloadfermdata">
148 <title>Netwerk payload data formaat voor vergisting controllers</title>
149 <para>
150 Dit is het meest uitgebreide formaat wat getoond is. Indien er bijvoorbeeld geen
151 chiller aanwezig is, dan wordt een `null' gestuurd in plaats van een json blok
152 met gegevens. De werkelijke uitvoering van de hardware en de configuratie daarvan
153 bepaald dus het uiteindelijke payload formaat.
154 </para>
155 <programlisting>
156 {
157 "uuid": "48c9ae27-3f58-41c9-ae4b-1d57b249c45a",
158 "alias": "unit1",
159 "product": {
160 "uuid": "1eb0c7bf-bf06-491c-a086-ac5478d521b9",
161 "code": "CB0001",
162 "name": "Hoppy Housebeer"
163 },
164 "air": {
165 "address": "70d60411-3ec8-40ab-998a-81fead83025f",
166 "state": "OK",
167 "temperature": 21.562
168 },
169 "beer": {
170 "address": "8ec36f9d-f382-4e32-a47f-732642e1018d",
171 "state": "OK",
172 "temperature": 22.125
173 },
174 "chiller": {
175 "address": "e81265b8-07f7-4b22-96c1-6f55a4b66a83",
176 "state": "OK",
177 "temperature": 12.437
178 },
179 "heater": {
180 "address": "d2f2d6bc-4d12-4852-9462-95f4c2476034",
181 "state": 0,
182 "usage": 10710793
183 },
184 "cooler": {
185 "address": "a9f30140-812c-4ec1-9e98-3a9d47deff7c",
186 "state": 0,
187 "usage": 920504
188 },
189 "fan": {
190 "address": "ae9f9887-8209-4810-9f58-ddfb34ee142f",
191 "state": 100,
192 "usage": 62889739
193 },
194 "light": {
195 "address": "cc6353cf-9c97-41b9-b6cf-00cea312e478",
196 "state": 0,
197 "usage": 29647290
198 },
199 "door": {
200 "address": "ad8746d1-0549-485a-a215-41e5cdde9e75",
201 "state": 1
202 },
203 "psu": {
204 "address": "e1bb7182-883d-4977-a1c0-76e214072fc5",
205 "state": 1
206 },
207 "stage": "PRIMARY",
208 "mode": "BEER",
209 "setpoint": {
210 "low": 21.0,
211 "high": 21.0
212 },
213 "webcam": {
214 "url":"https://the.webcamserver.com:8090/?action=stream",
215 "light": 1
216 },
217 "alarm": 0,
218 "profile": {
219 "uuid": "c93ad1bb-0446-4788-9c43-83990c5f8b82",
220 "name": "Witbier methode Cellis",
221 "state": "OFF",
222 "percent": 0,
223 "inittemp": {
224 "low": 17.9,
225 "high": 18.1
226 },
227 "fridgemode": 0,
228 "steps": [
229 {
230 "resttime": 2,
231 "steptime": 0,
232 "target": {
233 "low": 18.0,
234 "high": 18.0
235 },
236 "fridgemode": 0
237 },
238 {
239 "resttime": 0,
240 "steptime": 24,
241 "target": {
242 "low": 18.0,
243 "high": 22.0
244 },
245 "fridgemode": 0
246 },
247 {
248 "resttime": 48,
249 "steptime": 96,
250 "target": {
251 "low": 26.0,
252 "high": 26.0
253 },
254 "fridgemode": 0
255 }
256 ]
257 }
258 }
259 </programlisting>
260 <para>Temperature states can be: OK, MISSING or ERROR.<para>
261 <para>The general `mode' can be: OFF, NONE, FRIDGE, BEER or PROFILE.</para>
262 <para>The profile `state' can be: OFF, PAUSE, RUN, DONE or ABORT.</para>
263 </sect1>
264
265
266 <sect1 id="payloadfermlog">
267 <title>Netwerk payload log formaat voor vergisting controllers</title>
268 <para>
269 Dit is het meest uitgebreide formaat wat getoond is. Indien er bijvoorbeeld geen
270 chiller aanwezig is, dan wordt geen data hiervoor verstuurd.
271 De werkelijke uitvoering van de hardware en de configuratie daarvan
272 bepaald dus het uiteindelijke payload formaat.
273 </para>
274 <programlisting>
275 {
276 "timestamp": 1532201089,
277 "seq": 0,
278 "metric": {
279 "product": {
280 "uuid": "1eb0c7bf-bf06-491c-a086-ac5478d521b9",
281 "code": "CB0001",
282 "name": "Hoppy Housebeer"
283 },
284 "stage": "PRIMARY",
285 "mode": "BEER",
286 "temperature": {
287 "air": 20.125,
288 "beer": 20.062,
289 "chiller": -3.000,
290 "room": 20.1
291 },
292 "setpoint": {
293 "low": 19.8,
294 "high": 20.1
295 },
296 "heater": {
297 "power": 100,
298 "usage": 1234
299 },
300 "cooler": {
301 "power": 0,
302 "usage": 27273
303 },
304 "fan": {
305 "power": 100,
306 "usage": 8273772
307 },
308 "sg": 1.023,
309 "event": "Something to mark",
310 "fermenter_uuid": "48c9ae27-3f58-41c9-ae4b-1d57b249c45a"
311 }
312 }
313 </programlisting>
314 <para>
315 De ontvangen vergisting log gegevens worden niet opgeslagen in de SQL database
316 maar in platte tekst bestanden. Hierdoor is de gelogde informatie sneller toegankelijk.
317 Ieder brouw product heeft zijn eigen bestand.
318 De bestanden staan in <code>www/logs/fermentation/</code>.
319 De bestandsnamen zijn <code>product_code\ product_name.log</code>.
320 Het interne formaat is:</para>
321 <programlisting>
322 2014-11-15 18:39,BEER,PRIMARY,20.312,19.750,-1.500,20.5,18.6,18.8,35,12345,0,67890,Whatsup,Fermenter
323 | | | | | | | | | | | | | | |
324 0 datetime + | | | | | | | | | | | | | |
325 1 werkwijze ---------+ | | | | | | | | | | | | |
326 2 vergisting fase ---------+ | | | | | | | | | | | |
327 3 temperatuur lucht --------------+ | | | | | | | | | | |
328 4 temperatuur bier ----------------------+ | | | | | | | | | |
329 5 temperatuur koeler ---------------------------+ | | | | | | | | |
330 6 temperatuur ruimte ----------------------------------+ | | | | | | | |
331 7 instelwaarde laag ----------------------------------------+ | | | | | | |
332 8 instelwaarde hoog ---------------------------------------------+ | | | | | |
333 9 verwarming vermogen -----------------------------------------------+ | | | | |
334 10 verwarming verbruik ---------------------------------------------------+ | | | |
335 11 koeler vermogen -----------------------------------------------------------+ | | |
336 12 koeler verbruik ---------------------------------------------------------------+ | |
337 13 gebeurtenis --------------------------------------------------------------------------+ |
338 14 vergister uuid --------------------------------------------------------------------------------+
339 </programlisting>
340 </sect1>
341
342
343 </chapter>

Mercurial Repository: bms

mercurial