search

Apollon77 / node-mbus

Nodejs mbus module
MIT License
20 stars 15 forks source link

readme

node-mbus

NPM version Test and Release Downloads

This library provides access to selected functions of the libmbus (https://github.com/rscada/libmbus) to communicate with mbus devices via serial or TCP connections.

The library is based on the great work of samkrew (https://github.com/samkrew) which developed the basis of this module for node 0.x.

Usage example

var MbusMaster = require('node-mbus');

var mbusOptions = {
    host: '127.0.0.1',
    port: port,
    timeout: 2000,
    autoConnect: true
};
var mbusMaster = new MbusMaster(mbusOptions);

mbusMaster.connect();

// request for data from devide with ID 1
mbusMaster.getData(1, function(err, data) {
    console.log('err: ' + err);
    console.log('data: ' + JSON.stringify(data, null, 2));

    mbusMaster.close();
});

Method description

MbusMaster(options)

Constructor to initialize the MBusMaster instance to interact with the devices. In the options object you set the communication and other parameter for the library:

A note about TCP communcation timeout

On TCP networks, this sets the response time-out in milliseconds. The default is a quite conservative 4 seconds (4000ms). For serial networks, it is a function of the baud rate: between 11 and 330 "bit times" to which one should factor in some round-trip-time delay for network traversal.

libmbus uses the following equation to estimate this on serial networks (factoring in about 100ms round-trip-time between the host and the M-Bus driver):

(330 + 11) / BAUD + 0.15

connect(callback)

Call this method to connect to TCP/Serial. Needs to be done before you can communicate with the devices. The optional callback will be called with an error parameter that is null on success. The method will return true/false when no callback is provided.

close(callback, waitTillClosed)

Call this method to close the TCP/Serial connections. The optional callback will be called with an error parameter that is null on success. The method will return true/false when no callback is provided. When you have provided a callback and you try to close the connection while communication is in progress the method will wait till communication has finished (checked every 500ms), then close the connection and then call the callback. When not using a callback then you get false as result in this case. When you set waitTillClosed while using a callback the callback will be called with an error if communication is still ongoing.

getData(address, [options,] callback)

This method is requesting "Class 2 Data" from the device with the given address.

The options parameter is optional, and if given, is in the form of an object with one or more of the following properties set:

The callback is called with an error and data parameter. When data are received successfully the data parameter contains the data object. When you try to read data while communication is in progress your callback is called with an error.

Data example:

{
  "SlaveInformation": {
    "Id": 11490378,
    "Manufacturer": "ACW",
    "Version": 14,
    "ProductName": "Itron BM +m",
    "Medium": "Cold water",
    "AccessNumber": 41,
    "Status": 0,
    "Signature": 0
  },
  "DataRecord": [
    {
      "id": 0,
      "Function": "Instantaneous value",
      "StorageNumber": 0,
      "Unit": "Fabrication number",
      "Value": 11490378,
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 1,
      "Function": "Instantaneous value",
      "StorageNumber": 0,
      "Unit": "Volume (m m^3)",
      "Value": 54321,
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 2,
      "Function": "Instantaneous value",
      "StorageNumber": 1,
      "Unit": "Time Point (date)",
      "Value": "2000-00-00",
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 3,
      "Function": "Instantaneous value",
      "StorageNumber": 1,
      "Unit": "Volume (m m^3)",
      "Value": 0,
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 4,
      "Function": "Instantaneous value",
      "StorageNumber": 0,
      "Unit": "Time Point (time & date)",
      "Value": "2012-01-24T13:29:00",
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 5,
      "Function": "Instantaneous value",
      "StorageNumber": 0,
      "Unit": "Operating time (days)",
      "Value": 0,
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 6,
      "Function": "Instantaneous value",
      "StorageNumber": 0,
      "Unit": "Firmware version",
      "Value": 2,
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 7,
      "Function": "Instantaneous value",
      "StorageNumber": 0,
      "Unit": "Software version",
      "Value": 6,
      "Timestamp": "2018-02-24T22:17:01"
    },
    {
      "id": 8,
      "Function": "Manufacturer specific",
      "Value": "00 00 8F 13",
      "Timestamp": "2018-02-24T22:17:01"
    }
  ]
}

scanSecondary(callback)

This method scans for secondary IDs (?!) and returns an array with the found IDs. The callback is called with an error and scanResult parameter. The scan result is returned in the scanResult parameter as Array with the found IDs. If no IDs are found the Array is empty. When you try to read data while communication is in progress your callback is called with an error.

Note: The secondary scan can take a while, so > 5-100 seconds is normal depending on the used timeouts! When there are ID collisions and scan needs to get a level deeper then it can take even longer. So just know that it can take very long :-)

setPrimaryId(oldAddress, newAddress, callback)

This method allows you to set a new primary ID for a device. You can use any primary (Number, 0..250) or secondary (string, 16 characters long) address as oldAddress. The newAddress must be a primary address as Number 0..250. The callback will be called with an empty error parameter on success or an Error object on failure. When you try to read data while communication is in progress your callback is called with an error.

MBust-Master Devices reported as working

Todo

Changelog

2.2.4 (2024-05-09)

2.2.2 (2024-04-05)

2.2.1 (2024-03-28)

2.1.0 (2023-08-11)

2.0.0 (2022-06-29)

1.2.2 (2021-03-06)

1.2.1 (2020-08-16)

1.2.0 (2020-08-02)

1.1.0 (2020-04-12)

1.0.1 (2019-10-16)

1.0.0 (2019-05-04)

0.6.0/1 (2018-12-09)

v0.5.2 (2018.04.18)

v0.5.1 (2018.04.16)

v0.5.0 (2018.03.26)

v0.3.0 (2018.03.15)

v0.2.x (2018.03.11)

v0.1.x (2018.03.06)