wmbusmeters - Man Page

listen to wireless mbus radio traffic and relay the decoded telegrams to other software

Synopsis

wmbusmeters [options] <device>{:suffix} (<meter_name> <meter_type>[:<mode>] <meter_id> meter_key>)*

wmbusmetersd <pid_file>

Description

Wmbusmeters acquires wmbus telegrams, decodes them and relays them to some other software for further processing.  It can for example listen to radio traffic using dedicated wmbus dongles like (im871a amb8465 rfmrx2 cul d1tc) or a generic software defined radio dongle (rtl_sdr).

After the received telegram has been decrypted and parsed, it can then be relayed using a shell command, or stored in a log file.  The shell commands can for example relay the telegram using MQTT (eg mqtt_publish) sent to a REST API (eg curl) or store it in a database (eg psql).

Options

--addconversions=<unit>[,<unit>] add conversion to these units for json and shell envs (GJ,F)

--alarmexpectedactivity=
mon-fri(08-17),sat-sun(09-12) Specify when the timeout is tested, default is mon-sun(00-23)

--alarmshell=<cmdline> invokes cmdline when an alarm triggers

--alarmtimeout=<time> Expect a telegram to arrive within <time> seconds, eg 60s, 60m, 24h during expected activity.

--debug
for a lot of information

--donotprobe=<tty> do not auto-probe this tty. Use multiple times for several ttys or specify "all" for all ttys.

--exitafter=<time> exit program after time, eg 20h, 10m 5s

--format=
(hr|json|fields) for human readable, json or semicolon separated fields

--ignoreduplicates=true ignore telegram duplicates (when using multiple receiving dongles or repeaters)

--json_xxx=yyy
always add "xxx"="yyy" to the json output and add shell env METER_xxx=yyy

--listento=<mode> listen to one of the c1,t1,s1,s1m,n1a-n1f link modes.

--listento=<mode>,<mode> listen to more than one link mode at the same time, assuming the dongle supports it.

--logtimestamps=<when> add timestamps to log entries: never/always/important.

--c1 --t1 --s1 --s1m --n1a ... --n1f
listen to c1,t1,s1,s1m,n1a-n1f telegrams.

--listenvs=<meter_type> list the env variables available for the given meter type

--listfields=<meter_type> list the fields selectable for the given meter type

--listmeters
list all meter types

--listmeters=<search> list all meter types containing the text <search>

--logfile=<dir> use this file instead of stdout

--logtelegrams
log the contents of the telegrams for easy replay

--meterfiles=<dir> store meter readings in dir

--meterfilesaction=
(overwrite|append) overwrite or append to the meter readings file
--meterfilesnaming=
(name|id|name-id) the meter file is the meter's: name, id or name-id
--meterfilestimestamp=
(never|day|hour|minute|micros) the meter file is suffixed with a timestamp (localtime) with the given resolution.
--nodeviceexit
if no wmbus devices are found, then exit immediately
--oneshot
wait for an update from each meter, then quit

--resetafter=<time> reset the wmbus dongle regularly, default is 24h

--separator=<c> change field separator to c

--selectfields=
id,timestamp,total_m3 select fields to be printed (--listfields=<meter> to list available fields)

--separator=<c> change field separator to c

--shell=<cmdline> invokes cmdline with env variables containing the latest reading

--silent
do not print informational messages nor warnings

--useconfig=<dir> load config files from dir/etc

--usestderr
write notices/debug/verbose and other logging output to stderr (the default)
--usestdoutforlogging
write debug/verbose and logging output to stdout
--verbose
for more information

Devices

