1WMBUSMETERS(1) General Commands Manual WMBUSMETERS(1)
2
6 wmbusmeters - Acquire,query and decode wired and wireless mbus tele‐
7 grams, then relay the telegrams to other software.
8
11 wmbusmeters {options} [device]+ { [name] [driver] [id] [key] }*
12 wmbusmeters {options} [hex] { [name] [driver] [id] [key] }*
14 wmbusmetersd {options} [pid_file>]
16
19 Wmbusmeters acquires wired or wireless mbus telegrams, decodes them and
20 relays them to some other software for further processing. It can for
21 example listen to radio traffic using dedicated wmbus dongles (eg
22 im871a,im170a,amb8465, amb8335,cul,rc1180) or a software defined radio
23 dongle (rtl_sdr) with an RTL2832U (decoded using rtl_wmbus, rtl_433).
24 After the acquired telegram has been decrypted and parsed, it can then
26 be relayed using a shell command, or stored in a log file. The shell
27 commands can for example relay the telegram using MQTT (eg mqtt_pub‐
28 lish) sent to a REST API (eg curl) or store it in a database (eg psql).
29
32 --alarmexpectedactivity=mon-fri(08-17),sat-sun(09-12) Specify when the
33 timeout is tested, default is mon-sun(00-23)
34 --alarmshell=<cmdline> invokes cmdline when an alarm triggers
36 --alarmtimeout=<time> Expect a telegram to arrive within <time> sec‐
38 onds, eg 60s, 60m, 24h during expected activity
39 --analyze Analyze a telegram to find the best driver
41 --analyze=<key> Analyze a telegram to find the best driver and use the
43 provided decryption key.
44 --analyze=<driver> Analyze a telegram but use only this driver.
46 --analyze=<driver>:<key> Analyze a telegram and use only this driver
48 with this key. Add :verbose to any analyze to get more verbose analyze
49 output.
50 --calculate_xxx_yyy=... Add xxx_yyy to the json and calculate it using
52 the formula. E.g. --calculate_sumtemp_c='external_tempera‐
53 ture_c+flow_temperature_c' --calculate_flow_f=flow_temperature_c Units
54 are automatically translated if possible.
55 --debug for a lot of information
57 --donotprobe=<tty> do not auto-probe this tty. Use multiple times for
59 several ttys or specify "all" for all ttys
60 --exitafter=<time> exit program after time, eg 20h, 10m 5s
62 --format=(hr|json|fields) for human readable, json or semicolon sepa‐
64 rated fields
65 --help list all options
67 --ignoreduplicates=<bool> ignore duplicate telegrams, remember the last
69 10 telegrams. Default is true.
70 --field_xxx=yyy always add "xxx"="yyy" to the json output and add shell
72 env METER_xxx=yyy The field xxx can also be selected or added using se‐
73 lectfields=. Equivalent older command is --json_xxx=yyy.
74 --license print GPLv3+ license
76 --listento=<mode> listen to one of the c1,t1,s1,s1m,n1a-n1f link modes
78 --listento=<mode>,<mode> listen to more than one link mode at the same
80 time, assuming the dongle supports it
81 --listenvs=<meter_type> list the env variables available for the given
83 meter type
84 --listfields=<meter_type> list the fields selectable for the given me‐
86 ter type
87 --listmeters list all meter types
89 --listmeters=<search> list all meter types containing the text <search>
91 --listunits= list all unit suffixes that can be used for typing values
93 --logfile=<dir> use this file for logging or --logfile=syslog
95 --logtelegrams log the contents of the telegrams for easy replay
97 --logtimestamps=<when> add timestamps to log entries: never/always/im‐
99 portant
100 --meterfiles=<dir> store meter readings in dir
102 --meterfilesaction=(overwrite|append) overwrite or append to the meter
104 readings file
105 --meterfilesnaming=(name|id|name-id) the meter file is the meter's:
107 name, id or name-id
108 --meterfilestimestamp=(never|day|hour|minute|micros) the meter file is
110 suffixed with a timestamp (localtime) with the given resolution.
111 --nodeviceexit if no wmbus devices are found, then exit immediately
113 --normal for normal logging
115 --oneshot wait for an update from each meter, then quit
117 --overridedevice=<device> override device in config files. Can only be
119 used in combination with --useconfig= option
120 --pollinterval=<interval> poll mbus meters every <interval>, default is
122 10m.
123 --ppjson pretty print the json output
125 --resetafter=<time> reset the wmbus dongle regularly, default is 23h
127 --selectfields=id,timestamp,total_m3 select only these fields to be
129 printed (--listfields=<meter> to list available fields)
130 --separator=<c> change field separator to c
132 --shell=<cmdline> invokes cmdline with env variables containing the
134 latest reading
135 --silent do not print informational messages nor warnings
137 --trace for tons of information
139 --useconfig=<dir> load config <dir>/wmbusmeters.conf and meters from
141 <dir>/wmbusmeters.d
142 --usestderr write notices/debug/verbose and other logging output to
144 stderr (the default)
145 --usestdoutforlogging write debug/verbose and logging output to stdout
147 --verbose for more information
149 --version print version
151
154 auto:c1 detect any serially connected wmbus dongles and rtl_sdr dongles
155 and configure them for c1 mode.
156 Use auto to detect your dongle when testing, but then in produc‐
157 tion, state explicitly the dongle you are using. This will sig‐
158 nificantly reduce the amount of probing done on the serial
159 ports.
160 im871a:t1 look for an im871a dongle attached to any of the serial ttys
163 and configure it for t1 mode.
164 im871a[12345678]:t1 look for the im871a dongle with this particular id.
167 /dev/ttyUSB0:amb8465:c1,t1 expect an amb8465 on this tty.
170 rtlwmbus use software defined radio rtl_sdr|rtl_wmbus to receive wmbus
173 telegrams.This defaults to 868.95MHz, use for example rtlwmbus:868.9M
174 to tune the rtl_sdr dongle to slightly lower frequency.
175 rtlwmbus[alfa]:433M:c1,t1 rtlwmbus[beta]:868.9M:c1,t1 Use two rtlsdr
178 dongles, one has its id set to alfa (using rtl_eeprom)
179 and the other set to beta. Alfa has an antenna tuned for 433M,
180 beta has an antenna suitable for 868.9M.
181 /dev/ttyUSB0:9600 read serial data from tty at 9600 bps, expects raw
184 wmbus frames with the DLL crcs removed.
185 MAIN=/dev/ttyUSB0:mbus:2400 expect an serial to mbus master converter
188 on ttyUSB0.
189 stdin:rawtty read binary telegrams (without dll crc:s) from stdin.
192 filename:rawtty read binary telegrams from the file.
195 stdin:hex decode any hex found on stdin, non-hex characters are ig‐
198 nored.
199 stdin:rtlwmbus read rtlwmbus formatted data from stdin.
202 myfile.txt:rtlwmbus read rtlwmbus formatted data from this file in‐
205 stead.
206 simulation_xxx.txt read telegrams from file to replay telegram feed
209 (use --logtelegrams to acquire feed for replay)
210 2e441122334455667788 decode the given hex string the hex string must
213 have only hex digits or underscores.
214
217 meter_name a mnemonic for your utility meter
218 meter_type for example multical21:t1 (suffix means that we expect this
220 meter to transmit t1 telegrams) the driver auto can be used, but is not
221 recommended for production.
222 meter_id one or more 8 digit numbers separated with commas, a single
224 '*' wildcard, or a prefix '76543*' with wildcard.
225 meter_key a unique key for the meter, if meter telegrams are not en‐
227 crypted, you must supply an empty key: ""
228
231 Wait for wmbus dongles to be inserted and then listen for c1 telegrams.
232 Print a summary of the telegram and whether wmbusmeters has a
233 driver for decoding it.
234 % wmbusmeters auto:c1
236 Listen to C1 traffic using an im871a dongle attached to some
238 tty.
239 % wmbusmeters im871a:c1
241 The im871a dongles have an id number that is printed when the
243 dongle is started. You can use this to specify which dongle to
244 use for which linkmode.
245 % wmbusmeters im871a[12345678]:c1 im871a[22334455]:t1
247 Listen to both T1 and C1 traffic using rtl_sdr|rtl_wmbus and the stan‐
250 dard frequency 868.95M, which
251 might need tweaking depending on the rtl_sdr dongle you are us‐
252 ing.
253 % wmbusmeters rtlwmbus:868.95M
255 You can identify rtlsdr dongles this way as well. The id of the
257 rtlsdr dongle is set using rtl_eeprom. Assuming you want to lis‐
258 ten to multiple frequencies, one dongle has one type of antenna
259 attached.
260 % wmbusmeters rtlwmbus[alfa]:433M:t1 rtlwmbus[beta]:868.9M:c1
262 You can query an mbus meter:
264 % wmbusmeters MAIN=/dev/ttyUSB0:mbus:2400 MyTempMeter pi‐
266 igth:MAIN:mbus 12001932 NOKEY
267 Execute using config file /home/me/etc/wmbusmeters.conf and meter con‐
270 fig files in /home/me/etc/wmbusmeters.d
271 % wmbusmeters --useconfig=/home/me
273 Start a daemon using config file /etc/wmbusmeters.conf and meter config
276 files in /etc/wmbusmeters.d
277 % wmbusmetersd --useconfig=/ /var/run/wmbusmeters/wmbusme‐
279 ters.pid
280 An example wmbusmeters.conf:
283 loglevel=normal
285 device=im871a[12345678]:c1
286 device=rtlwmbus:433M:c1,t1
287 logtelegrams=false
288 format=json
289 # Remember to remove meterfiles to spare precious flash memory when only
290 # relaying data using for example mqtt.
291 meterfiles=/var/lib/wmbusmeters/meter_readings
292 meterfilesaction=overwrite
293 meterfilesnaming=name
294 meterfilestimestamp=day
295 logfile=/var/log/wmbusmeters/wmbusmeters.log
296 shell=/usr/bin/mosquitto_pub -h localhost -t "wmbusmeters/$METER_ID" -m "$METER_JSON"
297 alarmshell=/usr/bin/mosquitto_pub -h localhost -t wmbusmeters_alarm -m "$ALARM_TYPE $ALARM_MESSAGE"
298 alarmtimeout=1h
299 alarmexpectedactivity=mon-sun(00-23)
300 ignoreduplicates=false
301 field_address=MyStreet 5
302 An example wmbusmeters.d file:
305 name=MyTapWater
307 driver=multical21:c1
308 id=12345678
309 key=001122334455667788AABBCCDDEEFF
310 field_floor=4
311 You can use the driver auto, but it is not recommended for production.
314 The auto driver might change over time to better versions of the driver with new names,
315 whereas a fixed driver name should generate backwards compatible json.
316
319 Written by Fredrik Öhrström.
320
323 Copyright © 2017-2022 Fredrik Öhrström.
324 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
325 censes/gpl.html>.
326 This is free software: you are free to change and redistribute it.
327 There is NO WARRANTY, to the extent permitted by law.
328 WMBUSMETERS(1)