1WMBUSMETERS(1) General Commands Manual WMBUSMETERS(1)
2
6 wmbusmeters - listen to wireless mbus radio traffic and relay the de‐
7 coded telegrams to other software
8
11 wmbusmeters [options] <device>{:suffix} (<meter_name> <me‐
12 ter_type>[:<mode>] <meter_id> meter_key>)*
13 wmbusmeters [options] <hex> (<meter_name> <meter_type>[:<mode>] <me‐
15 ter_id> meter_key>)*
16 wmbusmetersd <pid_file>
18
21 Wmbusmeters acquires wmbus telegrams, decodes them and relays them to
22 some other software for further processing. It can for example listen
23 to radio traffic using dedicated wmbus dongles like
24 (im871a,amb8465,cul,rc1180) or a generic software defined radio dongle
25 (rtl_sdr) with an RTL2832U.
26 After the received telegram has been decrypted and parsed, it can then
28 be relayed using a shell command, or stored in a log file. The shell
29 commands can for example relay the telegram using MQTT (eg mqtt_pub‐
30 lish) sent to a REST API (eg curl) or store it in a database (eg psql).
31
34 --addconversions=<unit>[,<unit>] add conversion to these units for json
35 and shell envs (GJ,F)
36 --alarmexpectedactivity=mon-fri(08-17),sat-sun(09-12) Specify when the
38 timeout is tested, default is mon-sun(00-23)
39 --alarmshell=<cmdline> invokes cmdline when an alarm triggers
41 --alarmtimeout=<time> Expect a telegram to arrive within <time> sec‐
43 onds, eg 60s, 60m, 24h during expected activity
44 --debug for a lot of information
46 --device=<device> override device in config files. Use only in combina‐
48 tion with --useconfig= option
49 --donotprobe=<tty> do not auto-probe this tty. Use multiple times for
51 several ttys or specify "all" for all ttys
52 --exitafter=<time> exit program after time, eg 20h, 10m 5s
54 --format=(hr|json|fields) for human readable, json or semicolon sepa‐
56 rated fields
57 --help list all options
59 --ignoreduplicates=<bool> ignore duplicate telegrams, remember the last
61 10 telegrams. Default is true.
62 --field_xxx=yyy always add "xxx"="yyy" to the json output and add shell
64 env METER_xxx=yyy The field xxx can also be selected or added using se‐
65 lectfields=. Equivalent older command is --json_xxx=yyy.
66 --license print GPLv3+ license
68 --listento=<mode> listen to one of the c1,t1,s1,s1m,n1a-n1f link modes
70 --listento=<mode>,<mode> listen to more than one link mode at the same
72 time, assuming the dongle supports it
73 --listenvs=<meter_type> list the env variables available for the given
75 meter type
76 --listfields=<meter_type> list the fields selectable for the given me‐
78 ter type
79 --listmeters list all meter types
81 --listmeters=<search> list all meter types containing the text <search>
83 --listunits= list all unit suffixes that can be used for typing values
85 --logfile=<dir> use this file for logging
87 --logtelegrams log the contents of the telegrams for easy replay
89 --logtimestamps=<when> add timestamps to log entries: never/always/im‐
91 portant
92 --meterfiles=<dir> store meter readings in dir
94 --meterfilesaction=(overwrite|append) overwrite or append to the meter
96 readings file
97 --meterfilesnaming=(name|id|name-id) the meter file is the meter's:
99 name, id or name-id
100 --meterfilestimestamp=(never|day|hour|minute|micros) the meter file is
102 suffixed with a timestamp (localtime) with the given resolution.
103 --nodeviceexit if no wmbus devices are found, then exit immediately
105 --oneshot wait for an update from each meter, then quit
107 --resetafter=<time> reset the wmbus dongle regularly, default is 23h
109 --selectfields=id,timestamp,total_m3 select only these fields to be
111 printed (--listfields=<meter> to list available fields)
112 --separator=<c> change field separator to c
114 --shell=<cmdline> invokes cmdline with env variables containing the
116 latest reading
117 --silent do not print informational messages nor warnings
119 --trace for tons of information
121 --useconfig=<dir> load config files from dir/etc
123 --usestderr write notices/debug/verbose and other logging output to
125 stderr (the default)
126 --usestdoutforlogging write debug/verbose and logging output to stdout
128 --verbose for more information
130 --version print version
132
135 auto:c1 detect any serially connected wmbus dongles and rtl_sdr dongles
136 and configure them for c1 mode. Always try to use auto first.
137 im871a:t1 look for an im871a dongle attached to any of the serial ttys
140 and configure it for t1 mode.
141 im871a[12345678]:t1 look for the im871a dongle with this particular id.
144 /dev/ttyUSB0:amb8465:c1,t1 expect an amb8465 on this tty.
147 rtlwmbus use software defined radio rtl_sdr|rtl_wmbus to receive wmbus
150 telegrams.This defaults to 868.95MHz, use for example rtlwmbus:868.9M
151 to tune the rtl_sdr dongle to slightly lower frequency.
152 rtlwmbus[alfa]:433M:c1,t1 rtlwmbus[beta]:868.9M:c1,t1 Use two rtlsdr
155 dongles, one has its id set to alfa (using rtl_eeprom)
156 and the other set to beta. Alfa has an antenna tuned for 433M,
157 beta has an antenna suitable for 868.9M.
158 /dev/ttyUSB0:9600 read serial data from tty at 9600 bps, expects raw
161 wmbus frames with the DLL crcs removed.
162 stdin:rtlwmbus read rtlwmbus formatted data from stdin.
165 myfile.txt:rtlwmbus read rtlwmbus formatted data from this file in‐
168 stead.
169 simulation_xxx.txt read telegrams from file to replay telegram feed
172 (use --logtelegrams to acquire feed for replay)
173 2e441122334455667788 decode the given hex string the hex string must
176 have only hex digits.
177 stdin:hex decode any hex found on stdin, non-hex characters are ig‐
180 nored.
181
184 meter_name a mnemonic for your utility meter
185 meter_type for example multical21:t1 (suffix means that we expect this
187 meter to transmit t1 telegrams)
188 meter_id one or more 8 digit numbers separated with commas, a single
190 '*' wildcard, or a prefix '76543*' with wildcard.
191 meter_key a unique key for the meter, if meter telegrams are not en‐
193 crypted, you must supply an empty key: ""
194
197 Wait for wmbus dongles to be inserted and then listen for c1 telegrams.
198 Print a summary of the telegram and whether wmbusmeters has a
199 driver for decoding it.
200 % wmbusmeters auto:c1
202 Listen to C1 traffic using an im871a dongle attached to some
204 tty.
205 % wmbusmeters im871a:c1
207 The im871a dongles have an id number that is printed when the
209 dongle is started. You can use this to specify which dongle to
210 use for which linkmode.
211 % wmbusmeters im871a[12345678]:c1 im871a[22334455]:t1
213 Listen to both T1 and C1 traffic using rtl_sdr|rtl_wmbus and the stan‐
216 dard frequency 868.95M, which
217 might need tweaking depending on the rtl_sdr dongle you are us‐
218 ing.
219 % wmbusmeters rtlwmbus:868.95M
221 You can identify rtlsdr dongles this way as well. The id of the
223 rtlsdr dongle is set using rtl_eeprom. Assuming you want to lis‐
224 ten to multiple frequencies, one dongle has one type of antenna
225 attached.
226 % wmbusmeters rtlwmbus[alfa]:433M:t1 rtlwmbus[beta]:868.9M:c1
228 Execute using config file /home/me/etc/wmbusmeters.conf and meter con‐
231 fig files in /home/me/etc/wmbusmeters.d
232 % wmbusmeters --useconfig=/home/me
234 Start a daemon using config file /etc/wmbusmeters.conf and meter config
237 files in /etc/wmbusmeters.d
238 % wmbusmetersd --useconfig=/ /var/run/wmbusmeters/wmbusme‐
240 ters.pid
241 An example wmbusmeters.conf:
244 loglevel=normal
246 device=im871a[12345678]:c1
247 device=rtlwmbus:433M:c1,t1
248 logtelegrams=false
249 format=json
250 meterfiles=/var/log/wmbusmeters/meter_readings
251 meterfilesaction=overwrite
252 meterfilesnaming=name
253 meterfilestimestamp=day
254 logfile=/var/log/wmbusmeters/wmbusmeters.log
255 shell=/usr/bin/mosquitto_pub -h localhost -t "wmbusmeters/$METER_ID" -m "$METER_JSON"
256 alarmshell=/usr/bin/mosquitto_pub -h localhost -t wmbusmeters_alarm -m "$ALARM_TYPE $ALARM_MESSAGE"
257 alarmtimeout=1h
258 alarmexpectedactivity=mon-sun(00-23)
259 ignoreduplicates=false
260 json_address=MyStreet 5
261 An example wmbusmeters.d file:
264 name=MyTapWater
266 type=multical21:c1
267 id=12345678
268 key=001122334455667788AABBCCDDEEFF
269 json_floor=4
270
273 Written by Fredrik Öhrström.
274
277 Copyright © 2017-2020 Fredrik Öhrström.
278 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
279 censes/gpl.html>.
280 This is free software: you are free to change and redistribute it.
281 There is NO WARRANTY, to the extent permitted by law.
282 WMBUSMETERS(1)