WM-Bus - Wireless M-Bus

The Wireless M-Bus is popular metering standard widely deployed within Europe. Standard defines several bands and encoding schemes of radio signal which serve different purposes. Radio specification is defined within EN 13757–4 norm. Application layer protocol defines several communication methods. This binding is a receiver of unidirectional packets within mode S, T, C (or S1, T1, C1).

Table 1. WM-Bus binding capability table
Device discovery	Channel discovery	Read	Write	Subscribe
Yes	Yes	No	No	Yes

While binding does not discover radio interfaces out of the box, it does discover devices from received frames. The discovery logic is chained, meaning that it might be customized further, for use cases where vendor specific encoding is used within standard frame. Based on standard frame, binding will also attempt to discover channels. Because most popular WM-Bus devices are unidirectional (they broadcast their frames), binding does not attempt to read nor write data back to them. The only way to receive data is subscription.

This binding supports following radio chips:

Amber (tested AMB8465-M and AMB8665-M)
IMST (tested IM871A-USB)
Radiocrafts (tested RC1180-MBUS)

Above manufacturers are use different serial port protocol (wrappers around frames). You can attempt to use this binding with other radio chips and other chip models from these manufacturers, as long as they comply with serial port protocol.

Device discovery

The device discovery logic uses standard Wireless M-Bus header to identify device.

Header is constructed from several fields:

manufacturer - a three char manufacturer code.
device - device identifier, its serial number.
version - number which indicate hardware revision or model.
type - number which translates to pre-defined device types (oil meter, electricity meter, gas meter etc).

Header is not encrypted thus it allows to always identify sending device. In case when no further extensions are installed, binding uses above information to propose a Thing instance.

Due to popularity Wireless M-Bus is being used not only for metering. There are other applications such as smoke detection which can be reported though radio frames. Most of these use cases might require vendor mapping and customization of discovery procedure.

If your device is properly detected, but reports invalid data, it is very likely that it requires customized mapping.

Thing and Channel discovery

As mentioned above - each meter which sends data is identified as separate Thing. Once Thing is accepted through inbox functionality, additional configuration can be supplied. In most of the cases it is an encryption key which allows to decode data part of received broadcast frames.

There are several security schemes, out of which only few are currently supported:

NONE
AES_128
DES_CBC
DES_CBC_IV
AES_CBC_IV - supported
AES_CBC_IV_0
TLS

Other security modes are currently not covered by underlying WM-Bus stack. Encryption key is required in order to detect channels for devices which use encrypted data. For all other devices channel discovery is automatic.

Binding by default will create a new channel for each properly encoded data record within frame. The protocol defines several encoding schemes for data:

Empty data block
INT8
INT16
INT24
INT32
INT48
INT64
Real (32 bit)
BCD2
BCD4
BCD6
BCD8
BCD12
Date
String

Types are simplified at binding level to several top-level primitive kinds - Long, Double, Date, String, BCD and None. From that point of view items do not need to worry about exact data encoding.

Readout principles

There is no readout specification, because this binding serves as read only data acquisition tool. This means that readout will not be initiated by binding itself.

Write principles

There is no write support within this binding. There are no specific remarks for writing.

Channel definitions

Each channel is configured with div and vib parameters which uniquely identify each record within frame. The dib stands for Data Information Block and vib represents Value Information Block. Both blocks deliver together few extra pieces of information. The information which comes from these two places are:

DIB ships:

Storage - a present (0), or historical data value register.
Function
- Instant value
- Max value
- Min value
- Error value
Sub unit
Tariff
Storage number

VIB delivers:

Measurement kind
Multiplier
Measurement unit

All above information by default is placed in detected channel label / description, if available. It does not trigger any specific behavior when it comes to data acquisition.

Configuration example

dsl

Bridge co7io-wmbus:serial-jrxtx:radio1 "Serial Interface" [ serialPort="/dev/ttyS3", manufacturer="AMBER" ] { (1)

  Thing device heatMeter1 "Kamstrup Multical" [ serialNumber="01234", manufacturer="KAM", version="3", deviceType="HEAT_METER" ] { (2)
    Type number : power "Heat power" [ dib="AO", vib="10" ]  (3)
    Type number : flowRate "Flow rate" [ dib="AO", vib="11" ]
  }

  Thing device heatMeter2 "Techem ultra" [ serialNumber="43210", manufacturer="TCH", version="23", deviceType="HEAT_METER" ] {
    Type number : power "Heat power" [ dib="1D", vib="F0" ]
    Type number : flowRate "Flow rate" [ dib="3D", vib="FB" ]
  }

}

