2019-06-06 21:24:15 +00:00
.TH WMBUSMETERS 1
2019-02-26 21:19:16 +00:00
.SH NAME
2019-02-28 15:53:09 +00:00
wmbusmeters \- listen to wireless mbus radio traffic and relay the decoded telegrams to other software
2019-02-26 21:19:16 +00:00
.SH SYNOPSIS
2019-10-24 19:06:33 +00:00
.B wmbusmeters [options] <device>{:suffix} (<meter_name> <meter_type>[:<mode>] <meter_id> meter_key>)*
2019-02-26 21:19:16 +00:00
.B wmbusmetersd <pid_file>
.SH DESCRIPTION
2019-02-28 15:53:09 +00:00
Wmbusmeters acquires wmbus telegrams, decodes them and relays them to
some other software for further processing. It can for example listen
2020-05-06 07:41:29 +00:00
to radio traffic using dedicated wmbus dongles like (im871a amb8465 rfmrx2 cul d1tc)
2019-02-28 15:53:09 +00:00
or a generic software defined radio dongle (rtl_sdr).
2019-02-26 21:19:16 +00:00
2019-02-28 15:53:09 +00:00
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).
2019-02-26 21:19:16 +00:00
.SH OPTIONS
2019-06-06 21:24:15 +00:00
\fB \- -addconversions=\fR <unit>[,<unit>] add conversion to these units for json and shell envs (GJ,F)
2019-02-26 21:19:16 +00:00
2020-09-25 18:01:16 +00:00
\fB \- -alarmexpectedactivity=\fR mon-fri(08-17),sat-sun(09-12) Specify when the timeout is tested, default is mon-sun(00-23)
\fB \- -alarmshell=\fR <cmdline> invokes cmdline when an alarm triggers
\fB \- -alarmtimeout=\fR <time> Expect a telegram to arrive within <time> seconds, eg 60s, 60m, 24h during expected activity.
2019-02-27 18:42:21 +00:00
\fB \- -debug\fR for a lot of information
2019-02-26 21:19:16 +00:00
2019-02-27 18:42:21 +00:00
\fB \- -exitafter=\fR <time> exit program after time, eg 20h, 10m 5s
2019-02-26 21:19:16 +00:00
2019-02-27 18:42:21 +00:00
\fB \- -format=\fR (hr|json|fields) for human readable, json or semicolon separated fields
2019-02-26 21:19:16 +00:00
2019-10-24 19:06:33 +00:00
\fB \- -json_xxx=yyy\fR always add "xxx"="yyy" to the json output and add shell env METER_xxx=yyy
2019-06-06 21:24:15 +00:00
\fB \- -listento=\fR <mode> listen to one of the c1,t1,s1,s1m,n1a-n1f link modes.
\fB \- -listento=\fR <mode>,<mode> listen to more than one link mode at the same time, assuming the dongle supports it.
\fB \- -c1 --t1 --s1 --s1m --n1a ... --n1f\fR listen to c1,t1,s1,s1m,n1a-n1f telegrams.
2020-09-25 18:01:16 +00:00
\fB \- -listenvs=\fR <meter_type> list the env variables available for the given meter type
\fB \- -listfields=\fR <meter_type> list the fields selectable for the given meter type
\fB \- -listmeters\fR list all meter types
\fB \- -listmeters=\fR <search> list all meter types containing the text <search>
2019-02-27 18:42:21 +00:00
\fB \- -logfile=\fR <dir> use this file instead of stdout
2019-02-26 21:19:16 +00:00
2019-02-27 18:42:21 +00:00
\fB \- -logtelegrams\fR log the contents of the telegrams for easy replay
2019-02-26 21:19:16 +00:00
2019-02-27 18:42:21 +00:00
\fB \- -meterfiles=\fR <dir> store meter readings in dir
2019-02-26 21:19:16 +00:00
2019-02-27 18:42:21 +00:00
\fB \- -meterfilesaction=\fR (overwrite|append) overwrite or append to the meter readings file
2019-02-26 21:19:16 +00:00
2019-06-20 12:28:52 +00:00
\fB \- -meterfilesnaming=\fR (name|id|name-id) the meter file is the meter's: name, id or name-id
2020-05-06 07:41:29 +00:00
\fB \- -meterfilestimestamp=\fR (never|day|hour|minute|micros) the meter file is suffixed with a timestamp (localtime) with the given resolution.
2019-02-27 18:42:21 +00:00
\fB \- -oneshot\fR wait for an update from each meter, then quit
2019-02-26 21:19:16 +00:00
2020-09-25 21:56:50 +00:00
\fB \- -resetafter=\fR <time> reset the wmbus dongle regularly, default is 24h
2019-02-27 18:42:21 +00:00
\fB \- -separator=\fR <c> change field separator to c
2019-02-26 21:19:16 +00:00
2020-09-25 18:01:16 +00:00
\fB \- -selectfields=\fR id,timestamp,total_m3 select fields to be printed (--listfields=<meter> to list available fields)
2019-02-26 21:19:16 +00:00
2020-09-25 18:01:16 +00:00
\fB \- -separator=\fR <c> change field separator to c
\fB \- -shell=\fR <cmdline> invokes cmdline with env variables containing the latest reading
2019-02-26 21:19:16 +00:00
2019-02-27 18:42:21 +00:00
\fB \- -useconfig=\fR <dir> load config files from dir/etc
2019-02-26 21:19:16 +00:00
2020-09-25 18:01:16 +00:00
\fB \- -usestderr\fR write notices/debug/verbose and other logging output to stderr (the default)
\fB \- -usestdoutforlogging\fR write debug/verbose and logging output to stdout
2019-02-27 18:42:21 +00:00
\fB \- -verbose\fR for more information
2019-02-26 21:19:16 +00:00
.SH DEVICES
.TP
2020-09-25 18:01:16 +00:00
\fB /dev/ttyUSB0\fR to which an im871a,amb8456 or cul dongle is attached and let wmbusmeters detect the type.
2019-10-24 19:06:33 +00:00
.TP
\fB /dev/ttyACM0:rfmrx2\fR when an rfmrx2 dongle is attached to this tty.
2019-02-26 21:19:16 +00:00
.TP
2020-09-25 18:01:16 +00:00
\fB auto\fR detect any serially connected wmbus dongles and rtl_sdr dongles.
2019-02-26 21:19:16 +00:00
.TP
2019-04-15 19:31:27 +00:00
\fB rtlwmbus\fR use software defined radio rtl_sdr|rtl_wmbus to receive wmbus telegrams.This defaults to 868.95MHz, use for example \fB rtlwmbus:868.9M\fR to tune the rtl_sdr dongle to slightly lower frequency.
2019-02-26 21:19:16 +00:00
.TP
2019-02-27 18:42:21 +00:00
\fB simulation_xxx.txt\fR read telegrams from file to replay telegram feed (use --logtelegrams to acquire feed for replay)
2019-02-26 21:19:16 +00:00
.SH METER QUADRUPLES
.TP
2019-02-27 18:42:21 +00:00
\fB meter_name\fR a mnemonic for your utility meter
2019-02-26 21:19:16 +00:00
.TP
2020-09-25 18:01:16 +00:00
\fB meter_type\fR for example multical21:t1 (suffix means that we expect this meter to transmit t1 telegrams)
2019-02-26 21:19:16 +00:00
.TP
2019-06-06 21:24:15 +00:00
\fB meter_id\fR one or more 8 digit numbers separated with commas, a single '*' wildcard, or a prefix '76543*' with wildcard.
2019-02-26 21:19:16 +00:00
.TP
2019-02-27 18:42:21 +00:00
\fB meter_key\fR a unique key for the meter, if meter telegrams are not encrypted, you must supply an empty key: ""
2019-02-26 21:19:16 +00:00
.SH EXAMPLES
.TP
.TP
2020-09-25 18:01:16 +00:00
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.
2019-02-26 21:19:16 +00:00
% wmbusmeters --c1 auto
2020-09-25 18:01:16 +00:00
Listen to C1 and T1 traffic using a wmbus dongle attached to ttyUSB0.
% wmbusmeters --listento=c1,t1 /dev/ttyUSB0:amd8465
2019-02-26 21:19:16 +00:00
.TP
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
.TP
Execute using config file /home/me/etc/wmbusmeters.conf and meter config files in /home/me/etc/wmbusmeters.d
% wmbusmeters --useconfig=/home/me
.TP
Start a daemon using config file /etc/wmbusmeters.conf and meter config files in /etc/wmbusmeters.d
2019-02-27 18:42:21 +00:00
% wmbusmetersd --useconfig=/ /var/run/wmbusmeters/wmbusmeters.pid
2019-02-26 21:19:16 +00:00
.TP
An example wmbusmeters.conf:
.nf
loglevel=normal
2020-10-04 20:52:05 +00:00
device=/dev/ttyUSB0:im871a:c1
2019-02-26 21:19:16 +00:00
logtelegrams=false
meterfiles=/var/log/wmbusmeters/meter_readings
2019-04-15 19:31:27 +00:00
meterfilesaction=overwrite
2019-02-26 21:19:16 +00:00
logfile=/var/log/wmbusmeters/wmbusmeters.log
2019-04-15 19:31:27 +00:00
shell=/usr/bin/mosquitto_pub -h localhost -t "wmbusmeters/$METER_ID" -m "$METER_JSON"
2020-10-04 20:52:05 +00:00
alarmshell=/usr/bin/mosquitto_pub -h localhost -t wmbusmeters_alarm -m "$ALARM_TYPE $ALARM_MESSAGE"
alarmtimeout=1h
alarmexpectedactivity=mon-sun(00-23)
2019-10-24 19:06:33 +00:00
json_address=MyStreet 5
2019-02-26 21:19:16 +00:00
.fi
.TP
An example wmbusmeters.d file:
.nf
name=MyTapWater
2020-05-06 07:41:29 +00:00
type=multical21:c1
2019-02-26 21:19:16 +00:00
id=12345678
key=001122334455667788AABBCCDDEEFF
2019-10-24 19:06:33 +00:00
json_floor=4
2019-02-26 21:19:16 +00:00
.SH AUTHOR
Written by Fredrik Öhrström.
.SH COPYRIGHT
2020-05-06 07:41:29 +00:00
Copyright \(co 2017-2020 Fredrik Öhrström.
2019-02-26 21:19:16 +00:00
.br
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
.br
There is NO WARRANTY, to the extent permitted by law.