---
updatedAt: 2025-11-05T21:07:54.000Z
agentTools:
  projectIndex: https://esf.eurotech.com/llms.txt
---

# MBus Driver

This driver provides support for interacting with MBus slaves using the Driver and Asset models.\
Features:

* Meter readout in the JSON format
* Bus scanning
* Support for primary and secondary addressing

> 📘 Note
>
> It is not possible to connect the serial ports of Eurotech gateways to a MBus network directly. Connection should be made using an external MBus level converter with echo suppression.

## Global driver configuration

The driver global configuration contains parameters related to the connection. The relevant parameters depend on the mode.

### Serial mode

For establishing an serial connection, the following parameters are relevant:

* **Connection mode** must be set to `SERIAL`

* **Serial port name** should be set to the desired used serial port device (e.g. `/dev/ttyO3`)

* **Serial baud rate**

* **Serial data bits**

* **Serial stop bits**

* **Serial parity**

### IP mode

For establishing an IP connection, the following parameters are relevant:

* **Connection mode** must be set to `IP`

* **IP address** should be set to the remote hostname or IP address

* **IP port number**

## Channel configuration

The driver support the following modes for `READ` channels configurable by the **Read mode** channel parameter, the meaning of the other parameters depends on the channel mode:

* **READ**: Reads a specific slave addressed using either the primary or secondary address.

  * **Primary address**: If this parameter is set to a non-zero value, it specifies the primary address of the slave. If set to 0, the **Secondary address** parameter will be used.

  * **Secondary address**: A JSON object that defines the secondary address of the slave to read. The format of the JSON object is described in the [SecondaryAddressIn](#secondaryaddressin) section. The secondary address can contain wildcards.

  The result will contain as a JSON array of [VariableDataStructure](#variabledatastructure) objects, one for each frame received from the slave.

* **SCAN**: Discovers the secondary addresses of the devices connected to the bus.

  * **Primary address**: Must be set to 0

  * **Secondary address**: A JSON object that defines the mask to be used for scanning. The format of the JSON object is described in the [SecondaryAddressIn](#secondaryaddressin) section. The secondary address should contain wildcards.

  The result will contain as a JSON array of [SecondaryAddressOut](#secondaryaddressout) objects, one for each discovered slave.

* **SCAN\_AND\_READ**: Discovers the secondary addresses of the devices connected to the bus and performs a read on each discovered device.

  * **Primary address**: Must be set to 0

  * **Secondary address**: A JSON object that defines the mask to be used for scanning. The format of the JSON object is described in the [SecondaryAddressIn](#secondaryaddressin) section. The secondary address should contain wildcards.

  The result will contain as a JSON array of [SecondaryAddressOut](#secondaryaddressout) objects, one for each discovered slave.

In all cases the **value.type** parameter must be set to `STRING` as the driver will use the JSON format for channel output.

## JSON representation

This section describes the JSON format used by the driver for input and output data. It is recommended to check output data for missing and/or null fields, that might be present if decoding slave responses fail.

#### DeviceType

a device type

* **type** : `string` (enumerated)
* Possible values
  * `OTHER`
  * `OIL_METER`
  * `ELECTRICITY_METER`
  * `GAS_METER`
  * `HEAT_METER`
  * `STEAM_METER`
  * `WARM_WATER_METER`
  * `WATER_METER`
  * `HEAT_COST_ALLOCATOR`
  * `COMPRESSED_AIR`
  * `COOLING_METER_OUTLET`
  * `COOLING_METER_INLET`
  * `HEAT_METER_INLET`
  * `HEAT_COOLING_METER`
  * `BUS_SYSTEM_COMPONENT`
  * `UNKNOWN`
  * `RESERVED_FOR_METER_16`
  * `RESERVED_FOR_METER_17`
  * `RESERVED_FOR_METER_18`
  * `RESERVED_FOR_METER_19`
  * `CALORIFIC_VALUE`
  * `HOT_WATER_METER`
  * `COLD_WATER_METER`
  * `DUAL_REGISTER_WATER_METER`
  * `PRESSURE_METER`
  * `AD_CONVERTER`
  * `SMOKE_DETECTOR`
  * `ROOM_SENSOR_TEMP_HUM`
  * `GAS_DETECTOR`
  * `RESERVED_FOR_SENSOR_0X1D`
  * `RESERVED_FOR_SENSOR_0X1E`
  * `RESERVED_FOR_SENSOR_0X1F`
  * `BREAKER_ELEC`
  * `VALVE_GAS_OR_WATER`
  * `RESERVED_FOR_SWITCHING_DEVICE_0X22`
  * `RESERVED_FOR_SWITCHING_DEVICE_0X23`
  * `RESERVED_FOR_SWITCHING_DEVICE_0X24`
  * `CUSTOMER_UNIT_DISPLAY_DEVICE`
  * `RESERVED_FOR_CUSTOMER_UNIT_0X26`
  * `RESERVED_FOR_CUSTOMER_UNIT_0X27`
  * `WASTE_WATER_METER`
  * `GARBAGE`
  * `RESERVED_FOR_CO2`
  * `RESERVED_FOR_ENV_METER_0X2B`
  * `RESERVED_FOR_ENV_METER_0X2C`
  * `RESERVED_FOR_ENV_METER_0X2D`
  * `RESERVED_FOR_ENV_METER_0X2E`
  * `RESERVED_FOR_ENV_METER_0X2F`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X30`
  * `COM_CONTROLLER`
  * `UNIDIRECTION_REPEATER`
  * `BIDIRECTION_REPEATER`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X34`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X35`
  * `RADIO_CONVERTER_SYSTEM_SIDE`
  * `RADIO_CONVERTER_METER_SIDE`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X38`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X39`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X3A`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X3B`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X3C`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X3D`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X3E`
  * `RESERVED_FOR_SYSTEM_DEVICES_0X3F`
  * `RESERVED`

#### DataValueType

the type of the dataValue field

* **type** : `string` (enumerated)
* Possible values
  * `LONG`
  * `DOUBLE`
  * `DATE`
  * `STRING`
  * `BCD`
  * `NONE`

#### FunctionField

a function field

* **type** : `string` (enumerated)
* Possible values
  * `INST_VAL`
  * `MAX_VAL`
  * `MIN_VAL`
  * `ERROR_VAL`

#### Unit

a data unit

* **type** : `string` (enumerated)
* Possible values
  * `YEAR`
  * `MONTH`
  * `WEEK`
  * `DAY`
  * `HOUR`
  * `MIN`
  * `SECOND`
  * `DEGREE`
  * `DEGREE_CELSIUS`
  * `CURRENCY`
  * `METRE`
  * `METRE_PER_SECOND`
  * `CUBIC_METRE`
  * `CUBIC_METRE_CORRECTED`
  * `CUBIC_METRE_PER_HOUR`
  * `CUBIC_METRE_PER_HOUR_CORRECTED`
  * `CUBIC_METRE_PER_DAY`
  * `CUBIC_METRE_PER_DAY_CORRECTED`
  * `LITRE`
  * `KILOGRAM`
  * `NEWTON`
  * `NEWTONMETER`
  * `PASCAL`
  * `BAR`
  * `JOULE`
  * `JOULE_PER_HOUR`
  * `WATT`
  * `VOLT_AMPERE`
  * `VAR`
  * `WATT_HOUR`
  * `VOLT_AMPERE_HOUR`
  * `VAR_HOUR`
  * `AMPERE`
  * `COULOMB`
  * `VOLT`
  * `VOLT_PER_METRE`
  * `FARAD`
  * `OHM`
  * `OHM_METRE`
  * `WEBER`
  * `TESLA`
  * `AMPERE_PER_METRE`
  * `HENRY`
  * `HERTZ`
  * `ACTIVE_ENERGY_METER_CONSTANT_OR_PULSE_VALUE`
  * `REACTIVE_ENERGY_METER_CONSTANT_OR_PULSE_VALUE`
  * `APPARENT_ENERGY_METER_CONSTANT_OR_PULSE_VALUE`
  * `VOLT_SQUARED_HOURS`
  * `AMPERE_SQUARED_HOURS`
  * `KILOGRAM_PER_SECOND`
  * `SIEMENS`
  * `KELVIN`
  * `VOLT_SQUARED_HOUR_METER_CONSTANT_OR_PULSE_VALUE`
  * `AMPERE_SQUARED_HOUR_METER_CONSTANT_OR_PULSE_VALUE`
  * `METER_CONSTANT_OR_PULSE_VALUE`
  * `PERCENTAGE`
  * `AMPERE_HOUR`
  * `ENERGY_PER_VOLUME`
  * `CALORIFIC_VALUE`
  * `MOLE_PERCENT`
  * `MASS_DENSITY`
  * `PASCAL_SECOND`
  * `SPECIFIC_ENERGY`
  * `SIGNAL_STRENGTH`
  * `SIGNAL_STRENGTH_MICROVOLT`
  * `LOGARITHMIC`
  * `RESERVED`
  * `OTHER_UNIT`
  * `COUNT`
  * `CUBIC_METRE_PER_SECOND`
  * `CUBIC_METRE_PER_MINUTE`
  * `KILOGRAM_PER_HOUR`
  * `CUBIC_FEET`
  * `US_GALLON`
  * `US_GALLON_PER_MINUTE`
  * `US_GALLON_PER_HOUR`
  * `DEGREE_FAHRENHEIT`

#### SecondaryAddressOut

a secondary address present in output data

* **type** : `object`\ <br />**Properties**:

***

##### manufacturerId

the manufacturer id

* **type** : `string`

***

##### deviceId

the device id

* **type** : `string`

***

##### version

the device version

* **type** : `number`

***

##### deviceType

* a [DeviceType](#devicetype) element

***

##### asBytes

the secondary address encoded as a byte array

* **type** : `array`\
  Element type:\
  a secondary address byte as unsigned integer
  * **type** : `number`

***

##### asHex

the secondary adddres represented as an hex string

* **type** : `string`

***

Example:

```json
{
  "manufacturerId": "LSE",
  "deviceId": 10318243,
  "version": 30,
  "deviceType": "BUS_SYSTEM_COMPONENT",
  "asBytes": [67, 130, 49, 16, 101, 50, 30, 14],
  "asHex": "4382311065321E0E"
}
```

#### DataValue

a data value

* **type** : `variant`\ <br />**Variants**:

  ***

  a numeric value, if dataValue is `LONG`, `DOUBLE`, `BCD` or `DATE`. In the latter case, this field represents the date as the number of milliseconds sice UNIX epoch

  * **type** : `number`

  ***

  a string value, if dataValue is `STRING`

  * **type** : `string`

  ***

#### DataRecord

a data record in a VariableDataStructure

* **type** : `object`\ <br />**Properties**:

***

##### description

a description

* **type** : `string`

***

##### multiplierExponent

the multiplier exponent

* **type** : `number`

***

##### scaledDataValue

* **can be null** if dataValue is not a number\
  the scaled data value
* **type** : `number`

***

##### storageNumber

the storage number

* **type** : `number`

***

##### subunit

the subunit

* **type** : `number`

***

##### tariff

the tariff

* **type** : `number`

***

##### dataValue

* **can be null** if the dataValueType field is `NONE`
* a [DataValue](#datavalue) element

***

##### dib

the dib

* **type** : `array`\
  Element type:\
  a dib byte represented as unsigned integer
  * **type** : `number`

***

##### vib

the vib

* **type** : `array`\
  Element type:\
  a vib byte represented as unsigned integer
  * **type** : `number`

***

##### dataValueType

* a [DataValueType](#datavaluetype) element

***

##### functionField

* a [FunctionField](#functionfield) element

***

##### unit

* a [Unit](#unit) element

***

#### VariableDataStructure

a variable structure received as part of a request

* **type** : `object`\ <br />**Properties**:

***

##### encryptionMode

describes the encryption mode

* **type** : `string`

***

##### accessNumber

the access number

* **type** : `number`

***

##### secondaryAdddress

* a [SecondaryAddressOut](#secondaryaddressout) element

***

##### manufacturerData

the manufacturer data

* **type** : `array`\
  Element type:\
  a manufacturer data byte represented as unsigned integer
  * **type** : `number`

***

##### numberOfEncryptedBlocks

the number of encrypted blocks

* **type** : `number`

***

##### header

the header

* **type** : `array`\
  Element type:\
  a header byte represented as unsigned integer
  * **type** : `number`

***

##### status

the status

* **type** : `string`

***

Example:

```json
{
  "encryptionMode": "NONE",
  "accessNumber": 25,
  "secondaryAddress": {
    "manufacturerId": "LSE",
    "deviceId": 10318243,
    "version": 30,
    "deviceType": "BUS_SYSTEM_COMPONENT",
    "asBytes": [67, 130, 49, 16, 101, 50, 30, 14],
    "asHex": "4382311065321E0E"
  },
  "manufacturerData": [],
  "numberOfEncryptedBlocks": 0,
  "header": [114, 67, 130, 49, 16, 101, 50, 30, 14, 25, 0, 0, 0],
  "status": 0,
  "dataRecords": [{
    "description": "ON_TIME",
    "multiplierExponent": 0,
    "scaledDataValue": 4283.0,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": 4283,
    "dib": [12],
    "vib": [34],
    "dataValueType": "BCD",
    "functionField": "INST_VAL",
    "unit": "HOUR"
  }, {
    "description": "DATE_TIME",
    "multiplierExponent": 0,
    "scaledDataValue": null,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": 962106720099,
    "dib": [4],
    "vib": [109],
    "dataValueType": "DATE",
    "functionField": "INST_VAL",
    "unit": null
  }, {
    "description": "MODEL_VERSION",
    "multiplierExponent": 0,
    "scaledDataValue": 3.444564688926E12,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": 3444564688926,
    "dib": [6],
    "vib": [253, 12],
    "dataValueType": "LONG",
    "functionField": "INST_VAL",
    "unit": null
  }, {
    "description": "PARAMETER_SET_ID",
    "multiplierExponent": 0,
    "scaledDataValue": null,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": "WTT16",
    "dib": [13],
    "vib": [253, 11],
    "dataValueType": "STRING",
    "functionField": "INST_VAL",
    "unit": null
  }, {
    "description": "DATE",
    "multiplierExponent": 0,
    "scaledDataValue": null,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": 4993747200100,
    "dib": [50],
    "vib": [108],
    "dataValueType": "DATE",
    "functionField": "ERROR_VAL",
    "unit": null
  }, {
    "description": "ADDRESS",
    "multiplierExponent": 0,
    "scaledDataValue": 256.0,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": 256,
    "dib": [2],
    "vib": [250, 61],
    "dataValueType": "LONG",
    "functionField": "INST_VAL",
    "unit": null
  }, {
    "description": "% BATT",
    "multiplierExponent": 0,
    "scaledDataValue": 94.0,
    "storageNumber": 0,
    "subunit": 0,
    "tariff": 0,
    "dataValue": 94,
    "dib": [1],
    "vib": [124, 6, 84, 84, 65, 66, 32, 37],
    "dataValueType": "LONG",
    "functionField": "INST_VAL",
    "unit": null
  }]
}
```

#### SecondaryAddressIn

a secondary address present in channel configuration

* **type** : `object`\ <br />**Properties**:

***

##### manufacturerId

* **can be null** to use a wildcard, or `asBytes` or `asHex` are specified\
  the manufacturer id
* **type** : `string`

***

##### deviceId

* **can be null** to use a wildcard, or `asBytes` or `asHex` are specified\
  the device id
* **type** : `variant`\ <br />**Variants**:
  ***
  the device id encoded a number between 0 and 99999999
  * **type** : `number`
  ***
  the device id encoded as a string, it must have lenght 8 and contain only digits or `f` wildcards
  * **type** : `string`
  ***

***

##### version

* **can be null** to use a wildcard, or `asBytes` or `asHex` are specified\
  the device version
* **type** : `number`

***

##### deviceType

* **can be null** to use a wildcard, or `asBytes` or `asHex` are specified\
  the device type
* **type** : `variant`\ <br />**Variants**:
  ***
  the device id encoded as a number
  * **type** : `number`
  ***
  * a [DeviceType](#devicetype) element
  ***

***

##### asBytes

* **can be null** if the other parameters are specified\
  the secondary address encoded as a byte array
* **type** : `array`\
  Element type:\
  a secondary address byte as unsigned integer
  * **type** : `number`

***

##### asHex

* **can be null** if the other parameters are specified\
  the secondary adddres represented as an hex string
* **type** : `string`

***

Examples:

```json
{
  "asHex": "4382311065321E0E"
}
```

```json
{
  "deviceId": 10318243,
  "manufacturerId": "LSE"
}
```

```json
{
  "asHex": "FFFFFFFFFFFFFFFF"
}
```

```json
{
  "deviceId": "1031FFFF"
}
```