Wireless M-Bus Decoder

The Wireless M-Bus Decoder module enables simple decoding and decryption of wireless M-Bus messages (wM-Bus), which are sent from a wM-Bus concentrator to niotix via a connector.

In the following, wM-Bus concentrators are devices that receive wM-Bus messages from meters or other devices and transmit them via LoRaWAN or another LPWAN protocol such as NB-IoT. The wireless M-Bus decoder is integrated via a connector that is used with the virtual devices. This distributes the packets from the wM-Bus concentrators to the individual wM-Bus devices and also decrypts and decodes them.

Feature Summary

The Wireless M-Bus Decoder provides a comprehensive solution for decoding and decrypting wM-Bus messages sent from meters or other devices via a concentrator to niotix. Here are the key features:

1. Decoding and decryption of wM-Bus messages

• The module receives encrypted AES-encrypted OMS messages from wM-Bus devices.
• Messages are decrypted and decoded to display values such as meter readings, temperatures or other measurement data.

2. Support for manufacturer-specific fields

• In addition to standardised OMS messages, the decoder also supports manufacturer-specific fields for improved integration with devices from manufacturers such as Kamstrup, Landis+Gyr and Sontex.
  List of manufacturers

  • BMeters
  • Carlo Gavazzi
  • Danfoss
  • Diehl Metering
  • EBZ
  • Engelmann
  • Flonida
  • Integra Metering
  • Kamstrup
  • Landis+Gyr
  • Lansen
  • Minol-ZENNER
  • Müller-Electronic
  • Sagemcom
  • Sontex

3. Virtual device mapping

• Decoded messages are mapped to the corresponding virtual devices that have been set up as meters or other wM-Bus devices. The data is stored in the virtual device and made available for further processing.

4. Transformation of data

• Transformation and calculation rules can be used to further process and adapt the decoded messages, e.g. for unit conversions or changing the names of variables.

5. Error handling and forwarding of decoder errors

• Decoder errors are forwarded to the virtual device and output in the JSON object under the key decoderErrors.

6. Forwarding of reception quality and data source

• RSSI (signal strength) is taken from the received payload
• External ID of the receiving bridge (gateway_source_identifier) is forwarded to the meter virtual device (VD)

Data flow

Messages from a wM-Bus device are first recorded and forwarded by a wM-Bus concentrator in so-called fixed network operation. The AES-encrypted wM-Bus messages are forwarded to niotix via LoRaWAN or NB-IoT, for example, and passed on to a virtual device of the concentrator via a connector.

If a virtual device, for example a wM-Bus meter, is created with the wireless M-Bus connector, information such as the manufacturer’s serial number and the wM-Bus key (AES key) are stored in the device as connector-specific parameters.

The messages are then sent to the Wireless M-Bus decoder via an integration flow, which decodes and decodes the packets and assigns them to the individual devices. The decoded wM-Bus packet is transformed as usual in the virtual device via a Device Driver and persisted via data points in the and is available for further processing.

The data flow looks as follows in the overview:

Configuration in detail

The steps for integrating wM-Bus devices and concentrators are described in detail below. Once the initial integration is complete, only steps 3 and 8 are required to create additional devices and concentrators.

1. Creating a connector for the wM-Bus concentrator

The first step is to create a connector for the wM-Bus concentrators. All available input-side connectors for virtual devices can be used.

Concentrators with NB-IoT or LTE

Concentrators that send data via NB-IoT or LTE can be integrated with the “Webhook (incoming)” and “MQTT (incoming)” connectors.

In the “Connection data” tab, the data can be transformed based on the standard “Virtual Device Inbound” template. By default, the “id” parameter is used as the external ID of the virtual device. The standard structure for inbound data packets is

{                                                                 
    "id": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890", 
    "timestamp": "2022-09-08T12:51:51.897Z",      
    "payload": {
        "omsPayload": "44c14b2053fc2c486d67288a16b5b6ae6f03fe7830711d6fba9d2",
        "receptionTimestamp": "2024-01-08T06:00:00.000Z",
        "rssi": -123
    }                         
 }       

