Radiocraft Wireless M-Bus extension module  2.18
mbus.inc
Go to the documentation of this file.
1 //-----------------------------------------------------------------------------
2 // Wireless M-Bus communication
3 //-----------------------------------------------------------------------------
4 #IFDEF NOT MBUS_INC THEN
5 #DEFINE MBUS_INC
6 
7 #DEFINE MBUS_MODULE_MEDIA 1
8 #DEFINE MBUS_MODULE_PATH "B:\SYSTEM\EXT\MOD_MBUS.RMX"
9 
10 #DEFINE MBUS_DATA_LENGTH 246
11 
12 #DEFINE MBUS_MODCALL_ERR -999
13 
14 #DEFINE MBUS_MODE_S2 0
15 #DEFINE MBUS_MODE_T1 1
16 #DEFINE MBUS_MODE_T2 2
17 #DEFINE MBUS_MODE_S1 3
18 #DEFINE MBUS_MODE_R 4
19 #DEFINE MBUS_MODE_T1_C 10
20 #DEFINE MBUS_MODE_T2_C 11
21 
22 
23 //----------------------------------------------------------------------------
24 // mbusFrame
25 //
26 // Description:
27 // This struct block contains a frame received from the M-Bus module.
28 //
29 // Output:
30 // control - The control field.
31 // manufacturer - The ID of the manufacturer. Part of the device address.
32 // id - The device id/serial number. Part of the device address.
33 // version - The device version. Part of the device address.
34 // type - The device type. Part of the device address.
35 // RSSI - The signal strength for the packet. If it is not enabled in mbusOpen, it is set to 0.
36 // linsec - RTCU time when frame was received
37 // length - The length of the additional data in the frame.
38 // data - The additional data that was received.
39 // Only the first <length> bytes are valid.
40 //
41 //----------------------------------------------------------------------------
42 STRUCT_BLOCK ALIGN mbusFrame;
43  control : SINT; // Control field
44 
45  // Address
46  manufacturer : INT; // Manufacture ID
47  id : DINT; // Device Identification number
48  version : SINT; // Device Version number
49  type : SINT; // Device Type
50 
51  // APP_DATA
52  RSSI : INT; // signal strength in dB = - RSSI/2
53  linsec : DINT; // RTCU time when frame was received
54  length : INT; // Length of additional data
55  data : ARRAY[1 .. MBUS_DATA_LENGTH] OF SINT;
56 END_STRUCT_BLOCK;
57 
58 //----------------------------------------------------------------------------
59 // mbusInit()
60 //
61 // Description:
62 // Initializes the M-Bus extension module.
63 //
64 // Input:
65 // path - The path to the module to initialize. Optional, as the default value is already correct.
66 // media - The media the module is located on. Optional, as the default value is already correct.
67 //
68 // Returns:
69 // 0 : OK
70 // -1 : Failed to open media
71 // -2 : Failed to load module
72 //----------------------------------------------------------------------------
73 FUNCTION ALIGN mbusInit : INT;
74 VAR_INPUT
75  path : STRING := MBUS_MODULE_PATH;
76  media : SINT := MBUS_MODULE_MEDIA;
77 END_VAR;
78 VAR
79  rc : INT;
80 END_VAR;
81 
82 // Initialize media where module is located
83 rc := fsMediaOpen(media := media);
84 IF NOT (rc = 0) THEN
85  mbusInit := -1;
86  RETURN;
87 END_IF;
88 
89 // Load an extension module
90 rc := extModuleLoad(path:=path);
91 IF NOT (rc = 1) THEN
92  mbusInit := -2;
93  RETURN;
94 END_IF;
95 
96 mbusInit := 0;
97 END_FUNCTION;
98 
99 //----------------------------------------------------------------------------
100 // mbusOpen()
101 //
102 // Description:
103 // Opens the connection to the M-Bus module.
104 //
105 // Input:
106 // mode - The M-Bus mode to use. See the MBUS_MODE_* defines above.
107 // RSSI - Include the signal strength( RSSI) for each valid packet.
108 // It can be read from mbusReceive()
109 // max_frames - Amount of elements the buffer will accept. Maximum value 1000.
110 // overwrite - Policy to apply when the buffer is full.
111 // If TRUE, remove oldest element in buffer and append new.
112 // If FALSE, discard newly received frame.
113 //
114 //
115 // Returns:
116 // 0: Success
117 // -1: Failed to open the M-Bus interface.
118 // -2: Invalid input
119 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
120 //----------------------------------------------------------------------------
121 FUNCTION ALIGN mbusOpen : INT;
122 VAR_INPUT
123  mode : SINT := MBUS_MODE_T1;
124  RSSI : BOOL := OFF;
125  max_frames : INT := 100;
126  overwrite : BOOL := TRUE;
127 END_VAR;
128 VAR
129  error : INT;
130 END_VAR;
131  mbusOpen := INT(MODCALL("mod_mbus", "mbusOpen", error));
132  IF NOT (error = 0) THEN
133  mbusOpen := MBUS_MODCALL_ERR;
134  END_IF;
135 END_FUNCTION;
136 
137 //----------------------------------------------------------------------------
138 // mbusClose()
139 //
140 // Description:
141 // Closes the connection to the M-Bus module.
142 //
143 // Input:
144 // None.
145 //
146 // Returns:
147 // 0: Success
148 // -1: Failed to close the M-Bus interface.
149 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
150 //----------------------------------------------------------------------------
151 FUNCTION ALIGN mbusClose : INT;
152 VAR
153  error : INT;
154 END_VAR;
155  mbusClose := INT(MODCALL("mod_mbus", "mbusClose", error));
156  IF NOT (error = 0) THEN
157  mbusClose := MBUS_MODCALL_ERR;
158  END_IF;
159 END_FUNCTION;
160 
161 //----------------------------------------------------------------------------
162 // mbusSend()
163 //
164 // Description:
165 // Sends data to the M-Bus module.
166 //
167 // Input:
168 // control - The M-Bus mode to use. See the MBUS_MODE_* defines above. 0-255.
169 // length - The length of the data to send. Max 246 bytes.
170 // data - The data to send.
171 //
172 // Returns:
173 // 0: Success
174 // -1: Invalid parameter.
175 // -2: Failed to send data.
176 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
177 //----------------------------------------------------------------------------
178 FUNCTION ALIGN mbusSend : INT;
179 VAR_INPUT
180  control : INT := -1; // (-1, 0 .. 255) :change control byte before send
181  length : INT := 0; // (0 .. MBUS_DATA_LENGTH) : length of data to send
182  data : PTR; // data to send
183 END_VAR;
184 VAR
185  error : INT;
186 END_VAR;
187  mbusSend := INT(MODCALL("mod_mbus", "mbusSend", error));
188  IF NOT (error = 0) THEN
189  mbusSend := MBUS_MODCALL_ERR;
190  END_IF;
191 END_FUNCTION;
192 
193 //----------------------------------------------------------------------------
194 // mbusFilterReceive()
195 //
196 // Description:
197 // Receives data from a registered filter in the M-Bus module.
198 //
199 // Input:
200 // idx - (1..64) filter index to receive from.
201 //
202 // Output:
203 // frame - The provided struct is filled with the values of a received M-Bus frame.
204 //
205 // Returns:
206 // 1: Data was received.
207 // 0: No data
208 // -1: Failed to access receive interface.
209 // -2: Interface is not open
210 // -3: Invalid input
211 // -4: No slave registered with this index
212 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
213 //----------------------------------------------------------------------------
214 FUNCTION ALIGN mbusFilterReceive;
215 VAR_INPUT
216  idx : INT := 0;
217  frame : ACCESS mbusFrame;
218 END_VAR;
219 VAR
220  error : INT;
221 END_VAR;
222  mbusFilterReceive := INT(MODCALL("mod_mbus", "mbusFilterReceive", error));
223  IF NOT (error = 0) THEN
224  mbusFilterReceive := MBUS_MODCALL_ERR;
225  END_IF;
226 END_FUNCTION;
227 
228 //----------------------------------------------------------------------------
229 // mbusReceive()
230 //
231 // Description:
232 // Receives data from the M-Bus module. If the device address is given, it searches for
233 // data received from a slave device with the given address parameters.
234 // If type = -1 (default), this function returns the oldest element in the buffer.
235 //
236 // Input:
237 // manufacturer - The ID of the manufacturer. Part of the device address.
238 // id - The device identification number/serial number. Part of the device address.
239 // version - The device version. Part of the device address.
240 // type - The device type. Part of the device address.
241 // timeout - Time to wait for data in milliseconds.
242 // If timeout is -1 (default), wait until data is received.
243 //
244 // Output:
245 // frame - The provided struct is filled with the values of a received M-Bus frame.
246 //
247 // Returns:
248 // 1: Data was received.
249 // 0: No data
250 // -1: Failed to access receive interface.
251 // -2: Interface is not open
252 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
253 //----------------------------------------------------------------------------
254 FUNCTION ALIGN mbusReceive;
255 VAR_INPUT
256  timeout : DINT := -1;
257  manufacturer : INT := 0;
258  id : DINT := 0;
259  version : SINT := 0;
260  type : SINT := -1;
261  frame : ACCESS mbusFrame;
262 END_VAR;
263 VAR
264  error : INT;
265 END_VAR;
266  mbusReceive := INT(MODCALL("mod_mbus", "mbusReceive", error));
267  IF NOT (error = 0) THEN
268  mbusReceive := MBUS_MODCALL_ERR;
269  END_IF;
270 END_FUNCTION;
271 
272 //----------------------------------------------------------------------------
273 // mbusInfo()
274 //
275 // Description:
276 // Sends some information about the M-Bus module to the device output.
277 // Example output:
278 //
279 // mbus_test:Signal quality = 0
280 // mbus_test:RSSI = 205 (-102 dBm)
281 // mbus_test:Temperature = 32 C
282 // mbus_test:VCC = 3450mV
283 // mbus_test:MBUS_MODE = 0x01
284 // mbus_test:DATA_INTERFACE = 0x00
285 // mbus_test:PART_NUMBER = RC1180-MBUS3
286 // mbus_test:HW_REV_NO = 2.00
287 // mbus_test:FW_REV_NO = 3.15
288 // mbus_info:SERIAL_NUMBER = 01 23 45 67 89 AB CD EF
289 // mbus_info:INSTALL_MODE = 0x02
290 // mbus_info:RSSI_MODE = 0x01
291 //
292 // Input:
293 // None.
294 //
295 // Returns:
296 // 0: Success
297 // -1: Failed to access interface.
298 // -2: Module failure
299 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
300 //----------------------------------------------------------------------------
301 FUNCTION mbusInfo : INT;
302 VAR
303  error : INT;
304 END_VAR;
305  mbusInfo := INT(MODCALL("mod_mbus", "mbusInfo", error));
306  IF NOT (error = 0) THEN
307  mbusInfo := MBUS_MODCALL_ERR;
308  END_IF;
309 END_FUNCTION;
310 
311 //----------------------------------------------------------------------------
312 // mbusRegisterSlave()
313 //
314 // Description:
315 // Registers/installs a slave device on the M-Bus module.
316 // This is necessary when filtering or when using encryption.
317 //
318 // Input:
319 // idx - The index of the slave to register. 1-64.
320 // manufacturer - The ID of the manufacturer. Part of the device address.
321 // id - The device identification number/serial number. Part of the device address.
322 // version - The device version. Part of the device address.
323 // type - The device type. Part of the device address.
324 // key - The 16 byte (128 bit) encryption key. Can be left empty if encryption is not used.
325 //
326 // Returns:
327 // 0: Success
328 // -1: Failed to access interface.
329 // -2: Invalid idx.
330 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
331 //----------------------------------------------------------------------------
332 FUNCTION mbusRegisterSlave : INT;
333 VAR_INPUT
334  idx : INT := 1;
335  manufacturer : MANDATORY INT;
336  id : MANDATORY DINT;
337  version : MANDATORY SINT;
338  type : MANDATORY SINT;
339  key : PTR;
340 END_VAR;
341 VAR
342  error : INT;
343 END_VAR;
344  mbusRegisterSlave := INT(MODCALL("mod_mbus", "mbusRegisterSlave", error));
345  IF NOT (error = 0) THEN
346  mbusRegisterSlave := MBUS_MODCALL_ERR;
347  END_IF;
348 END_FUNCTION;
349 
350 //----------------------------------------------------------------------------
351 // mbusFilterEnable()
352 //
353 // Description:
354 // Enables/disables filtering of the received packets, to only receive packets from registered slave devices.
355 //
356 // Input:
357 // enable - Set to true to only receive packets from installed slaves.
358 //
359 // Returns:
360 // 0: Success
361 // -1: Failed to access interface.
362 // -2: Invalid idx.
363 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
364 //----------------------------------------------------------------------------
365 FUNCTION mbusFilterEnable : INT;
366 VAR_INPUT
367  enable : BOOL := TRUE;
368 END_VAR;
369 VAR
370  error : INT;
371 END_VAR;
372  mbusFilterEnable := INT(MODCALL("mod_mbus", "mbusFilterEnable", error));
373  IF NOT (error = 0) THEN
374  mbusFilterEnable := MBUS_MODCALL_ERR;
375  END_IF;
376 END_FUNCTION;
377 
378 //----------------------------------------------------------------------------
379 // mbusGetBufferLevel()
380 //
381 // Description:
382 // Returns how many promille of the buffer is filled.
383 //
384 // Input:
385 //
386 // Returns: Buffer full level in promille [0..1000].
387 // -1: Failed to access interface.
388 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
389 //----------------------------------------------------------------------------
390 FUNCTION ALIGN mbusGetBufferLevel : INT;
391 VAR
392  error : INT;
393 END_VAR;
394  mbusGetBufferLevel := INT(MODCALL("mod_mbus", "mbusGetBufferLevel", error));
395  IF NOT (error = 0) THEN
396  mbusGetBufferLevel := MBUS_MODCALL_ERR;
397  END_IF;
398 END_FUNCTION;
399 
400 #END_IF
mbusGetBufferLevel
static int mbusGetBufferLevel(void)
Get the actual level of how full the buffer is in promille.
Definition: mod_mbus.c:2043
mbusSend
static int mbusSend(int16 c, int8 *data, int8 size)
Send an M-BUS packet.
Definition: mod_mbus.c:1670
mbusClose
static int mbusClose(void)
Closes the communication interface.
Definition: mod_mbus.c:1512
mbusOpen
static int mbusOpen(int8 mode, int8 rssi)
Opens the connection to the M-Bus module.
Definition: mod_mbus.c:1558
MBUS_DATA_LENGTH
#define MBUS_DATA_LENGTH
Maximum size of a MBUS message not including header information.
Definition: mod_mbus.c:30