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 wmbus telegrams, decodes them and relays them to
20 some other software for further processing. It can for example listen
21 to radio traffic using dedicated wmbus dongles (eg
22 im871a,amb8465,cul,rc1180) or a software defined radio dongle (rtl_sdr)
23 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 --addconversions=<unit>[,<unit>] add conversion to these units for json
33 and shell envs (GJ,F)
34 --alarmexpectedactivity=mon-fri(08-17),sat-sun(09-12) Specify when the
36 timeout is tested, default is mon-sun(00-23)
37 --alarmshell=<cmdline> invokes cmdline when an alarm triggers
39 --alarmtimeout=<time> Expect a telegram to arrive within <time> sec‐
41 onds, eg 60s, 60m, 24h during expected activity
42 --analyze Analyze a telegram to find the best driver
44 --analyze=<key> Analyze a telegram to find the best driver and use the
46 provided decryption key.
47 --analyze=<driver> Analyze a telegram but use only this driver.
49 --analyze=<driver>:<key> Analyze a telegram and use only this driver
51 with this key. Add :verbose to any analyze to get more verbose analyze
52 output.
53 --debug for a lot of information
55 --device=<device> override device in config files. Use only in combina‐
57 tion with --useconfig= option
58 --donotprobe=<tty> do not auto-probe this tty. Use multiple times for
60 several ttys or specify "all" for all ttys
61 --exitafter=<time> exit program after time, eg 20h, 10m 5s
63 --format=(hr|json|fields) for human readable, json or semicolon sepa‐
65 rated fields
66 --help list all options
68 --ignoreduplicates=<bool> ignore duplicate telegrams, remember the last
70 10 telegrams. Default is true.
71 --field_xxx=yyy always add "xxx"="yyy" to the json output and add shell
73 env METER_xxx=yyy The field xxx can also be selected or added using se‐
74 lectfields=. Equivalent older command is --json_xxx=yyy.
75 --license print GPLv3+ license
77 --listento=<mode> listen to one of the c1,t1,s1,s1m,n1a-n1f link modes
79 --listento=<mode>,<mode> listen to more than one link mode at the same
81 time, assuming the dongle supports it
82 --listenvs=<meter_type> list the env variables available for the given
84 meter type
85 --listfields=<meter_type> list the fields selectable for the given me‐
87 ter type
88 --listmeters list all meter types
90 --listmeters=<search> list all meter types containing the text <search>
92 --listunits= list all unit suffixes that can be used for typing values
94 --logfile=<dir> use this file for logging
96 --logtelegrams log the contents of the telegrams for easy replay
98 --logtimestamps=<when> add timestamps to log entries: never/always/im‐
100 portant
101 --meterfiles=<dir> store meter readings in dir
103 --meterfilesaction=(overwrite|append) overwrite or append to the meter
105 readings file
106 --meterfilesnaming=(name|id|name-id) the meter file is the meter's:
108 name, id or name-id
109 --meterfilestimestamp=(never|day|hour|minute|micros) the meter file is
111 suffixed with a timestamp (localtime) with the given resolution.
112 --nodeviceexit if no wmbus devices are found, then exit immediately
114 --normal for normal logging
116 --oneshot wait for an update from each meter, then quit
118 --pollinterval=<interval> poll mbus meters every <interval>, default is
120 10m.
121 --ppjson pretty print the json output
123 --resetafter=<time> reset the wmbus dongle regularly, default is 23h
125 --selectfields=id,timestamp,total_m3 select only these fields to be
127 printed (--listfields=<meter> to list available fields)
128 --separator=<c> change field separator to c
130 --shell=<cmdline> invokes cmdline with env variables containing the
132 latest reading
133 --silent do not print informational messages nor warnings
135 --trace for tons of information
137 --useconfig=<dir> load config files from dir/etc
139 --usestderr write notices/debug/verbose and other logging output to
141 stderr (the default)
142 --usestdoutforlogging write debug/verbose and logging output to stdout
144 --verbose for more information
146 --version print version
148
151 auto:c1 detect any serially connected wmbus dongles and rtl_sdr dongles
152 and configure them for c1 mode.
153 Use auto to detect your dongle when testing, but then in produc‐
154 tion, state explicitly the dongle you are using. This will re‐
155 duce the amount of probing done on the serial ports.
156 im871a:t1 look for an im871a dongle attached to any of the serial ttys
159 and configure it for t1 mode.
160 im871a[12345678]:t1 look for the im871a dongle with this particular id.
163 /dev/ttyUSB0:amb8465:c1,t1 expect an amb8465 on this tty.
166 rtlwmbus use software defined radio rtl_sdr|rtl_wmbus to receive wmbus
169 telegrams.This defaults to 868.95MHz, use for example rtlwmbus:868.9M
170 to tune the rtl_sdr dongle to slightly lower frequency.
171 rtlwmbus[alfa]:433M:c1,t1 rtlwmbus[beta]:868.9M:c1,t1 Use two rtlsdr
174 dongles, one has its id set to alfa (using rtl_eeprom)
175 and the other set to beta. Alfa has an antenna tuned for 433M,
176 beta has an antenna suitable for 868.9M.
177 /dev/ttyUSB0:9600 read serial data from tty at 9600 bps, expects raw
180 wmbus frames with the DLL crcs removed.
181 MAIN=/dev/ttyUSB0:mbus:2400 expect an serial to mbus master converter
184 on ttyUSB0.
185 stdin:rtlwmbus read rtlwmbus formatted data from stdin.
188 myfile.txt:rtlwmbus read rtlwmbus formatted data from this file in‐
191 stead.
192 simulation_xxx.txt read telegrams from file to replay telegram feed
195 (use --logtelegrams to acquire feed for replay)
196 2e441122334455667788 decode the given hex string the hex string must
199 have only hex digits.
200 stdin:hex decode any hex found on stdin, non-hex characters are ig‐
203 nored.
204
207 meter_name a mnemonic for your utility meter
208 meter_type for example multical21:t1 (suffix means that we expect this
210 meter to transmit t1 telegrams)
211 meter_id one or more 8 digit numbers separated with commas, a single
213 '*' wildcard, or a prefix '76543*' with wildcard.
214 meter_key a unique key for the meter, if meter telegrams are not en‐
216 crypted, you must supply an empty key: ""
217
220 Wait for wmbus dongles to be inserted and then listen for c1 telegrams.
221 Print a summary of the telegram and whether wmbusmeters has a
222 driver for decoding it.
223 % wmbusmeters auto:c1
225 Listen to C1 traffic using an im871a dongle attached to some
227 tty.
228 % wmbusmeters im871a:c1
230 The im871a dongles have an id number that is printed when the
232 dongle is started. You can use this to specify which dongle to
233 use for which linkmode.
234 % wmbusmeters im871a[12345678]:c1 im871a[22334455]:t1
236 Listen to both T1 and C1 traffic using rtl_sdr|rtl_wmbus and the stan‐
239 dard frequency 868.95M, which
240 might need tweaking depending on the rtl_sdr dongle you are us‐
241 ing.
242 % wmbusmeters rtlwmbus:868.95M
244 You can identify rtlsdr dongles this way as well. The id of the
246 rtlsdr dongle is set using rtl_eeprom. Assuming you want to lis‐
247 ten to multiple frequencies, one dongle has one type of antenna
248 attached.
249 % wmbusmeters rtlwmbus[alfa]:433M:t1 rtlwmbus[beta]:868.9M:c1
251 You can query an mbus meter:
253 % wmbusmeters MAIN=/dev/ttyUSB0:mbus:2400 MyTempMeter pi‐
255 igth:MAIN:mbus 12001932 NOKEY
256 Execute using config file /home/me/etc/wmbusmeters.conf and meter con‐
259 fig files in /home/me/etc/wmbusmeters.d
260 % wmbusmeters --useconfig=/home/me
262 Start a daemon using config file /etc/wmbusmeters.conf and meter config
265 files in /etc/wmbusmeters.d
266 % wmbusmetersd --useconfig=/ /var/run/wmbusmeters/wmbusme‐
268 ters.pid
269 An example wmbusmeters.conf:
272 loglevel=normal
274 device=im871a[12345678]:c1
275 device=rtlwmbus:433M:c1,t1
276 logtelegrams=false
277 format=json
278 # Remember to remove meterfiles to spare precious flash memory when only
279 # relaying data using for example mqtt.
280 meterfiles=/var/lib/wmbusmeters/meter_readings
281 meterfilesaction=overwrite
282 meterfilesnaming=name
283 meterfilestimestamp=day
284 logfile=/var/log/wmbusmeters/wmbusmeters.log
285 shell=/usr/bin/mosquitto_pub -h localhost -t "wmbusmeters/$METER_ID" -m "$METER_JSON"
286 alarmshell=/usr/bin/mosquitto_pub -h localhost -t wmbusmeters_alarm -m "$ALARM_TYPE $ALARM_MESSAGE"
287 alarmtimeout=1h
288 alarmexpectedactivity=mon-sun(00-23)
289 ignoreduplicates=false
290 field_address=MyStreet 5
291 An example wmbusmeters.d file:
294 name=MyTapWater
296 type=multical21:c1
297 id=12345678
298 key=001122334455667788AABBCCDDEEFF
299 field_floor=4
300
303 Written by Fredrik Öhrström.
304
307 Copyright © 2017-2022 Fredrik Öhrström.
308 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
309 censes/gpl.html>.
310 This is free software: you are free to change and redistribute it.
311 There is NO WARRANTY, to the extent permitted by law.
312 WMBUSMETERS(1)