• omsPayload: The encrypted OMS message of the wMBus device as a hex string
• receptionTimestamp: The timestamp of the packet reception by the wireless M-Bus gateway in ISO format (ISO 8601). If this timestamp is not available, the reception timestamp in niotix is used
• rssi: Reception signal strength of the wMBus message in dBm (optional), can be passed on to the virtual device of the meter

The OMS message must be included in the properties of the payload object. If necessary, the payload can still be transformed in the Device Driver of the concentrator (see Step 2).

If the messages are sent via LTE or NB-IoT, the complete OMS message is sent by the concentrator as an object together with any other values.

Data flow in detail

Concentrators with LoRaWAN

wM-Bus concentrators with LoRaWAN usually send two different message types:

• OMS payload: The encoded wM-Bus message is split up by the concentrator and sent in individual LoRaWAN payloads
• Status payloads: Status payloads contain information about the status of the concentrator and are sent via a different port, for example

As the wM-Bus payloads are split into individual LoRaWAN payloads depending on the manufacturer, these must be reassembled using an additional service (reassembler). This can be done via NodeRed in niotix, for example, or via a service provided by the manufacturer.

The complete OMS messages are then forwarded from the reassembler to the virtual device of the wM-Bus concentrator via the “Webhook (incoming)” or “MQTT (incoming)” connectors in niotix.

Data flow in detail

2. Create Device Driver for wM-Bus concentrator

The Device Driver of the wM-Bus concentrator has the function of transforming and persisting status messages of the concentrator, for example a battery level. In addition, the concentrator message can be transformed for specific devices if it does not yet correspond to the required format.

The wireless m-Bus connector expects the OMS payload as an output object of the Javascript function parser with the following properties:

• omsPayload: The encrypted OMS message of the wMBus device as a hex string
• receptionTimestamp: The timestamp of the packet reception by the wireless M-Bus gateway in ISO format (ISO 8601). If this timestamp is not available, the reception timestamp in niotix is used
• rssi: Reception signal strength of the wMBus message in dBm (optional), can be passed on to the virtual device of the meter

Example object as output of the function parser:

{
        "omsPayload": "44c14b2053fc2c486d67288a16b5b6ae6f03fe7830711d6fba9d2",
        "receptionTimestamp": "2024-01-08T06:00:00.000Z",
        "rssi": -42
}

In addition, further data points for monitoring the device, such as a battery level, can be created in the Device Driver of the wM-Bus concentrator using the calculation variables and type definitions. If no further transformation is required in the Device Driver, the following minimal function is used in the JavaScript parser:

module.exports = function (payload, meta) {
  return payload;
}

If the incoming payload needs to be transformed, for example because the OMS payload is contained in a string with additional information or is not sent as a hex string, this transformation is carried out using the JavaScript parser. In addition, the calculation variables can be used to perform simple transformations and calculations (e.g. renaming or division). At least the minimum Javascript parser must always be defined.

3. Create wM-Bus concentrator as virtual device

A virtual device with the defined Device Driver and connector is created for each concentrator. All known options are available for this: individually via the user interface, as a CSV import or via the XAPI

4. Creating a transformation

In the following steps, the components of an integration flow are defined in the “Integrations” menu and then the integration flow itself is created. As a rule, only a simple transformation is required:

• Output format: application/json
• Type: jsonata
• Transformation: $

If the _parsed data point does not yet have the required parameters, it can be converted to the required format using the transformation. However, it is recommended to carry out this transformation in the respective Device Driver (see 2. Create Device Driver for wM-Bus concentrator). The receptionTimestamp parameter is optional.

Required output format of the transformation:

{
  "meta": {
    "state_identifier": "_parsed"
  },
  "value": {
    "omsPayload": "44c14b2053fc2c486d67288a16b5b6ae6f03fe7830711d6fba9d2",
    "receptionTimestamp": "2024-01-08T06:00:00.000Z",
    "rssi": -42
  }
}

5. Creating a filter

The filter is selected so that only the OMS messages to be decoded are forwarded. For example, the following filter can be used:

• Mode: extended.
• Type: JSONATA
• Input type: application/json
• Code:

