wmbusmeters

wmbusmeters

The program acquires utility meter readings from wired m-bus or wireless wm-bus meters. The readings can then be published using MQTT, curled to a REST api, inserted into a database or stored in a log file.

What does it do?

Wmbusmeters converts incoming telegrams from (w)mbus/OMS compatible meters like: 1844AE4C4455223368077A55000000_041389E20100023B0000

into human readable: MyTapWater 33225544 123.529 m³ 0 m³/h 2024-03-03 19:36:22

or into csv: MyTapWater;33225544;123.529;0;2024-03-03 19:36:45

or into json:

{
    "_":"telegram",
    "media":"water",
    "meter":"iperl",
    "name":"MyTapWater",
    "id":"33225544",
    "max_flow_m3h":0,
    "total_m3":123.529,
    "timestamp":"2024-03-03T18:37:00Z"
}

Wmbusmeters can collect telegrams from radio using hardware dongles or rtl-sdr software radio dongles, or from m-bus meters using serial ports, or from files/pipes.

Wmbusmeters uses drivers to translate the measurement values from a meter to understandable key-value pairs.

You can automatically decode a 32 bit signed binary word representing a volume in m3 stored in storage slot 1 but what does this measurement mean? Is it last months final measurement that will be used for water billing? Is it the amount of gas delivered last year? The drivers adds this knowledge, here is an example:

field {
    name = target
    info = 'Water consumption at the end of last month.'
    quantity = Volume
    match {
        measurement_type = Instantaneous
        vif_range = Volume
        storage_nr = 20
    }
}

All native drivers are going to be rewritten in this form. If you want to create a new driver, write it directly in xmq form. I am not accepting new drivers as C++ code.

FAQ/WIKI/MANUAL pages

The program runs on GNU/Linux, MacOSX, FreeBSD, and Raspberry Pi.

Distributions

wmbusmeters package is available on Fedora (version 31 or newer) and can be simply installed by using:

dnf install wmbusmeters

wmbusmeters for Debian is currently available through Experimental repositories. Availability for other Linux distributions can be checked on release-monitoring project page.

Docker

Experimental docker containers are available here: https://hub.docker.com/r/wmbusmeters/wmbusmeters

Snap

Experimental snaps are available here: https://snapcraft.io/wmbusmeters Read the wiki for more info on how to use the snap: https://wmbusmeters.github.io/wmbusmeters-wiki/SNAP.html

Build from source and run as a daemon

Building and installing from source is easy and recommended since the development progresses quickly. First remove the wmbus dongle (im871a,iu891a,amb8465(metis),amb3665,cul,rc1180) or the generic rtlsdr dongle (RTL2832U) from your computer. Then do:

./configure; make; sudo make install will install wmbusmeters as a daemon.

Usage

Check the contents of your /etc/wmbusmeters.conf file, assuming it has device=auto:t1 and you are using a im871a,iu891a,amb8465(metis),amb3665,rc1180,cul or rtlsdr device, then you can now start the daemon with sudo systemctl start wmbusmeters or you can try it from the command line wmbusmeters auto:t1

Wmbusmeters will scan for wmbus devices every few seconds and detect whenever a device is plugged in or removed. However since wmbusmeters now supports several dongle types, the scan can take some time!

Use auto for testing and to find your dongle. For production it is very much recommended that you change auto:t1 to the device name with the full device path (eg /dev/ttyAMA0:iu891a:c1,t1). This will skip the slow probing for all possible wmbus dongles when wmbusmeters startup.

If the serial device (ttyUSB0) might change you can also use device=iu891a:c1,t1 which will probe all serial devices but only scans for im891a which also speeds it up.

Note that the rtl-sdr devices are not found under the tty devices (e.g. /dev/tty...). Instead the rtl-sdr devices are accessed through character device special files named /dev/swradio0 to /dev/swradio255^kernel_docs_sdr. Wmbusmeters uses librtsldr to probe these devices.

If you have to scan serial devices, then remember that some Raspberry PIs are upset when random data is sent to /dev/ttyAMA0 when it is configured in bluetooth mode. To solve this, add donotprobe=/dev/ttyAMA0

To have the wmbusmeters daemon start automatically when the computer boots do: sudo systemctl enable wmbusmeters

You can trigger a reload of the config files with sudo killall -HUP wmbusmetersd

(Note! make install only works for GNU/Linux. For MacOSX try to start wmbusmetersd /tmp/thepidfile from a script instead.)

You can also start the daemon with another set of config files: wmbusmetersd --useconfig=/home/me/.config/wmbusmeters /tmp/thepidfile

When using useconfig, the files/dir should be: /home/me/.config/wmbusmeters/wmbusmeters.conf and the meters dir: /home/me/.config/wmbusmeters/wmbusmeters.d

Check the config file /etc/wmbusmeters.conf and edit the device. For example: /dev/ttyUSB1:amb8465:c1,t1 or iu891a:c1,t1 or iu891a[457200101056]:t1.

Adding a device like auto or iu891a will trigger an automatic probe of all serial ttys to auto find or to find on which tty the iu891a resides.

