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 section. The secondary address can contain wildcards.
The result will contain as a JSON array of 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 section. The secondary address should contain wildcards.
The result will contain as a JSON array of 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 section. The secondary address should contain wildcards.
The result will contain as a JSON array of 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

Properties:

manufacturerId

the manufacturer id

type : string

deviceId

the device id

type : string

version

the device version

type : number

deviceType

a 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:

{
  "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

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

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 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 element

functionField

a FunctionField element

unit

a Unit element

VariableDataStructure

a variable structure received as part of a request

type : object

Properties:

encryptionMode

describes the encryption mode

type : string

accessNumber

the access number

type : number

secondaryAdddress

a 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:

{
  "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

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

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

Variants:
the device id encoded as a number
- type : number
- a 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:

{
  "asHex": "4382311065321E0E"
}

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

{
  "asHex": "FFFFFFFFFFFFFFFF"
}

{
  "deviceId": "1031FFFF"
}

📘Note

Global driver configuration

Serial mode

IP mode

Channel configuration

JSON representation

DeviceType

DataValueType

FunctionField

Unit

SecondaryAddressOut

manufacturerId

deviceId

version

deviceType

asBytes

asHex

DataValue

DataRecord

description

multiplierExponent

scaledDataValue

storageNumber

subunit

tariff

dataValue

dib

vib

dataValueType

functionField

unit

VariableDataStructure

encryptionMode

accessNumber

secondaryAdddress

manufacturerData

numberOfEncryptedBlocks

header

status

SecondaryAddressIn

manufacturerId

deviceId

version

deviceType

asBytes

asHex

📘
Note