Mercurial > bms / file comparison

comparison: doc/bms-ch8.sgml

doc/bms-ch8.sgml

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

Mercurial Repository: bms

mercurial