1	The jrxtx bridge assumes default serial port settings based on manufacturer, so they do not have to be specified.
2	Wireless M-Bus header is assembled automatically from device identification fields.
3	Channel associated with device rely on hex notation for DIB and VIB parameters.

co7io

<?xml version="1.0" encoding="utf-8" ?>
<things xmlns="http://connectorio.com/xmlns/managed/things">

  <bridge type="co7io-wmbus:serial-jrxtx" label="Radio interface">
    <id>radio1</id>
    <config>
      <serialPort>/dev/ttyS3</serialPort>
      <manufacturer>AMBER</manufacturer>
    </config>
  </bridge>

  <thing type="co7io-wmbus:device" label="Kamstrup Multical">
    <id>heatMeter1</id>
    <bridge>co7io-wmbus:serial-jrxtx:radio1</bridge>
    <config>
      <serialNumber>01234</serialNumber>
      <manufacturer>KAM</manufacturer>
      <version>3</version>
      <deviceType>HEAT_METER</deviceType>
    </config>
    <channel>
      <id>co7io-wmbus:device:radio1:heatMeter1:power</id>
      <type>co7io-wmbus:number</type>
      <label>Heat power</label>
      <config>
        <dib>AO</dib>
        <vib>10</vib>
      </config>
    </channel>
    <channel>
      <id>co7io-wmbus:device:radio1:heatMeter1:flowRate</id>
      <type>co7io-wmbus:number</type>
      <label>Flow rate</label>
      <config>
        <dib>AO</dib>
        <vib>11</vib>
      </config>
    </channel>
  </thing>

  <thing type="co7io-wmbus:device" label="Techem ultra">
    <id>heatMeter2</id>
    <bridge>co7io-wmbus:serial-jrxtx:radio1</bridge>
    <config>
      <serialNumber>43210</serialNumber>
      <manufacturer>TCH</manufacturer>
      <version>23</version>
      <deviceType>HEAT_METER</deviceType>
    </config>
    <channel>
      <id>co7io-wmbus:device:radio1:heatMeter2:power</id>
      <type>co7io-wmbus:number</type>
      <label>Heat power</label>
      <config>
        <dib>1D</dib>
        <vib>F0</vib>
      </config>
    </channel>
    <channel>
      <id>co7io-wmbus:device:radio1:heatMeter2:flowRate</id>
      <type>co7io-wmbus:number</type>
      <label>Flow rate</label>
      <config>
        <dib>3D</dib>
        <vib>FB</vib>
      </config>
    </channel>
  </thing>

</things>

yaml

---
things:
- kind: "Bridge"
  UID: "co7io-wmbus:serial-jrxtx:radio1"
  label: "Serial Interface"
  configuration:
    serialPort: "/dev/ttyS3"
    manufacturer: "AMBER"
  things:
  - id: "heatMeter1"
    type: "co7io-wmbus:device"
    label: "Kamstrup Multical"
    configuration:
      deviceType: "HEAT_METER"
      serialNumber: "01234"
      version: "3"
      manufacturer: "KAM"
    channels:
    - id: "power"
      type: "number"
      label: "Heat power"
      configuration:
        dib: "AO"
        vib: "10"
    - id: "flowRate"
      type: "number"
      label: "Flow rate"
      configuration:
        dib: "AO"
        vib: "11"
  - id: "heatMeter2"
    type: "co7io-wmbus:device"
    label: "Techem ultra"
    configuration:
      deviceType: "HEAT_METER"
      serialNumber: "43210"
      version: "23"
      manufacturer: "TCH"
    channels:
    - id: "power"
      type: "number"
      label: "Heat power"
      configuration:
        dib: "1D"
        vib: "F0"
    - id: "flowRate"
      type: "number"
      label: "Flow rate"
      configuration:
        dib: "3D"
        vib: "FB"