WMBUSMETERS(1)

📦 version 2.0.0, in fedora 43, fedora 44, ubuntu resolute, ubuntu stonking

WMBUSMETERS(1) 💖

okay bestie, welcome to the General Commands Manual page for wmbusmeters and friends — grab a boba, this one is a whole vibe 🧋✨

✨ NAME ✨

wmbusmeters — acquire, query and decode wired and wireless mbus telegrams, then relay those telegrams to other software. that's the whole job description, no cap 🫶

🌸 SYNOPSIS 🌸

wmbusmeters {options} [device]+ { [name] [driver] [id] [key] }*

wmbusmeters {options} [hex] { [name] [driver] [id] [key] }*

wmbusmetersd {options} [pid_file>]

🦋 DESCRIPTION 🦋

so Wmbusmeters acquires wired or wireless mbus telegrams, decodes them, and relays them to some other software for further processing. it is literally the main character of your meter-reading setup 👑

it can, for example, listen to radio traffic using dedicated wmbus dongles (eg im871a,im170a,amb8465, amb8335,cul,rc1180) or a software defined radio dongle (rtl_sdr) with an RTL2832U (decoded using rtl_wmbus, rtl_433). yes queen, software defined radio 💅

once the acquired 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). pick your fighter ✨

💅 OPTIONS 💅

  • --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
  • --analyze — analyze a telegram to find the best driver 🔍
  • --analyze=<key> — analyze a telegram to find the best driver and use the provided decryption key
  • --analyze=<driver> — analyze a telegram but use only this driver
  • --analyze=<driver>:<key> — analyze a telegram and use only this driver with this key. add :verbose to any analyze to get more verbose analyze output 👀
  • --calculate_xxx_yyy=... — add xxx_yyy 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 — units are automatically translated if possible 🧮
  • --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
  • --help — list all options 🫶
  • --identitymode=(id,id-mfct,full,none) — group meter state based on the identity mode. default is id.
  • --ignoreduplicates=<bool> — ignore duplicate telegrams, remember the last 10 telegrams. default is true.
  • --field_xxx=yyy — always add "xxx"="yyy" to the json output and add shell env METER_xxx=yyy. the field xxx can also be selected or added using selectfields=. equivalent older command is --json_xxx=yyy.
  • --license — print GPLv3+ license 📜
  • --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 🔥
  • --listenvs=<meter_type> — list the env variables available for the given meter type
  • --listfields=<meter_driver> — list the fields selectable for the given meter type
  • --printdriver=<meter_driver> — print xmq driver source code
  • --listmeters — list all meter types
  • --listmeters=<search> — list all meter types containing the text <search>
  • --listunits= — list all unit suffixes that can be used for typing values
  • --logfile=<dir> — use this file for logging or --logfile=syslog
  • --logtelegrams — log the contents of the telegrams for easy replay
  • --logtimestamps=<when> — add timestamps to log entries: never/always/important
  • --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
  • --normal — for normal logging
  • --oneshot — wait for an update from each meter, then quit ✌️
  • --overridedevice=<device> — override device in config files. can only be used in combination with --useconfig= option
  • --pollinterval=<interval> — poll mbus meters every <interval>, default is 10m.
  • --ppjson — pretty print the json output ✨
  • --resetafter=<time> — reset the wmbus dongle regularly, default is 23h
  • --selectfields=id,timestamp,total_m3 — select only these 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 🤫
  • --trace — for tons of information
  • --useconfig=<dir> — load config <dir>/wmbusmeters.conf and meters from <dir>/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

🎀 DEVICES 🎀

  • auto:c1 — detect any serially connected wmbus dongles and rtl_sdr dongles and configure them for c1 mode.
    • use auto to detect your dongle when testing, but then in production, state explicitly the dongle you are using. this will significantly reduce the amount of probing done on the serial ports. (ngl, do this, bestie 🫶)
  • 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. two dongles, two vibes 💅
  • /dev/ttyUSB0:9600 — read serial data from tty at 9600 bps, expects raw wmbus frames with the DLL crcs removed.
  • MAIN=/dev/ttyUSB0:mbus:2400 — expect an serial to mbus master converter on ttyUSB0.
  • stdin:rawtty — read binary telegrams (without dll crc:s) from stdin.
  • filename:rawtty — read binary telegrams from the file.
  • stdin:hex — decode any hex found on stdin, non-hex characters are ignored.
  • 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) 🎬
  • 2e441122334455667788 — decode the given hex string, the hex string must have only hex digits or underscores.

🌈 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) the driver auto can be used, but is not recommended for production.
  • meter_id — one or more addresses separated with commas, a single '*' wildcard, or a prefix '76543*' with wildcard. you can as a suffix fully or partially specify manufacturer, version and type: 12345678.M=KAM.V=1b.T=16 you can use p0 to p250 to specify an mbus primary address. you can filter out telegrams: 76543*,!76543210 🕵️
  • 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

you can query an mbus meter:

% wmbusmeters MAIN=/dev/ttyUSB0:mbus:2400 MyTempMeter piigth:MAIN:mbus 12001932 NOKEY

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
# Remember to remove meterfiles to spare precious flash memory when only
# relaying data using for example mqtt.
meterfiles=/var/lib/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
field_address=MyStreet 5

an example wmbusmeters.d file:

name=MyTapWater
driver=multical21:c1
id=12345678
key=001122334455667788AABBCCDDEEFF
field_floor=4

you can use the driver auto, but it is not recommended for production. the auto driver might change over time to better versions of the driver with new names, whereas a fixed driver name should generate backwards compatible json. 👑

fr fr bestie, pin your driver name in prod. the auto driver is a ✨surprise✨ and surprises in production are not the cute kind 💀

💜 AUTHOR 💜

written by Fredrik Öhrström. 👑

copyright © 2017-2022 Fredrik Öhrström.

license GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.

this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law.

and that's the whole page, bestie!! 🦋 this was the WMBUSMETERS(1) manual page from the General Commands Manual — go forth and decode some telegrams, you absolute icon 💖✨🎀

📦 where this page comes from