Multical 21 Reader Firmware

Modern ESP8266/ESP32 firmware for Kamstrup Multical 21 water meters with an AMS Reader inspired web interface, WiFi onboarding, local water usage graphs, Home Assistant MQTT, Fibaro/local JSON API, browser OTA updates, and Telnet debugging.

This project is a product-focused continuation of the ESP Multical 21 reader idea. It keeps the useful wireless M-Bus / CC1101 / AES-CTR decoding foundation and adds the practical firmware features needed to run a Multical 21 reader as a small standalone appliance on a home network.

Keywords: Kamstrup Multical 21, Multical21, wireless M-Bus, wM-Bus, CC1101, ESP8266, D1 mini, D1 mini Lite, ESP32, water meter, Home Assistant, MQTT, Fibaro Home Center, OTA firmware, captive portal, water usage graphs.

Highlights

• AMS-style dashboard with status top bar, live RX/radio/NTP/MQTT indicators, water total, hourly, daily, weekly usage, meter details, and a 60 minute live usage graph.
• WiFi onboarding with setup AP Multical21-Setup, captive portal redirects, WiFi scan, and WiFi connection testing from the browser.
• Browser setup UI for device name, WiFi, NTP, MQTT, Home Assistant discovery, Telnet debug, meter serial, and AES key.
• Runtime meter setup: no local credentials.h is required for meter serial or encryption key.
• Persistent history in LittleFS so hourly, daily, weekly, monthly, and yearly graph data can survive reboot.
• NTP-backed calendar buckets so graph days, weeks, months, and years follow real dates.
• MQTT JSON publishing and optional Home Assistant MQTT discovery.
• Local JSON endpoints for Fibaro, scripts, dashboards, and other home automation systems.
• Browser OTA firmware upload from /firmware.
• Optional Telnet debug on port 23 with mirrored serial diagnostics.
• GitHub Actions release builds for ESP8266 D1 mini Lite and LOLIN S2 Mini.

Supported Hardware

• Kamstrup Multical 21 water meter with wireless M-Bus.
• CC1101 868 MHz radio module connected over SPI.
• ESP8266 D1 mini Lite.
• LOLIN S2 Mini / ESP32-S2.

The default PlatformIO environment is esp8266_lite, because that is the known working D1 mini Lite target with 1 MB flash. Use the matching firmware binary for your board.

Screenshots

First Boot

1. Flash the matching firmware binary for your board.
2. Join the WiFi network Multical21-Setup.
3. Open the captive portal prompt, or browse to http://192.168.4.1/.
4. Scan/test WiFi.
5. Enter meter serial as 8 hex characters. The UI validates plain hex only.
6. Enter AES key as 32 hex characters. The UI validates plain hex only.
7. Configure MQTT/Home Assistant if needed.
8. Save and reboot.

Meter serial example:

12345678

AES key example format:

00112233445566778899AABBCCDDEEFF

Do not include 0x, commas, or spaces in the web UI fields.

Web UI

• / - dashboard with current water state and recent usage.
• /setup - WiFi, NTP, MQTT, Home Assistant, Telnet, meter serial, AES key.
• /graphs - hourly, daily, weekly, monthly, and yearly graphs.
• /firmware - browser OTA firmware upload.
• /reset-config - POST endpoint used by the setup UI to clear configuration.
• /factory-reset - POST endpoint used by the setup UI to clear configuration and local history.
• /data.json - local JSON state API.
• /dayplot.json - 24 hour plot data.
• /monthplot.json - 31 day plot data.
• /version.json - firmware version, build date, board, and git SHA.
• /diagnostics.json - downloadable diagnostic bundle with firmware, network, NTP, CC1101/radio, and configuration status.

If mDNS is available on your network, the device can also be reached by the configured device name, for example:

http://multical21.local

Home Assistant And MQTT

MQTT can be enabled from the setup page. The firmware publishes decoded water meter state as JSON and can publish Home Assistant discovery entities for:

• total water counter
• current hour usage
• daily usage
• weekly/monthly/yearly history windows
• water temperature
• room/ambient temperature
• last frame age
• Multical alarm flags: dry, reverse flow, leak, burst

Secure MQTT/TLS can be enabled, but certificate management is intentionally not part of this firmware. TLS mode is intended for trusted local network broker setups.

Fibaro And Local API

Fibaro Home Center or any other controller can poll:

• http://<device-ip>/data.json for current state and sync-safe total counter.
• http://<device-ip>/dayplot.json for the 24 hour graph.
• http://<device-ip>/monthplot.json for the 31 day graph.

