ChangelogDownloads
HomeGuidesChangelog
ChangelogDownloadsSupportMulti-service IoT Edge GatewaysEUROTECH
Guides
SupportMulti-service IoT Edge GatewaysEUROTECH

MBus Driver

Suggest Edits

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

Updated about 1 year ago