wmbusmeters/wmbusmeters.1

.TH WMBUSMETERS 1
.SH NAME
wmbusmeters \- listen to wireless mbus radio traffic and relay the decoded telegrams to other software

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

.B wmbusmetersd <pid_file>

.SH 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).

.SH OPTIONS
\fB\--addconversions=\fR<unit>[,<unit>] add conversion to these units for json and shell envs (GJ,F)

\fB\--alarmexpectedactivity=\fRmon-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.

\fB\--debug\fR for a lot of information

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

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

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

\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.

\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>

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

\fB\--logtelegrams\fR log the contents of the telegrams for easy replay

\fB\--meterfiles=\fR<dir> store meter readings in dir

\fB\--meterfilesaction=\fR(overwrite|append) overwrite or append to the meter readings file

\fB\--meterfilesnaming=\fR(name|id|name-id) the meter file is the meter's: name, id or name-id

\fB\--meterfilestimestamp=\fR(never|day|hour|minute|micros) the meter file is suffixed with a timestamp (localtime) with the given resolution.

\fB\--oneshot\fR wait for an update from each meter, then quit

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

\fB\--separator=\fR<c> change field separator to c

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

\fB\--separator=\fR<c> change field separator to c

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

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

\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

\fB\--verbose\fR for more information

.SH DEVICES
.TP
\fB/dev/ttyUSB0\fR to which an im871a,amb8456 or cul dongle is attached and let wmbusmeters detect the type.

.TP
\fB/dev/ttyACM0:rfmrx2\fR when an rfmrx2 dongle is attached to this tty.

.TP
\fBauto\fR detect any serially connected wmbus dongles and rtl_sdr dongles.

.TP
\fBrtlwmbus\fR use software defined radio rtl_sdr|rtl_wmbus to receive wmbus telegrams.This defaults to 868.95MHz, use for example \fBrtlwmbus:868.9M\fR to tune the rtl_sdr dongle to slightly lower frequency.

.TP
\fBsimulation_xxx.txt\fR read telegrams from file to replay telegram feed (use --logtelegrams to acquire feed for replay)

.SH METER QUADRUPLES
.TP
\fBmeter_name\fR a mnemonic for your utility meter
.TP
\fBmeter_type\fR for example multical21:t1 (suffix means that we expect this meter to transmit t1 telegrams)
.TP
\fBmeter_id\fR one or more 8 digit numbers separated with commas, a single '*' wildcard, or a prefix '76543*' with wildcard.
.TP
\fBmeter_key\fR a unique key for the meter, if meter telegrams are not encrypted, you must supply an empty key: ""

.SH EXAMPLES
.TP

.TP
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 --c1 auto

Listen to C1 and T1 traffic using a wmbus dongle attached to ttyUSB0.

% wmbusmeters --listento=c1,t1 /dev/ttyUSB0:amd8465

.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

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

.TP
An example wmbusmeters.conf:

.nf
loglevel=normal
device=/dev/ttyUSB0:im871a
logtelegrams=false
meterfiles=/var/log/wmbusmeters/meter_readings
meterfilesaction=overwrite
logfile=/var/log/wmbusmeters/wmbusmeters.log
shell=/usr/bin/mosquitto_pub -h localhost -t "wmbusmeters/$METER_ID" -m "$METER_JSON"
json_address=MyStreet 5
.fi

.TP
An example wmbusmeters.d file:

.nf
name=MyTapWater
type=multical21:c1
id=12345678
key=001122334455667788AABBCCDDEEFF
json_floor=4

.SH AUTHOR
Written by Fredrik Öhrström.

.SH COPYRIGHT
Copyright \(co 2017-2020 Fredrik Öhrström.
.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.