auto:c1 detect any serially connected wmbus dongles and rtl_sdr dongles and configure them for c1 mode. (You do not need to use --c1 or --listento=c1 when suffixing the device with the linkmode.) Always try to use auto first.
im871a:t1 look for an im871a dongle attached to any of the serial ttys and configure it for t1 mode.
im871a[12345678]:t1 look for the im871a dongle with this particular id.
/dev/ttyUSB0:amb8465:c1,t1 expect an amb8465 on this tty.
rtlwmbus use software defined radio rtl_sdr|rtl_wmbus to receive wmbus telegrams.This defaults to 868.95MHz, use for example rtlwmbus:868.9M to tune the rtl_sdr dongle to slightly lower frequency.
rtlwmbus[alfa]:433M:c1,t1 rtlwmbus[beta]:868.9M:c1,t1 Use two rtlsdr dongles, one has its id set to alfa (using rtl_eeprom)

and the other set to beta. Alfa has an antenna tuned for 433M, beta has an antenna suitable for 868.9M.

/dev/ttyUSB0:9600 read serial data from tty at 9600 bps, expects raw wmbus frames with the DLL crcs removed.

stdin:rtlwmbus read rtlwmbus formatted data from stdin.

myfile.txt:rtlwmbus read rtlwmbus formatted data from this file instead.

simulation_xxx.txt read telegrams from file to replay telegram feed (use --logtelegrams to acquire feed for replay)

Meter Quadruples

meter_name a mnemonic for your utility meter

meter_type for example multical21:t1 (suffix means that we expect this meter to transmit t1 telegrams)

meter_id one or more 8 digit numbers separated with commas, a single '*' wildcard, or a prefix '76543*' with wildcard.

meter_key a unique key for the meter, if meter telegrams are not encrypted, you must supply an empty key: ""

Examples

Wait for wmbus dongles to be inserted and then listen for c1 telegrams.

Print a summary of the telegram and whether wmbusmeters has a driver for decoding it.

% wmbusmeters auto:c1

Listen to C1 traffic using an im871a dongle attached to some tty.

% wmbusmeters im871a:c1

The im871a dongles have an id number that is printed when the dongle is started. You can use this to specify which dongle to use for which linkmode.

% wmbusmeters im871a[12345678]:c1 im871a[22334455]:t1

Listen to both T1 and C1 traffic using rtl_sdr|rtl_wmbus and the standard frequency 868.95M, which

might need tweaking depending on the rtl_sdr dongle you are using.

% wmbusmeters rtlwmbus:868.95M

You can identify rtlsdr dongles this way as well. The id of the rtlsdr dongle is set using rtl_eeprom. Assuming you want to listen to multiple frequencies, one dongle has one type of antenna attached.

% wmbusmeters rtlwmbus[alfa]:433M:t1 rtlwmbus[beta]:868.9M:c1

Execute using config file /home/me/etc/wmbusmeters.conf and meter config files in /home/me/etc/wmbusmeters.d

% wmbusmeters --useconfig=/home/me

Start a daemon using config file /etc/wmbusmeters.conf and meter config files in /etc/wmbusmeters.d

% wmbusmetersd --useconfig=/ /var/run/wmbusmeters/wmbusmeters.pid

An example wmbusmeters.conf:
loglevel=normal
device=im871a[12345678]:c1
device=rtlwmbus:433M:c1,t1
logtelegrams=false
format=json
meterfiles=/var/log/wmbusmeters/meter_readings
meterfilesaction=overwrite
meterfilesnaming=name
meterfilestimestamp=day
logfile=/var/log/wmbusmeters/wmbusmeters.log
shell=/usr/bin/mosquitto_pub -h localhost -t "wmbusmeters/$METER_ID" -m "$METER_JSON"
alarmshell=/usr/bin/mosquitto_pub -h localhost -t wmbusmeters_alarm -m "$ALARM_TYPE $ALARM_MESSAGE"
alarmtimeout=1h
alarmexpectedactivity=mon-sun(00-23)
ignoreduplicates=false
json_address=MyStreet 5
An example wmbusmeters.d file:
name=MyTapWater
type=multical21:c1
id=12345678
key=001122334455667788AABBCCDDEEFF
json_floor=4

Author

Written by Fredrik Öhrström.