Wireless M-Bus receiver and decoder firmware for the M5Stack Cardputer-ADV. It listens for water, heat, electricity, gas, heat-cost-allocator, smoke and room sensor telegrams (EN 13757-4 C1, T1 and S1), decrypts them, decodes them on the device with a full port of the wmbusmeters driver engine, and shows the results on the Cardputer, in a web UI, over MQTT (with Home Assistant discovery), on the USB serial port and in SD card logs.
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
-
All 122 wmbusmeters XMQ drivers, decoded exactly like upstream. The engine is a faithful port: DIF/VIF records, storage/tariff/subunit matching, combinables, lookups, unit-aware formulas, ixml grammars for manufacturer payloads, compact frames and compact profiles (history values). The upstream driver test suite runs on the host: 385 of 385 test telegrams decode to the same fields and values.
-
Every common security mode. AES-128 CBC (mode 5), AES CBC with CMAC key derivation (mode 7), AES-CCM (mode 10, OMS profile D), ELL AES-CTR, DES (modes 2/3), Diehl IZAR/PRIOS LFSR, Qundis walk-by blocks and driver default keys. Meters without a driver still get a generic OMS decode.
-
Much better reception.
- SX1262 (Cap LoRa-1262): the antenna switch is actually enabled (the PI4IOE expander was misconfigured before, costing ~30 dB). Boosted RX gain, a 234 kHz filter and an 8-bit preamble detector are used. A sync word interrupt starts a timed read, so reception stops right after each frame and false syncs are dropped in well under a millisecond.
- CC1101 (Hydra RF): infinite packet mode with FIFO streaming. Earlier builds cut every frame at 61 bytes.
- T1 (3-out-of-6), C1 frame A and B, and S1 (Manchester) are supported. You can also alternate between the 868.95 MHz and 868.30 MHz bands.
- A dedicated high-priority radio task and a capture queue, so UI, Wi-Fi and SD card work never make the receiver miss a telegram.
-
A new user interface: meter list with values, signal and age, a live feed, a Hunt mode (signal gauge, history graph and proximity beeps) to find a meter, statistics, on-device settings, and meter keys typed on the keyboard. A QR code connects your phone to the web UI. Four themes are included.
-
Web UI on the device's own access point or your network. It shows the live feed, sortable and filterable meters, full decodes, a telegram analyzer, key management, settings, log downloads and firmware updates over the air. It needs no internet access.
-
MQTT with credentials, 4 KB messages, wmbusmeters-compatible JSON, last will, and Home Assistant discovery with proper units and device and state classes.
-
USB serial in three output modes:
- readable log lines;
- JSON;
rtl_wmbuslines that a PC wmbusmeters can use directly.
There's also a command line for keys, bands and analysis.
-
SD card logs: replayable raw telegrams, decoded JSON lines and a wardriving CSV with GNSS positions. Meter keys are imported from
/keys.txtat boot. -
GNSS (Cap LoRa-1262) provides positions per meter (GeoJSON export in the web UI) and sets the clock without network.
- M5Stack Cardputer-ADV
- one radio cap, auto-detected at boot:
- Cap LoRa-1262 (SX1262 + GNSS), recommended
- Hydra RF (CC1101). Use an 868 MHz tuned board; a 433 MHz board attenuates 868 MHz heavily.
- optional: microSD card (FAT32)
The SX1262 receives at most 255 raw bytes per frame, a limit of its packet engine. That covers T1 telegrams up to about 150 bytes and C1 telegrams up to about 220 bytes, which is nearly every meter; longer ones show as truncated. The CC1101 streams its FIFO and receives frames of any length.
Download wmbuster-adv-full.bin from the
releases page and flash it at offset
0x0, for example with the
esptool-js web flasher or:
esptool.py --chip esp32s3 write_flash 0x0 wmbuster-adv-full.binLater updates can be uploaded in the web UI (Settings → Firmware update, use
firmware.bin).
-
Power on. The splash screen shows the detected radio and band.
-
Meters appear on the METERS tab as their telegrams arrive. Encrypted meters show a lock.
-
Open SETUP → Connect phone (QR). Scan the first code to join the
wM-Buster-XXXXaccess point (passwordwmbuster), then openhttp://192.168.4.1. -
Add keys for your meters: on the device (open the meter, press K and type the 32 hex digits), in the web UI (click a meter), over serial (
key 12345678 00112233445566778899AABBCCDDEEFF), or with/keys.txton the SD card:# id,key,name,driver (key NOKEY for none, driver "auto" to detect) 12345678,00112233445566778899AABBCCDDEEFF,Kitchen water,autowmbusmeters meter files (
name=,id=,key=,driver=lines) work too. Keys are stored in flash (NVS).
| Key | Action |
|---|---|
Tab, 1–5 |
switch view: Meters, Live, Hunt, Stats, Setup |
; . (↑ ↓) |
move / scroll (hold to repeat) |
, / (← →) |
previous / next view, change a setting |
Enter |
open meter / change setting |
Del |
back / erase |
` |
cancel text entry |
T |
hunt the selected meter (proximity beeps, B toggles) |
F or * |
star / unstar (starred meters stay on top and trigger ntfy alerts) |
O |
meter sort order: recent, signal, id, count |
K, N, R |
in a meter: enter key, name, raw telegram |
Home Assistant / MQTT. Enable MQTT in the web UI and set the broker, user and
password. Telegrams go to wmbusmeters/<name or id> in the same JSON format that
wmbusmeters produces. Meters you configured (name, key or star) get Home Assistant
discovery entities automatically. wmbusmeters/wmbuster/status carries
online/offline, and wmbusmeters/wmbuster/state has statistics.
A PC running wmbusmeters. Set the serial output to rtl_wmbus and use the
Cardputer as its receiver:
stty -F /dev/ttyACM0 115200 raw
wmbusmeters --format=json stdin:rtlwmbus MyMeter auto 12345678 NOKEY < /dev/ttyACM0SD logs replay the same way:
wmbusmeters stdin:rtlwmbus < telegrams.rtl.
ntfy. Set an ntfy URL (for example https://ntfy.sh/my-topic) to get pushed
notifications when a starred meter is first heard or its status changes (leak,
tamper, ...).
Serial commands. Type help. You can paste any hex telegram to analyze it,
or use analyze <hex> <key> <driver>, meters, show <id>,
band ct|s|hop, out log|json|rtlwmbus, wifi <ssid> <pass>,
mqtt <host> [port] [user] [pass], stats.
pio run -e m5stack-cardputer-adv # firmware + wmbuster-adv-full.bin
pio run -e m5stack-cardputer-adv -t upload # flash over USBweb/index.html is gzipped into the firmware automatically at build time.
make -C test/host # 204 unit checks + all upstream wmbusmeters driver tests
make -C test/ui_preview # renders every screen of the device UI to PNGThe analyzer is also available on the PC: make -C test/host analyze && test/host/build/analyze <hex> [driver|auto] [key].
Add a section for the new version to CHANGELOG.md and set WMB_VERSION in
src/version.h. Then either push a matching tag:
git tag v2.1.0 && git push origin v2.1.0or open Actions → Build → Run workflow on GitHub and enter the tag (v2.1.0);
the tag is then created on the commit that was built.
GitHub Actions runs the tests, builds the firmware and publishes the release with
wmbuster-adv-full.bin, firmware.bin, checksums and the changelog section. Tags
with a suffix (v2.1.0-beta.1) become pre-releases. Every push and pull request is
built too, and the images are attached to the run.
The drivers, manufacturer names and test vectors are generated from a wmbusmeters checkout:
python3 tools/generate_drivers.py /path/to/wmbusmeterslib/wmbus/ portable decoder library: frames, telegram layers + crypto,
DIF/VIF, driver engine, formulas, ixml, generated drivers
lib/radio/ SX1262 / CC1101 receiver task
src/app/ pipeline, meter table, settings/keys, console, SD logging
src/net/ WiFi, web UI + JSON API, MQTT, ntfy
src/ui/ on-device UI (hardware independent view + Cardputer glue)
src/hw/ board (RF switch, LED, battery) and GNSS
web/ web UI source
test/ host tests, UI preview, upstream test vectors
tools/ driver generator, web embedding, merged image
wmbusmeters by Fredrik Öhrström and contributors. The decoder engine, drivers and test telegrams come from there. The CC1101 and SX1262 settings follow the esphome wmbus components by SzczepanLeon and contributors.
GPL-3.0.





