OMS (Wireless M-Bus)

OMS (Open Metering System) is a wireless protocol based on the M-Bus (Meter-Bus) standard, commonly used in Europe for reading smart meters for water, gas, heat, and electricity. It operates on 868 MHz radio frequency and uses AES-128 encryption for secure data transmission.

Details

OMS is sometimes referred to as wireless M-Bus or wM-Bus. The protocol follows the EN 13757 standard for meter data exchange.

How OMS Works

OMS meters periodically broadcast their readings over radio. A receiver (like a USB stick or gateway) captures these telegrams and forwards them to energy2mqtt via MQTT. The data is encrypted with AES-128, so you need the encryption key from your meter provider to decode the readings.

Typical Setup

[Smart Meter] ---(868 MHz radio)---> [OMS Receiver] ---(MQTT)---> [energy2mqtt] ---> [Home Assistant]

Common OMS receivers include:

  • IMST iM871A USB stick
  • Amber Wireless AMB8465-M
  • CUL-based receivers with wMBus firmware
  • ZENNER Datahub (cloud-based)

Protocol Details

Telegram Structure

Each OMS telegram contains several fields that identify the meter and its data:

Field Description Example
L Field Length of telegram 0x2D (45 bytes)
C Field Control field (message type) 0x44 (SND_NR)
M Field Manufacturer code (3 letters) ELS → Elvaco
A Field Serial number 12345678
Version Device version 0x33
Device Type Medium being measured 0x07 (Cold Water)

Device Types (Medium Codes)

Code Medium
0x02 Electricity
0x03 Gas
0x04 Heat
0x06 Hot Water
0x07 Cold Water
0x0A Cooling (Return)
0x0B Cooling (Flow)
0x0C Heat (Volume)
0x0D Combined Heat/Cooling

DIN Address Format

Each meter is identified by a unique DIN address in this format:

{device_type}{manufacturer}{version}{serial_number}

Example: 07ELS3312345678

  • 07 = Cold Water
  • ELS = Elvaco
  • 33 = Version 0x33
  • 12345678 = Serial number

Security Modes

OMS supports different security modes. energy2mqtt currently supports:

Mode Description Status
Mode 5 AES-128 CBC encryption ✅ Supported
Mode 7 AES-128 with authentication ⏳ Planned
Unencrypted No encryption ✅ Supported

For Security Mode 5, the decryption uses:

  • Key: Your 16-byte AES key (provided by meter manufacturer)
  • IV (Initialization Vector): Constructed from M-Field + A-Field + Access Number
Details

After decryption, valid data always starts with 0x2F 0x2F. If you see different bytes, your encryption key might be wrong.

Data Encoding (DIF/VIF)

Meter values are encoded using DIF (Data Information Field) and VIF (Value Information Field):

  • DIF tells you the data type and length
  • VIF tells you what the value represents (energy, volume, power, etc.) and its unit

Common VIF examples:

VIF Code Measurement Unit Scale
0x13 Volume Liters ×0.001
0x14 Volume Liters ×0.01
0x15 Volume Liters ×0.1
0x16 Volume Liters ×1
0x03 Energy Wh ×1
0x06 Energy kWh ×1
0x2B Power W ×1

Configuration

To configure OMS meters in energy2mqtt, you need to add them to your e2m.yaml configuration file.

Required Information

Before configuring, gather this information for each meter:

  1. Name: A friendly name for the meter
  2. DIN Address (ID): The unique identifier (see format above)
  3. Encryption Key: 16-byte hex key from your meter provider

Configuration Example

oms:
  - name: "Water Meter Kitchen"
    id: "07ELS3312345678"
    key: "0102030405060708090A0B0C0D0E0F10"

  - name: "Gas Meter"
    id: "03KAM0198765432"
    key: "AABBCCDDEEFF00112233445566778899"

  - name: "Heat Meter Basement"
    id: "04ZEN2011223344"
    key: "112233445566778899AABBCCDDEEFF00"

Configuration Parameters

Parameter Required Description
name Yes Friendly name for the meter (shown in Home Assistant)
id Yes DIN address in format: {type}{manufacturer}{version}{serial}
key Yes AES-128 encryption key as 32-character hex string
Details

The encryption key must be exactly 32 hexadecimal characters (16 bytes). If your provider gave you a shorter key, it might be wrong or use a different format.

MQTT Input

energy2mqtt listens for OMS telegrams on the MQTT topic:

oms_input

The message should contain the raw telegram as a hex-encoded string.

Example MQTT message:

2D44A5113412785607337206004C052F2F...

The input needs to be a complete OMS frame with the inner-frame CRC removed and checked by the concentrator.

Output Data

After processing, energy2mqtt publishes the parsed meter data via MQTT. The data includes:

  • Meter name
  • All decoded measurements with units
  • Protocol metadata (manufacturer, device type, etc.)
  • CRC verification status
  • Decrypted payload (for debugging)

Example output values:

Field Example Value Description
volume 1234.567 Total volume in liters
flow_temperature 45.2 Flow temperature in °C
return_temperature 35.8 Return temperature in °C
power 2500 Current power in W
energy 12345.6 Total energy in kWh

Troubleshooting

Common Issues

“CRC verification failed”

  • The telegram was corrupted during transmission
  • Check your OMS receiver antenna and position

“Decryption failed” or wrong values

  • Verify your encryption key is correct
  • Make sure the DIN address matches exactly
  • Check if the key format is hexadecimal (not Base64)

“Unknown device type”

  • The meter uses a device type code not yet supported
  • Open an issue on GitHub with the device type code

Getting Your Encryption Key

The encryption key is usually:

  • Printed on a card that came with the meter
  • Available through your utility provider’s portal
  • Provided by the meter manufacturer on request
Details

Some utilities use the same key for all meters of one type. Ask your provider if you can’t find individual keys.

ZENNER Datahub Integration

If you’re using ZENNER Datahub with the ZENNER Gateways as OMS receiver, energy2mqtt can receive data directly from the Datahub cloud. The Datahub handles the decryption and parsing for you, so you don’t need to configure encryption keys.

Just add the the forwarding via HTTP or MQTT in the same way as you do for the LoRaWAN part. See the ZENNER Datahub documentation for more information about the platform.