Radiocraft Wireless M-Bus extension module  1.00.00
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 // length - The length of the additional data in the frame.
37 // data - The additional data that was received.
38 // Only the first <length> bytes are valid.
39 //
40 //----------------------------------------------------------------------------
41 STRUCT_BLOCK ALIGN mbusFrame;
42  control : SINT; // Control field
43 
44  // Address
45  manufacturer : INT; // Manufacture ID
46  id : DINT; // Device Identification number
47  version : SINT; // Device Version number
48  type : SINT; // Device Type
49 
50  // APP_DATA
51  RSSI : INT; // signal strength in dB = - RSSI/2
52  length : INT; // Length of additional data
53  data : ARRAY[1 .. MBUS_DATA_LENGTH] OF SINT;
54 END_STRUCT_BLOCK;
55 
56 //----------------------------------------------------------------------------
57 // mbusInit()
58 //
59 // Description:
60 // Initializes the M-Bus extension module.
61 //
62 // Input:
63 // showTags - Print the tags from the module to the device output.
64 // path - The path to the module to initialize. Optional, as the default value is already correct.
65 // media - The media the module is located on. Optional, as the default value is already correct.
66 //
67 // Returns:
68 // 0 : OK
69 // -1 : Failed to open media
70 // -2 : Failed show tags
71 // -3 : Failed to load module
72 //----------------------------------------------------------------------------
73 FUNCTION ALIGN mbusInit : INT;
74 VAR_INPUT
75  showTags : BOOL := FALSE;
76  path : STRING := MBUS_MODULE_PATH;
77  media : SINT := MBUS_MODULE_MEDIA;
78 END_VAR;
79 VAR
80  rc : INT;
81  index : INT;
82  text : STRING;
83  tag : STRING;
84 END_VAR;
85 
86 // Initialize media where module is located
87 rc := fsMediaOpen(media := media);
88 IF NOT (rc = 0) THEN
89  DebugFmt(message := "Failed to open media \1 (err \2)", v1 := media, v2 := rc);
90  mbusInit := -1;
91  RETURN;
92 END_IF;
93 
94 IF showTags THEN
95  DebugMsg(message := "Extension: " + path);
96  FOR index := 1 TO 10 DO
97  // Read the name of a tag
98  rc:=extTagEnumerate(path:=path, index:=index, tag:=tag);
99  IF (rc = 1) THEN
100  // Read the text of a tag
101  rc := extTagRead(path:=path,tag:=tag,text:=text);
102  IF (rc = 1) THEN
103  DebugFmt(message := "[\1] : '" + strLeft(str := tag + "' ", length := 13) + "= '" + text + "'", v1 := index);
104  ELSE
105  DebugFmt(message := "[\1] : Failed to read '" + tag + "' (err \2)", v1 := index, v2 := rc);
106  END_IF;
107  ELSIF (rc = -3) THEN
108  // No more tags
109  EXIT;
110  ELSE
111  DebugFmt(message := "[\1] : Failed to read tag name (err \2)", v1 := index, v2 := rc);
112  mbusInit := -2;
113  RETURN;
114  END_IF;
115  END_FOR;
116 END_IF;
117 
118 // Load an extension module
119 rc := extModuleLoad(path:=path);
120 IF NOT (rc = 1) THEN
121  DebugFmt(message := "Failed to load module " + path + "(err \1)", v1 := rc);
122  mbusInit := -3;
123  RETURN;
124 END_IF;
125 
126 DebugMsg(message := "Module '" + path + "' loaded");
127 mbusInit := 0;
128 END_FUNCTION;
129 
130 //----------------------------------------------------------------------------
131 // mbusOpen()
132 //
133 // Description:
134 // Opens the connection to the M-Bus module.
135 //
136 // Input:
137 // mode - The M-Bus mode to use. See the MBUS_MODE_* defines above.
138 // RSSI - Include the signal strength( RSSI) for each valid packet.
139 // It can be read from mbusReceive()
140 //
141 // Returns:
142 // 0: Success
143 // -1: Failed to open the M-Bus interface.
144 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
145 //----------------------------------------------------------------------------
146 FUNCTION ALIGN mbusOpen : INT;
147 VAR_INPUT
148  mode: SINT := MBUS_MODE_T1;
149  RSSI: BOOL := OFF;
150 END_VAR;
151 VAR
152  error : INT;
153 END_VAR;
154  mbusOpen := INT(MODCALL("mod_mbus", "mbusOpen", error));
155  IF NOT (error = 0) THEN
156  DebugFmt(message := "MBUS: failed to call external module 'mbusOpen' (err \1)", v1 := error);
157  mbusOpen := MBUS_MODCALL_ERR;
158  END_IF;
159 END_FUNCTION;
160 
161 //----------------------------------------------------------------------------
162 // mbusClose()
163 //
164 // Description:
165 // Closes the connection to the M-Bus module.
166 //
167 // Input:
168 // None.
169 //
170 // Returns:
171 // 0: Success
172 // -1: Failed to close the M-Bus interface.
173 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
174 //----------------------------------------------------------------------------
175 FUNCTION ALIGN mbusClose : INT;
176 VAR
177  error : INT;
178 END_VAR;
179  mbusClose := INT(MODCALL("mod_mbus", "mbusClose", error));
180  IF NOT (error = 0) THEN
181  DebugFmt(message := "MBUS: failed to call external module 'mbusClose' (err \1)", v1 := error);
182  mbusClose := MBUS_MODCALL_ERR;
183  END_IF;
184 END_FUNCTION;
185 
186 //----------------------------------------------------------------------------
187 // mbusSend()
188 //
189 // Description:
190 // Sends data to the M-Bus module.
191 //
192 // Input:
193 // control - The M-Bus mode to use. See the MBUS_MODE_* defines above. 0-255.
194 // length - The length of the data to send. Max 246 bytes.
195 // data - The data to send.
196 //
197 // Returns:
198 // 0: Success
199 // -1: Invalid parameter.
200 // -2: Failed to send data.
201 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
202 //----------------------------------------------------------------------------
203 FUNCTION ALIGN mbusSend : INT;
204 VAR_INPUT
205  control : INT := -1; // (-1, 0 .. 255) :change control byte before send
206  length : INT := 0; // (0 .. MBUS_DATA_LENGTH) : length of data to send
207  data : PTR; // data to send
208 END_VAR;
209 VAR
210  error : INT;
211 END_VAR;
212  mbusSend := INT(MODCALL("mod_mbus", "mbusSend", error));
213  IF NOT (error = 0) THEN
214  DebugFmt(message := "MBUS: failed to call external module 'mbusSend' (err \1)", v1 := error);
215  mbusSend := MBUS_MODCALL_ERR;
216  END_IF;
217 END_FUNCTION;
218 
219 //----------------------------------------------------------------------------
220 // mbusReceive()
221 //
222 // Description:
223 // Receives data from the M-Bus module.
224 //
225 // Input:
226 // None.
227 //
228 // Output:
229 // frame - The provided struct is filled with the values of a received M-Bus frame.
230 //
231 // Returns:
232 // 1: Data was received.
233 // 0: No data
234 // -1: Communicaton error
235 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
236 //----------------------------------------------------------------------------
237 FUNCTION ALIGN mbusReceive;
238 VAR_INPUT
239  frame : ACCESS mbusFrame;
240 END_VAR;
241 VAR
242  error : INT;
243 END_VAR;
244  mbusReceive := INT(MODCALL("mod_mbus", "mbusReceive", error));
245  IF NOT (error = 0) THEN
246  DebugFmt(message := "MBUS: failed to call external module 'mbusReceive' (err \1)", v1 := error);
247  mbusReceive := MBUS_MODCALL_ERR;
248  END_IF;
249 END_FUNCTION;
250 
251 //----------------------------------------------------------------------------
252 // mbusInfo()
253 //
254 // Description:
255 // Sends some information about the M-Bus module to the device output.
256 // Example output:
257 //
258 // mbus_test:Signal quality = 0
259 // mbus_test:RSSI = 205 (-102 dBm)
260 // mbus_test:Temperature = 32 C
261 // mbus_test:VCC = 3450mV
262 // mbus_test:MBUS_MODE = 0x01
263 // mbus_test:DATA_INTERFACE = 0x00
264 // mbus_test:PART_NUMBER = RC1180-MBUS3
265 // mbus_test:HW_REV_NO = 2.00
266 // mbus_test:FW_REV_NO = 3.15
267 // mbus_info:SERIAL_NUMBER = 01 23 45 67 89 AB CD EF
268 // mbus_info:INSTALL_MODE = 0x02
269 // mbus_info:RSSI_MODE = 0x01
270 //
271 // Input:
272 // None.
273 //
274 // Returns:
275 // 0: Success
276 // -1: Communicaton error.
277 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
278 //----------------------------------------------------------------------------
279 FUNCTION mbusInfo : INT;
280 VAR
281  error : INT;
282 END_VAR;
283  mbusInfo := INT(MODCALL("mod_mbus", "mbusInfo", error));
284  IF NOT (error = 0) THEN
285  DebugFmt(message := "MBUS: failed to call external module 'mbusInfo' (err \1)", v1 := error);
286  mbusInfo := MBUS_MODCALL_ERR;
287  END_IF;
288 END_FUNCTION;
289 
290 
291 //----------------------------------------------------------------------------
292 // mbusRegisterSlave()
293 //
294 // Description:
295 // Registers/installs a slave device on the M-Bus module.
296 // This is necessary when filtering or when using encryption.
297 //
298 // Input:
299 // idx - The index of the slave to register. 1-64.
300 // manufacturer - The ID of the manufacturer. Part of the device address.
301 // id - The device identification number/serial number. Part of the device address.
302 // version - The device version. Part of the device address.
303 // type - The device type. Part of the device address.
304 // key - The 16 byte (128 bit) encryption key. Can be left empty if encryption is not used.
305 //
306 // Returns:
307 // 0: Success
308 // -1: Communicaton error.
309 // -2: Invalid idx.
310 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
311 //----------------------------------------------------------------------------
312 FUNCTION mbusRegisterSlave : INT;
313 VAR_INPUT
314  idx : INT := 1;
315  manufacturer : MANDATORY INT;
316  id : MANDATORY DINT;
317  version : MANDATORY SINT;
318  type : MANDATORY SINT;
319  key : PTR;
320 END_VAR;
321 VAR
322  error : INT;
323 END_VAR;
324  mbusRegisterSlave := INT(MODCALL("mod_mbus", "mbusRegisterSlave", error));
325  IF NOT (error = 0) THEN
326  DebugFmt(message := "MBUS: failed to call external module 'mbusRegisterSlave' (err \1)", v1 := error);
327  mbusRegisterSlave := MBUS_MODCALL_ERR;
328  END_IF;
329 END_FUNCTION;
330 
331 //----------------------------------------------------------------------------
332 // mbusSetFilter()
333 //
334 // Description:
335 // Enables/disables filtering of the received packets, to only receive packets from registered slave devices.
336 //
337 // Input:
338 // installed - Set to true to only show packets from installed slaves.
339 //
340 // Returns:
341 // 0: Success
342 // -1: Communicaton error.
343 // -2: Invalid idx.
344 // -999 (MBUS_MODCALL_ERR): Failed to find function in extension module.
345 //----------------------------------------------------------------------------
346 FUNCTION mbusSetFilter : INT;
347 VAR_INPUT
348  installed : BOOL := TRUE;
349 END_VAR;
350 VAR
351  error : INT;
352 END_VAR;
353  mbusSetFilter := INT(MODCALL("mod_mbus", "mbusSetFilter", error));
354  IF NOT (error = 0) THEN
355  DebugFmt(message := "MBUS: failed to call external module 'mbusSetFilter' (err \1)", v1 := error);
356  mbusSetFilter := MBUS_MODCALL_ERR;
357  END_IF;
358 END_FUNCTION;
359 
360 #END_IF
static int mbusOpen(int8 mode, int8 rssi)
Opens the connection to the M-Bus module.
Definition: mod_mbus.c:919
static int mbusSend(int16 c, int8 *data, int8 size)
Send an M-BUS packet.
Definition: mod_mbus.c:1020
static int mbusReceive(tdef_mbus_start_frame *start, int8 *data, int16 *rssi)
Receive a new frame from the M-Bus module.
Definition: mod_mbus.c:1105
static int mbusClose(void)
Closes the communication interface.
Definition: mod_mbus.c:884
#define MBUS_DATA_LENGTH
Maximum size of a MBUS message not including header information.
Definition: mod_mbus.c:28