OBIS (Object Identification System) is the standardized addressing scheme defined by IEC 62056 for energy meters. The Weble universal gateway OBIS driver reads data from smart meters and energy meters using several IEC 62056 sub-protocols over serial, TCP, or HTTP connections.
The driver supports the following protocols:
- D0 Protocol — based on IEC 62056-21 (formerly IEC 61107/EN 61107), communicates in ASCII format over serial. This is the most common protocol for reading electricity, gas, and water meters via their optical interface or serial port.
- SML Protocol — SmartMeterLanguage, a binary format used primarily by German smart meters (eHZ, eBZ).
- JsonEfrProtocol — reads OBIS data from EFR Smart Grid Hub devices in JSON format over HTTP.
- DLMS — DLMS/COSEM (IEC 62056), the full binary protocol stack over HDLC. Supports both active connection (Mode E) and passive listening.
The driver also provides a By meter model mode with presets for specific meters, simplifying the configuration to just selecting the meter model.
¶ 1. Getting started
¶ 1.1 Choosing the right protocol
| Protocol | Transport | Use case |
|---|---|---|
| D0 Protocol | Serial | Most electricity meters with optical port or RS485 interface. Default baudrate: 300 baud (auto-negotiation to higher speed). |
| SML Protocol | Serial / TCP | German smart meters (Discovergy, EMH, eBZ). Binary format. |
| JsonEfrProtocol | HTTP | EFR Smart Grid Hub — reads OBIS data via HTTP API. |
| DLMS | Serial | Advanced meters supporting DLMS/COSEM. Two transport modes available. |
| By meter model | Serial | Simplified setup — just select the meter model. Currently supports Landis & Gyr E450 and Kamstrup OMNIPOWER HAN. |
¶ 1.2 Gateway configuration (D0 Protocol example)
- Create a new gateway and select the OBIS IEC62056 meters driver.
- Set Protocol to
D0Protocol. - Configure the serial port connected to the meter (optical head, RS485, or USB adapter).
- Set the Serial Baudrate to
300(the D0 protocol starts at 300 baud and auto-negotiates to a higher speed). - Configure serial parameters: DataBits
7, StopBits1, Parityeven(standard D0 settings).
¶ 1.3 Gateway configuration (By meter model)
For supported meters, the By meter model mode is the simplest:
- Set Protocol to
By meter model. - Select the Model (e.g.
Landis & Gyr E450). - Configure only the Serial Port — all other serial parameters are auto-configured.
¶ 1.4 Reading meter data
Once the gateway is started, the driver automatically queries the meter and creates addresses for all discovered OBIS codes. The addresses are organized in a tree structure.
For example, a typical electricity meter might expose:
%obis:1-0:1.8.0*255— total active energy import (kWh)%obis:1-0:2.8.0*255— total active energy export (kWh)%obis:1-0:16.7.0*255— instantaneous active power (W)%obis:1-0:32.7.0*255— voltage L1 (V)%obis:1-0:31.7.0*255— current L1 (A)
¶ 2. Gateway parameters
¶ 2.1 General parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this OBIS gateway instance. |
| Cluster ID | cluster | Cluster identifier. Use 0 for single-gateway setups. |
| Description | description | Optional description. |
| Protocol | protocol | Communication protocol: D0Protocol, SmlProtocol, JsonEfrProtocol, DLMS, or By meter model. |
| Model | meterModel | Only visible in By meter model mode. Meter model preset: Landis & Gyr E450 or Kamstrup OMNIPOWER HAN. |
| Transport type | type | Transport medium: serial, tcp, or http. Hidden in D0, DLMS, and By meter model modes (serial is forced). |
| Request timeout (ms) | timeout | Maximum time in milliseconds to wait for a meter response. Default: 10000. |
| Idle timeout (ms) | idleTimeout | Pause in milliseconds before sending a new request. Default: 5000. |
¶ 2.2 Serial parameters
Visible when transport type is serial or when using D0/DLMS/By meter model protocols.
| Label | JSON Key | Description |
|---|---|---|
| Serial Port | serialPort | Serial interface connected to the meter. Auto-complete lists detected USB/serial interfaces. |
| Serial Baudrate | serialBaudRate | Initial baudrate. For D0: 300 (auto-negotiation). For E450: 2400. Values: 300 to 115200. |
| Serial DataBits | serialDataBits | Data bits per character: 5, 6, 7 (D0 standard), or 8. |
| Serial StopBits | serialStopBit | Stop bits: 1 or 2. |
| Serial Parity | serialParity | Parity: none, even (D0/DLMS standard), odd, mark, or space. |
¶ 2.3 TCP parameters
Visible when transport type is tcp.
| Label | JSON Key | Description |
|---|---|---|
| Host | host | IP address or domain of the meter or TCP-serial converter. |
| Port | port | TCP port. Default: 10001. |
¶ 2.4 HTTP parameters
Visible when transport type is http (JsonEfrProtocol).
| Label | JSON Key | Description |
|---|---|---|
| http request url | httpRequestUrl | The URL from which to query OBIS data. |
¶ 2.5 D0 Protocol parameters
Visible when protocol is D0Protocol.
| Label | JSON Key | Description |
|---|---|---|
| D0 wake up chars | protocolD0WakeupCharacters | Number of NULL characters sent before the first transmission to wake up the meter. Default: 0. |
| D0 sign on message | protocolD0SignOnMessage | Command for the sign-on message. Default: ? (queries all mandatory fields). Other values depend on the meter. |
| D0 mode overwrite | protocolD0ModeOverwrite | Override the D0 mode reported by the meter. Leave empty to use the mode from the meter's identification message. |
| D0 baudrate overwrite | protocolD0BaudrateChangeoverOverwrite | Override the baudrate change. Use when the meter reports incorrect baudrate information. |
¶ 2.6 SML Protocol parameters
Visible when protocol is SmlProtocol.
| Label | JSON Key | Description |
|---|---|---|
| SML ignore invalid CRC | protocolSmlIgnoreInvalidCRC | If enabled, CRC checksum errors are ignored. Useful for meters with known CRC issues. |
| SML input encoding | protocolSmlInputEncoding | Input data encoding: binary (default, from serial), ascii, utf-8, or base64. |
¶ 2.7 DLMS parameters
Visible when protocol is DLMS.
| Label | JSON Key | Description |
|---|---|---|
| DLMS Transport | dlmsTransport | Transport mode: hdcModeE (gateway initiates via IEC 62056-21 Mode E then switches to HDLC — e.g. Landis+Gyr E650 optical port) or hdlcListen (passive listening of DLMS/HDLC frames pushed by the meter — e.g. Landis+Gyr E450, Kamstrup on M-Bus). |
¶ 2.8 Gateway JSON examples
D0 Protocol (standard optical head):
{
"protocol": "D0Protocol",
"type": "serial",
"serialPort": "/dev/serial/by-id/usb-FTDI_FT232R-if00",
"serialBaudRate": 300,
"serialDataBits": 7,
"serialStopBit": 1,
"serialParity": "even",
"timeout": 10000,
"idleTimeout": 5000,
"protocolD0WakeupCharacters": 0,
"protocolD0SignOnMessage": "?"
}
By meter model (Landis & Gyr E450):
{
"protocol": "By meter model",
"meterModel": "Landis & Gyr E450",
"serialPort": "/dev/serial/by-id/usb-MBUS-if00",
"serialBaudRate": 2400,
"serialDataBits": 8,
"serialStopBit": 1,
"serialParity": "even"
}
SML Protocol (German smart meter via TCP):
{
"protocol": "SmlProtocol",
"type": "tcp",
"host": "192.168.1.50",
"port": 10001,
"protocolSmlIgnoreInvalidCRC": false,
"protocolSmlInputEncoding": "binary"
}
¶ 3. Addresses
¶ 3.1 Address format
OBIS addresses use the prefix %obis: followed by the OBIS code:
%obis:<medium>-<channel>:<measurement>.<type>.<tariff>*<previous>
Where:
- medium —
0= abstract,1= electricity,7= gas,8= water - channel —
0= no channel - measurement — identifies what is measured (e.g.
1= active energy import,2= active energy export,16= active power) - type —
7= instantaneous,8= cumulative - tariff —
0= total,1/2= tariff 1/2 - previous —
255= current value
¶ Common OBIS codes for electricity meters
| OBIS code | Description |
|---|---|
1-0:1.8.0*255 |
Total active energy import (kWh) |
1-0:1.8.1*255 |
Active energy import tariff 1 |
1-0:1.8.2*255 |
Active energy import tariff 2 |
1-0:2.8.0*255 |
Total active energy export (kWh) |
1-0:16.7.0*255 |
Instantaneous total active power (W) |
1-0:32.7.0*255 |
Voltage L1 (V) |
1-0:52.7.0*255 |
Voltage L2 (V) |
1-0:72.7.0*255 |
Voltage L3 (V) |
1-0:31.7.0*255 |
Current L1 (A) |
1-0:51.7.0*255 |
Current L2 (A) |
1-0:71.7.0*255 |
Current L3 (A) |
1-0:14.7.0*255 |
Frequency (Hz) |
¶ 3.2 Address parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The OBIS address (auto-discovered from the meter). |
| Description | description | Optional description. |
| Log | log | Logging mode: never, on update, always, or a duration in ms. |
¶ 3.3 Address properties
| Property | Value |
|---|---|
| Readable | Yes (main addresses only, triggers a fresh meter read) |
| Writable | No (read-only from meters) |
| Routable | Yes |
| Loggable | Yes |
¶ 4. Supported meters
¶ 4.1 Meter model presets
| Model | Protocol | Default serial settings |
|---|---|---|
| Landis & Gyr E450 | DLMS (hdlcListen) | 2400 baud, 8 data bits, 1 stop bit, even parity |
| Kamstrup OMNIPOWER HAN | DLMS | 2400 baud, 8 data bits, 1 stop bit, no parity |
¶ 4.2 Compatible meters (D0 Protocol)
The D0 protocol is widely supported by electricity meters from most manufacturers. Any meter with an IEC 62056-21 optical port or RS485 interface should work with the D0 protocol. Common examples include:
- Landis+Gyr E350, E550, ZMD
- Iskraemeco MT174, MT880
- ABB A/B series
- EMH ED300, eHZ
- Elster AS1440, A1800
- And many more IEC 62056-21 compatible meters
¶ 4.3 Landis+Gyr E650 (DLMS Mode E)
The E650 meter is supported via DLMS over the optical port. Configure Protocol DLMS and DLMS Transport hdcModeE.
For a complete E450 integration example, see the article Landis & Gyr E450 meters.