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

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

functionField

unit

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

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



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