Use total_m3 as the source of truth. If Fibaro misses polls, it can recover by calculating the difference between the latest total_m3 and the last value it stored. Use last_frame_age_s to detect stale radio data.

The repository also contains a Fibaro Quick App for estimating BWT AQA Life salt usage from the Multical water consumption API:

• fibaro/BWT_Salt_Monitor.lua
• fibaro/README.md

Firmware Update

1. Build the matching PlatformIO target, or download a release binary.
2. Open http://<device-ip>/firmware.
3. Upload the matching .bin file.
4. The device validates the image and restarts when the upload succeeds.

Dirty local history is flushed before the firmware update restart, so accepted meter deltas are not intentionally left only in RAM during OTA.

For ESP8266 D1 mini Lite, use:

multical21-reader-<version>-esp8266-lite.bin

For LOLIN S2 Mini / ESP32-S2, use:

multical21-reader-<version>-lolin-s2-mini.bin

GitHub Release Binaries

Every pushed v* tag starts the release workflow. GitHub Actions builds and attaches:

• multical21-reader-<version>-esp8266-lite.bin
• multical21-reader-<version>-lolin-s2-mini.bin
• SHA256SUMS.txt

Build Locally

Install PlatformIO and build the default ESP8266 Lite target:

pio run

Build all release environments:

pio run -e esp8266_lite -e lolin_s2_mini

The repository still contains generic ESP8266/ESP32 environments for local experiments, but release binaries are produced for the two known working board profiles above.

Force Setup / Captive Portal

• Open http://<device-ip>/setup and press Reset setup/config.
• The device clears runtime configuration and reboots into Multical21-Setup.
• Local water history is kept.
• Or erase flash before upload from PlatformIO if you want a fully clean first boot.

Reset Options

• Reset setup/config clears WiFi, MQTT, NTP, meter serial, AES key, and other EEPROM configuration. Persisted water history is kept.
• Factory reset clears setup/config and deletes persisted LittleFS water history. Use this only when you intentionally want a clean device.

Telnet Debug

1. Enable Telnet debug in the setup UI and reboot.
2. Connect with telnet <device-ip> 23 or nc <device-ip> 23.
3. Serial debug output is mirrored to the Telnet session.

Telnet debug is useful for checking CC1101 packet interrupts, radio RSSI, wireless M-Bus frame validation, meter serial matching, and AES decrypt status.

Diagnostics

Open /hardware and use Download diagnostics, or browse directly to:

http://<device-ip>/diagnostics.json

The file includes firmware version, board, IP/hostname, NTP attempts/sync age, CC1101 detection, radio profile, last accepted/rejected frame, MQTT/HA status, and whether meter serial/AES are configured. It does not expose WiFi password, MQTT password, AES key, or meter serial.

API Examples

Read live state:

curl http://<device-ip>/data.json

Example fields:

{
  "valid": true,
  "uptime_s": 3600,
  "total_m3": 1376.002,
  "current_hour_m3": 0.004,
  "today_m3": 0.120,
  "current_week_m3": 0.650,
  "last_frame_age_s": 12,
  "time_synced": true,
  "alarms": {
    "burst": false,
    "leak": false,
    "dry": false,
    "reverse": false
  }
}

Read non-secret configuration status:

curl http://<device-ip>/configuration.json

Download diagnostics:

curl -o multical21-diagnostics.json http://<device-ip>/diagnostics.json

Configuration is changed through the browser setup form at /setup. There is no public JSON POST config API, which avoids exposing WiFi passwords, MQTT passwords, AES keys, or meter serials through a casual automation endpoint.

Project Lineage

This firmware builds on the original open source Multical 21 reader work and related wireless M-Bus decoding knowledge:

• Original project inspiration: chester4444/esp-multical21
• Additional ESP Multical 21 work: derbmann/esp-multical21
• Wireless M-Bus tooling: wmbusmeters/wmbusmeters
• Earlier MQTT/serial reader work by weetmuts

This repository is maintained as the product firmware version with browser setup, persistent history, OTA update flow, local API, and home automation integrations.

Recommended GitHub Topics

Add these topics to the GitHub repository so the project is easier to find:

kamstrup
multical21
water-meter
wireless-mbus
wmbus
cc1101
esp8266
esp32
home-assistant
mqtt
fibaro
ota

License

This project follows the license inherited from the original ESP Multical 21 reader code. See LICENSE.