M-Bus (Meter-Bus) is a European standard (EN 13757) for the remote reading of utility meters such as water, gas, heat, and electricity meters. Based on a master-slave architecture, the M-Bus master supplies power to the serial bus and periodically polls the connected slave devices (meters) to collect their consumption data.
The Weble universal gateway M-Bus driver acts as the M-Bus master and supports three connection types:
- Serial — wired M-Bus via RS485/RS232/USB, the most common setup for building metering installations.
- TCP — M-Bus over TCP/IP through an M-Bus to Ethernet converter, used when meters are physically far from the gateway.
- Wireless — Wireless M-Bus (wM-Bus) using a USB receiver, for wirelessly transmitting meter data without physical bus wiring.
The driver supports a wide range of meter types from over 100 manufacturers including Kamstrup, Siemens, Landis & Gyr, Diehl, Itron, Danfoss, Sensus, Sontex, and Techem. It handles multi-frame data for complex devices such as Siemens RVD heating controllers that return large data sets across multiple M-Bus response frames.
¶ 1. Getting started
¶ 1.1 Serial setup
This is the most common M-Bus configuration. The gateway connects to the M-Bus via a serial interface (typically a USB to M-Bus converter).
- Create a new gateway and select the M-Bus driver.
- Set the Type to
Serial. - Select the Serial Port — use the auto-complete to select the connected USB interface. Using the unique ID is recommended for stability.
- Set the Serial Baudrate to match the bus speed (default:
2400baud, the M-Bus standard rate). - Configure the Polling interval (e.g.
60000for one reading per minute, or use a cron expression like0 * * * *for every hour).
Once the gateway is started, use the Scan Primary or Scan Secondary functions to discover connected meters (see section 5).
¶ 1.2 TCP setup
When using an M-Bus to TCP/IP converter (e.g. a Relay PadPuls or similar device):
- Set the Type to
TCP. - Enter the Host (IP address of the converter) and Port (default:
10001). - Configure polling and other parameters as needed.
¶ 1.3 Wireless setup (wM-Bus)
For wireless M-Bus meters:
- Set the Type to
Wireless. - Select the Serial Port of the wM-Bus USB receiver stick.
- Use the Scan Wireless function to listen for nearby meters.
Wireless meters require a Driver selection (the wM-Bus decoder matching the meter model) and optionally an encryption Key if the meter data is encrypted.
¶ 2. Gateway parameters
¶ 2.1 General parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this M-Bus gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Description | description | Optional description for this gateway. |
| Type | type | Connection type: Serial (wired via serial port), TCP (via M-Bus to TCP converter), or Wireless (wM-Bus receiver). |
| Only values | onlyValues | If enabled (default), simplifies the address structure to only expose the counter values. When disabled, addresses include additional metadata (units, meter types). |
| Emit change | emitOnlyChanges | Controls when new values are emitted: only changes (emit only when the value changes), each cycles (emit on every poll cycle), or a duration in milliseconds at which the last known value is periodically re-emitted. Default: only changes. |
¶ 2.2 Serial parameters
These parameters are visible when the Type is Serial.
| Label | JSON Key | Description |
|---|---|---|
| Serial Port | serialPort | The serial interface connected to the M-Bus. Auto-complete lists detected USB/serial interfaces. Use unique ID for stability. |
| Serial Baudrate | serialBaudRate | Bus speed: 300, 600, 1200, 2400 (default, M-Bus standard), 4800, 9600, 19200, or 38400. |
| Polling (ms/cron) | polling | Read frequency. Accepts a duration in milliseconds (e.g. 60000 for 1 minute) or a cron expression (e.g. 0 * * * * for every hour). Multiple schedules can be combined with ; (e.g. 0 * * * * ; 30 12 * * 6-7). Default: 1000. |
¶ 2.3 TCP parameters
These parameters are visible when the Type is TCP.
| Label | JSON Key | Description |
|---|---|---|
| Host | host | IP address or domain name of the M-Bus to TCP converter. Default: 192.168.1.1. |
| Port | port | TCP port on which the converter listens. Default: 10001. |
| Polling (ms/cron) | polling | Same as serial polling (see above). |
¶ 2.4 Advanced parameters
These parameters are visible for Serial and TCP types. They are hidden when Legacy driver is enabled.
| Label | JSON Key | Description |
|---|---|---|
| Request timeout (ms) | requestTimeout | Maximum time in milliseconds to wait for a meter response before triggering a timeout error. Default: 5000. |
| Idle timeout (ms) | idleTimeout | Pause in milliseconds between each request sent on the bus. Increase this value if the bus or meters are slow. Default: 1000. |
| Retries on timeout | retry | Number of times the driver retries a request when a meter does not respond. Default: 0 (no retry). |
| Apply unit factor | applyUnitFactor | If enabled (default), automatically applies unit conversion factors (m³, kWh, etc.) to the raw meter values. |
| Legacy driver | legacyDriver | Use the legacy M-Bus driver (based on libmbus/node-mbus) instead of the current JS implementation. The legacy driver has fewer configuration options but may be needed for compatibility with certain setups. |
¶ 2.5 TCP Server parameters
These parameters are visible for Serial and TCP types.
| Label | JSON Key | Description |
|---|---|---|
| TCP Server | tcpServer | Enable a built-in TCP server that exposes the M-Bus serial line. When a TCP client connects, the driver stops its own polling and acts as a transparent TCP to Serial bridge for the connected client. Useful for allowing third-party M-Bus master software to access the bus. |
| TCP Server port | tcpServerPort | TCP port on which the server listens. Default: 8222. |
¶ 2.6 Gateway JSON examples
Serial M-Bus:
{
"type": "serial",
"serialPort": "/dev/serial/by-id/usb-FTDI_FT232R-if00",
"serialBaudRate": 2400,
"polling": 60000,
"requestTimeout": 5000,
"idleTimeout": 1000,
"retry": 1,
"applyUnitFactor": true,
"onlyValues": true,
"emitOnlyChanges": true,
"legacyDriver": false,
"tcpServer": false,
"tcpServerPort": 8222
}
TCP M-Bus:
{
"type": "tcp",
"host": "192.168.1.100",
"port": 10001,
"polling": "0 */15 * * *",
"requestTimeout": 10000,
"idleTimeout": 1000,
"retry": 2,
"applyUnitFactor": true,
"onlyValues": true,
"emitOnlyChanges": true,
"legacyDriver": false
}
Wireless M-Bus:
{
"type": "wireless",
"serialPort": "/dev/serial/by-id/usb-IMST_iM871A-if00"
}
¶ 3. Addresses
¶ 3.1 Address format
M-Bus addresses use the prefix %mbus: followed by the slave identifier and optionally a data record path:
%mbus:1— main device address for primary address 1 (readable, triggers a fresh read from the meter)%mbus:12345678— main device address by secondary address%mbus:1/0— data record #0 from the meter at primary address 1%mbus:1/0/value— just the value of record #0 (with scale and offset applied)%mbus:1/0/timestamp— the timestamp of record #0
The main address (without /) is readable — reading it triggers a fresh M-Bus request to the meter. Sub-addresses (with /record) are automatically populated when the meter responds.
¶ 3.2 Wired address parameters (Serial / TCP)
| Label | JSON Key | Description |
|---|---|---|
| Device ID | name | The M-Bus slave address: a primary address (0-250) or a secondary address (8-digit number). |
| Description | description | Optional description. |
| Scale | scale | Multiplication factor applied to the raw value. Default: 1. Final value = raw × scale + offset. |
| Offset | offset | Value added after scaling. Default: 0. |
| Polling (ms/cron) | polling | Per-address polling override. If set, this meter is read at a different frequency than the gateway default. Only available with the new driver (not legacy). |
| Max frames | maxFrames | Optional. Limits the number of M-Bus response frames read from this meter. Some devices (e.g. Siemens RVD controllers) return data across multiple frames. Leave empty to read all frames, or set a value to reduce request time. Only visible on main addresses. |
| Max records | maxRecords | Optional. Limits the number of data records imported from the meter response. Useful to keep only the first records which are usually the most relevant (main counter values). Leave empty to import all records. Only visible on main addresses. |
| Skip loops | skipLoops | (Legacy, deprecated) Skip N polling loops between reads. Prefer using per-address Polling with cron or millisecond intervals instead. Only visible on main addresses. |
| Log | log | Logging mode: never, on update, always, or a duration in milliseconds. |
¶ 3.3 Wireless address parameters
| Label | JSON Key | Description |
|---|---|---|
| Device ID | name | The wireless meter address (serial number). |
| Description | description | Optional description. |
| Key | key | Encryption key for decoding the meter's wireless telegrams. Required if the meter uses AES encryption. |
| Driver | driver | The wM-Bus decoder driver matching the meter model. Select Auto for automatic detection, or choose a specific driver (e.g. multical21, hydrus, compact5, omnipower). |
¶ 3.4 Value calculation
For wired M-Bus addresses, the final value is calculated as:
value = raw_value × scale + offset
This is useful for applying custom unit conversions. For example, to convert liters to m³, set scale = 0.001.
¶ 3.5 Supported meter types (wireless)
The driver supports a wide range of wM-Bus meter types:
| Category | Drivers |
|---|---|
| Water meters | apator162, hydrus, hydrodigit, multical21, flowiq2200, flowiq3100, izar, izar3, q400, ultrimis, itron, minomess, and more |
| Heat meters | compact5, multical302/403/602/603/803, sharky774, ultraheat, sensostar, vario451, elf, microclima, hydroclima |
| Electricity meters | ebzwmbe, ehzp, esyswm, em24, omnipower, amiplus, gransystems |
| Heat cost allocators | eurisii, fhkvdataiii, fhkvdataiv, qcaloric, sontex868, bfw240radio |
| Temperature/Humidity | cma12w, lansenth, rfmamb, munia, piigth |
| Gas meters | unismart |
| Smoke detectors | ei6500, lansensm, tsd2, qsmoke |
| Pulse counters | lansenpu |
| Door/Window sensors | lansendw |
¶ 3.6 M-Bus mediums
Each M-Bus meter reports its medium — the type of utility being measured:
| Code | Medium |
|---|---|
| 00 | Other |
| 01 | Oil |
| 02 | Electricity |
| 03 | Gas |
| 04 | Heat |
| 05 | Steam |
| 06 | Hot Water |
| 07 | Water |
| 08 | H.C.A. (Heat Cost Allocation) |
¶ 4. Scanning and device discovery
¶ 4.1 Primary scan
The primary scan sends ping requests to each primary address in a specified range (0 to 250) and reads the data from any responding meter.
To perform a primary scan, use the context menu on the gateway and select Scan Primary. Enter the address range (e.g. from 0 to 250) to scan the entire bus.
Each M-Bus slave has a primary address between 0 and 250 assigned during installation. The primary scan is fast but only works when each meter has a unique primary address — if two meters share the same primary address, they will collide.
¶ 4.2 Secondary scan
The secondary scan uses the M-Bus secondary addressing mechanism to discover meters regardless of their primary addresses. Each meter has a unique secondary address — a 16-character hexadecimal string that encodes:
| Characters | Content | Encoding |
|---|---|---|
| 1–8 | Meter serial number (ID) | BCD (digits 0–9 only) |
| 9–12 | Manufacturer code | Hex (0–F) |
| 13 | Version | Hex (0–F) |
| 14 | Medium | Hex (0–F) |
| 15–16 | Additional info | Hex (0–F) |
¶ Scan mask
The secondary scan uses a mask with F as wildcard characters. The driver probes the bus with the mask, and if a meter responds, it reads the full secondary address. If multiple meters respond simultaneously (collision), the driver automatically narrows down by iterating through each wildcard digit position.
Common masks:
| Mask | Effect |
|---|---|
FFFFFFFFFFFFFFFF |
Scans all devices (full wildcard — may be slow on large buses). |
12345678FFFFFFFF |
Scans only devices with ID 12345678. |
FFFFFFFF4D25FFFF |
Scans only Siemens (manufacturer code 4D25) devices. |
FFFFFFFFFFFFFF07 |
Scans only water meters (medium 07). |
¶ Collision resolution algorithm
The secondary scan works recursively, similar to a tree search:
- The driver sends a select command with the current mask.
- If one meter responds → the meter is found, its full secondary address is read.
- If multiple meters respond (collision) → the driver narrows the mask by iterating the first wildcard digit (0–9 for BCD positions, 0–F for hex positions) and recurses.
- If no meter responds (timeout) → the mask is skipped after retrying.
This process efficiently discovers all meters on the bus even when hundreds of devices are connected, though it can take several minutes on large installations.
To perform a secondary scan, use the context menu on the gateway and select Scan Secondary. Enter the mask or use the default FFFFFFFFFFFFFFFF to scan all devices.
¶ 4.3 Cancel scan
A secondary scan can be canceled at any time via the context menu (Cancel Scan Secondary). This is useful for long-running scans on large buses.
¶ 4.4 Wireless scan
For wireless M-Bus, the scan function simply listens for incoming wM-Bus telegrams from nearby meters. Detected meters are automatically added as addresses. Use the context menu and select Scan Wireless to start listening.
¶ 4.5 Changing primary address
The primary address of a meter can be changed via the context menu (Set Primary). Enter the new primary address (0–250). This sends an M-Bus command directly to the meter to update its primary address.
Warning: Changing the primary address modifies the meter's configuration permanently.
¶ 4.6 Changing baudrate
The baudrate of a meter can be changed via the context menu (Set Baudrate). This is useful for optimizing bus communication speed.
¶ 5. Multi-frame support (Siemens RVD and similar controllers)
Some M-Bus devices, such as Siemens RVD25x/RVD26x heating controllers, return large amounts of data that span multiple M-Bus response frames. A standard M-Bus frame can carry approximately 50 data records, but complex controllers may expose hundreds of data points (temperatures, valve positions, pump states, diagnostics, etc.).
The maxFrames parameter on each address controls how many consecutive frames the driver will request from the meter. After receiving each frame, the driver checks if the meter indicates more records follow and sends the next frame request.
To read all data from a Siemens RVD controller:
- Discover the meter using primary or secondary scan.
- Set the
maxFramesparameter to a sufficient value (e.g.10or higher) on the main address. - Optionally set
maxRecordsto limit the total number of imported data records.
The driver automatically merges all records from multiple frames into a single unified address tree.
For a complete Siemens RVD integration example, see the article M-Bus - Siemens RVD25x/RVD26x Heating Controllers.
¶ 6. TCP Server mode
When TCP Server is enabled, the M-Bus driver opens a TCP listening socket (default port 8222). This allows external M-Bus master software (e.g. a commissioning tool or third-party BMS) to connect and communicate directly with the meters on the serial bus.
When a TCP client connects:
- The driver stops its own polling to avoid bus conflicts.
- The serial line is bridged to the TCP socket — all data from the TCP client is forwarded to the serial port and vice versa.
- When the TCP client disconnects, the driver resumes normal polling.
This is useful for:
- Remote diagnostics — connecting from a Windows PC via VPN with an M-Bus programming/diagnostics tool to remotely configure or troubleshoot meters without being physically on site (see section 6.1).
- Commissioning — connecting vendor tools to configure meters without physically accessing the bus.
- Sharing — allowing multiple systems to access the same M-Bus installation (one at a time).
¶ 6.1 Remote M-Bus diagnostics via VPN
A powerful use case for the TCP Server feature is to connect remotely from a Windows PC — via VPN — with a professional M-Bus diagnostics tool such as NG-MScan2. This allows a technician to scan, configure, and troubleshoot M-Bus meters from anywhere in the world, as if they were physically connected to the bus.
The setup requires:
- On the Weble gateway: enable TCP Server on the M-Bus driver (default port
8222). - VPN connection: establish a VPN connection between the Windows PC and the gateway's network (using Weble VPN, site-to-site VPN, or any other VPN solution).
- On the Windows PC: install and run the Weble Serial Emulator TCP tool.
¶ Serial Emulator TCP tool
Since M-Bus diagnostics software (like NG-MScan2) expects to communicate via a local COM port, the Serial Emulator TCP tool creates a virtual serial port bridge:
- com0com (included) creates a virtual COM port pair on Windows (e.g.
COM90↔COM91). These two ports are internally wired together — anything written to one is read from the other. - The Serial Emulator TCP script opens
COM91and establishes a TCP connection to the gateway's M-Bus TCP Server (e.g.192.168.1.99:8222). All data is transparently forwarded between the serial port and the TCP socket. - The M-Bus tool (NG-MScan2) opens
COM90and communicates as if it were connected to a physical M-Bus serial interface.
¶ Installation
Run install.bat as Administrator. It will:
- Install the com0com virtual serial port driver.
- Create a virtual port pair (
COM90↔COM91).
¶ Usage
Open serialEmulatorTCP_GUI.exe. The GUI allows you to configure the connection parameters (host, port, COM port, baudrate, etc.) and start the bridge with a single click. The default settings from gui_config.txt are pre-filled (host 192.168.1.99, port 8222, COM 90, baudrate 2400). Adjust the host to match the gateway's IP address (via VPN) and click connect.
Alternatively, the bridge can be started from the command line:
serialEmulatorTCP.exe --host=<gateway-ip> --port=8222 --weble-mbus
Key parameters (configurable via GUI or command line):
| Parameter | Description |
|---|---|
--host=<ip> |
IP address of the Weble gateway (via VPN). |
--port=8222 |
TCP Server port configured on the M-Bus driver. |
--weble-mbus |
Enables the Weble M-Bus handshake protocol. When active, the tool waits for the gateway's M-Bus driver to be ready before bridging. If the bus is busy (e.g. scanning), an error is displayed. |
--COM90 |
Virtual COM port number (default: 90). |
--baud=2400 |
Serial baudrate (must match the M-Bus bus speed). |
--parity=even |
Serial parity (M-Bus standard: even). |
Once the bridge is connected and ready, open NG-MScan2 (or any other M-Bus tool) and select COM90 as the serial port. The tool can now scan, read, and configure all meters on the remote M-Bus installation as if locally connected.
Note: While the TCP client is connected, the gateway's own M-Bus polling is paused to avoid bus conflicts. Polling resumes automatically when the client disconnects.