M-Bus Proxy Suite

Laboratory firmware for staged M-Bus diagnostics and cache-based proxy experiments. Do not connect it to billing-relevant equipment until every stage has been validated in an isolated setup.

M-Bus Proxy Suite is PlatformIO/Arduino firmware for ESP32 boards. One universal firmware is built per board family; the web interface selects Master, Slave, or Sniffer mode after flashing.

The preview is a manually redacted internal-network capture. No credentials or meter serial numbers are shown.

What it does

• passively observe M-Bus traffic in Sniffer mode with UART transmission disabled;
• poll isolated physical M-Bus meters in Master mode;
• emulate a cached M-Bus slave response in Slave mode;
• transfer raw cache entries between two devices over TCP;
• retain decoded meter values through MQTT and Home Assistant discovery;
• expose configuration, cache, frames, exports, and firmware updates through a web UI.

Firmware targets

Board family	Universal target	Network support
WT32-ETH01	wt32-universal	Wi-Fi and LAN8720 Ethernet
ESP32 DevKit	esp32dev-universal	Wi-Fi
ESP32-C3 DevKitM-1	esp32c3-universal	Wi-Fi
ESP32-S3 DevKitC-1	esp32s3-universal	Wi-Fi
Waveshare ESP32-S3-POE-ETH	esp32s3-poe-eth-universal	Wi-Fi and W5500 Ethernet

Board-specific targets are necessary because pin mappings, flash layout, USB configuration, and Ethernet hardware differ. Master, Slave, and Sniffer are selected in the UI and do not require separate firmware images.

Quick start

1. Build the target that matches the physical board:

   pio run -e wt32-universal

2. Flash over USB:

   pio run -e wt32-universal -t upload

3. On the first boot, record the randomly generated web/OTA password from the serial monitor. It is saved only on that device.

4. Connect to the fallback access point using the SSID and password shown in the serial monitor, then open the shown address in a browser.

5. Select Master, Slave, or Sniffer. The device restarts to apply the mode.

6. Follow the staged test procedure before wiring an official master or real meters.

OTA updates

Every normal firmware target has a matching -ota target. Supply the device address and the locally generated password through an environment variable:

MBUS_OTA_PASSWORD='<DEVICE_PASSWORD>' \
pio run -e wt32-universal-ota -t upload --upload-port <DEVICE_IP_OR_HOSTNAME>

No password, hostname, IP address, or device identifier is stored in this repository.

Modes and safety

Mode	Purpose	Critical constraint
Sniffer	Passive capture of master/slave TTL traffic	TX remains unassigned; use receive-only wiring.
Master	Read real M-Bus slaves on an isolated segment	Never connect a second active master to the same segment.
Slave	Answer from validated cache entries	Unknown or stale entries must remain silent.

The system is a cache proxy, not a transparent real-time tunnel. Preserve raw frames and validate actual meter behavior before use.

Documentation

• Staged testing
• Wiring and voltage levels
• WT32-ETH01 flashing
• Web interface and MQTT
• Sanitized examples
• Screenshot policy
• Known limitations
• Binary release compliance
• Security policy
• Contribution guide

License

Original M-Bus Bridge code and documentation are available under the PolyForm Noncommercial License 1.0.0. Third-party components retain their own licenses; see Third-Party Notices. Prebuilt binaries are not released until LGPL distribution requirements have been reviewed.

Public repository checklist

Before publishing a fork or release, run:

git diff --check
rg -n -i "password|token|secret|api[_-]?key|ssid|serial|mac" --glob '!*.example' .
pio run -e wt32-universal --silent

Review every match. Commit only placeholders, synthetic examples, and intentionally public documentation.