If you specify a full device path like /dev/ttyUSB0:iu891a:c1 or rtlwmbus or rtl433 then it will not probe the serial devices. If you must be really sure that it will not probe something you can add donotprobe=/dev/ttyUSB0 or donotprobe=all.

You can specify combinations like: device=rc1180:t1 device=auto:c1 to set the rc1180 dongle to t1 but any other auto-detected dongle to c1.

Some dongles have identifiers (im871a,iu891a,amb8465(metis),amb3665 and rtlsdrs) (for example: rtlsdr can be set with rtl_eeprom -s myname) You might have two rtlsdr dongles, one attached to an antenna tuned to 433MHz and the other attached to an antenna tuned for 868.95MHz, then a more complicated setup could look like this:

device=rtlwmbus[555555]:433M
device=rtlwmbus[112233]
device=/dev/ttyUSB0:iu891a[00102759]:c1,t1
device=/dev/ttyUSB1:rc1180:t1

Bus aliases and polling

To poll an C2/T2/S2 wireless meter or an wired m-bus meter you need to give the (w)mbus device a bus-alias, for example here we pick the bus alias MAIN for the mbus using 2400 bps for all meters on this bus.

MAIN=/dev/ttyUSB0:mbus:2400

and here we pick the bus alias RADIOMAIN for an iu891a dongle:

RADIOMAIN=/dev/ttyUSB1:iu891a:c2

The bus alias is then used in the meter driver specification to specify which bus the mbus poll request should be sent to.

wmbusmeters --pollinterval=60s MAIN=/dev/ttyUSB0:mbus:2400 MyTempMeter piigth:MAIN:mbus 12001932 NOKEY

If you want to poll an mbus meter using the primary address, use p0 to p250 (deciman numbers) instead of the full 8 digit secondary address.

wmbusmeters --pollinterval=60s MAIN=/dev/ttyUSB0:mbus:2400 MyTempMeter piigth:MAIN:mbus p0 NOKEY

Example wmbusmeter.conf file

…

Then add a meter file in /etc/wmbusmeters.d/MyTapWater

name=MyTapWater
id=12345678
key=00112233445566778899AABBCCDDEEFF
driver=multical21

And an mbus meter file in /etc/wmbusmeters.d/MyTempHygro

name=MyTempHygro
id=11223344
driver=piigth:MAIN:mbus
pollinterval=60s

Important information about meter drivers and their names.

You can use driver=auto to have wmbusmeters automatically detect and use the best driver for your meter, but you should >not invokes cmdline when an alarm triggers --alarmtimeout= Expect a telegram to arrive within seconds, eg 60s, 60m, 24h during expected activity. --analyze Analyze a telegram to find the best driver. --analyze= Analyze a telegram to find the best driver use the provided decryption key. --analyze= Analyze a telegram and use only this driver. --analyze=: Analyze a telegram and use only this driver with this key. --calculate_field_unit='...' Add field_unit to the json and calculate it using the formula. E.g. --calculate_sumtemp_c='external_temperature_c+flow_temperature_c' --calculate_flow_f=flow_temperature_c --debug for a lot of information --donotprobe= do not auto-probe this tty. Use multiple times for several ttys or specify "all" for all ttys. --driver= load a driver --driversdir= load all drivers in dir --exitafter= exit program after time, eg 20h, 10m 5s --format= for human readable, json or semicolon separated fields --help list all options --identitymode=(id|id-mfct|full|none) group meter state based on the identity mode. Default is id. --ignoreduplicates= ignore duplicate telegrams, remember the last 10 telegrams --field_xxx=yyy always add "xxx"="yyy" to the json output and add shell env METER_xxx=yyy (--json_xxx=yyy also works) --license print GPLv3+ license --listento= listen to one of the c1,t1,s1,s1m,n1a-n1f link modes, or cct for iU891A Custom C/T mode --listento=, listen to more than one link mode at the same time, assuming the dongle supports it --listenvs= list the env variables available for the given meter driver --listfields= list the fields selectable for the given meter driver --printdriver= print xmq driver source code --listdrivers list all meter drivers --listdrivers= list all meter drivers containing the text --listunits list all unit suffixes that can be used for typing values --logfile= use this file for logging or --logfile=syslog --logtelegrams log the contents of the telegrams for easy replay --logtimestamps= add log timestamps: always never important --meterfiles= 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. --metershell= invokes cmdline with env variables the first time a meter is seen since startup --nodeviceexit if no wmbus devices are found, then exit immediately --normal for normal logging --oneshot wait for an update from each meter, then quit --overridedevice= override device in config files. Use only in combination with --useconfig= option --ppjson pretty print the json --pollinterval= time between polling of meters, must be set to get polling. --resetafter= reset the wmbus dongle regularly, default is 23h --selectfields=id,timestamp,total_m3 select only these fields to be printed (--listfields= to list available fields) --separator= change field separator to c --shell= invokes cmdline with env variables containing the latest reading --silent do not print informational messages nor warnings --trace for tons of information --useconfig= load config /wmbusmeters.conf and meters from /wmbusmeters.d --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 --version print version

…

ERRFILE=$(mktemp --suffix=_wmbusmeters_rtlsd