$.meta.state_identifier = '_parsed' and $exists($.value.omsPayload)

If the parameter omsPayload is also to be used within the account without the wireless M-Bus connector, it is recommended to define the filter differently, for example based on the device group or another property.

6. Creating a connector of the type “Wireless MBus Decoder”

If the module is activated, a connector of the type “Wireless M-Bus Decoder” can be created in the menu item Integrations / Connectors. If the module is deactivated, the connectors of type “Wireless M-Bus Decoder” are also deactivated.

The “Simple Default Format” template is activated by default. This automatically generates properties from the decoded values and the OMS descriptors, which can be processed directly in the virtual device. The key is generated according to the following scheme:

Key = [Description] + _ + [Tariff] + _ + [MemoryNo] + _ + [Subunit]

**Example

The following property:

"Volume_0_1_0": 236,666

is made up of the parameters

• Description: Volume
• Tariff: 0
• Storage number: 1
• Sub-unit: 0
• Value: 236.666

The following setting in the connector activates the simplified format:

• Template: Simple Default Format

The object decoderRaw contains the complete output object of the decoder, which can be used alternatively and contains additional information.

The time stamps are generated according to the following logic:

1. if a time stamp is encoded in the OMS message, this is used. The time zone of the device can be set in minutes in the template in the “Connection data” tab using the “utcMinuteOffset” parameter.

Example for time zone UTC+1 (default)

const utcMinuteOffset = 60;

2. if no timestamp is coded in the OMS message, the timestamp receptionTimestamp is used, which is sent by the concentrator or otherwise generated by niotix.

Example output:

[
    {
        "meta": {
            "time": "2024-01-30T11:59:45Z"
        },
        "decoderRaw": {"..."},
        "Volume_0_0_0": 240.216,
        "On_time_0_0_0": 2449383,
        "Manufacturer_specific_VIF__0x20_0_0_0": 0,
        "rssi": -123,
        "gateway_source_identifier": "ABC123456789",
    },
    {
        "meta": {
            "time": "2023-12-30T23:00:00.000Z"
        },
        "Volume_0_1_0": 236.666,
        "Flow_temperature_0_1_0": 16,
        "External_temperature_0_1_0": 22
    }
]

• rssi: Signal strength upon reception (optional, otherwise zero)
• gateway_source_identifier: External ID of the receiving wMBus bridge

Errors in decoding the message are also output, for example, if the AES key is incorrect:

[
  {
  "meta": {
    "time": "2023-12-30T23:00:00.000Z"
  },
  "On_time_0_0_0": 141834,
  "decoderErrors": "No working key found"
  }
]

7. Creating an integration flow

An integration flow can then be created, which consists firstly of the filter created, secondly of the transformer and thirdly of the Wireless M-Bus Decoder connector. This integration flow sends the wM-Bus messages to the wireless M-Bus decoder. From there, the messages are distributed to the respective virtual devices of this connector.

9. Creating a Device Driver for each meter type

The wireless M-Bus decoder generates a decoded and decrypted message object. A Device Driver with a function parser or the calculation variables can be used to transform the variable names or adapt the units. The definition of the target variables in the Device Driver determines which data points of the virtual device are created. If the template Simple Default Format was selected in step 6, the simple parser can be used:

module.exports = function (payload, meta) {
  return payload;
}

Simple calculations or renaming can then be carried out using the calculation variables.

8. Creating the meter as a virtual device

The virtual device is created as usual individually via the user interface, as a CSV import or via the XAPI. If the device limit for the wireless M-Bus decoder in the current account is reached, no further devices can be created. Unlike other connectors to external systems, the “External ID” field is not filled in, but generated by the system. The following connector-specific fields are available:

• External ID: The external ID is automatically generated for internal use according to the scheme: manufacturer code_serial number
• Manufacturer code: The manufacturer code consists of three capital letters and enables the manufacturer to be identified
• Device key: AES key for wM-Bus (HEX, 32 digits), not required for unencrypted messages
• Device serial number: Serial number of the manufacturer (HEX, 8 digits)