Thu, 31 Jan 2019 22:39:36 +0100
The recipes yeast grid now uses a popup editor.
0 | 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> |