search

Apollon77 / smartmeter-obis

This library supports the reading and parsing of smartmeter protocols that follow the OBIS number logic to make their data available.
MIT License
50 stars 18 forks source link

readme

smartmeter-obis

NPM version Downloads Test and Release

This library supports Node.js 16.x+.

This library supports the reading and parsing of smartmeter protocols that follow the OBIS number logic to make their data available.

Supported Protocols:

Supported Transports (how to receive the data):

Usage example (example for SerialRequestResponseTransport with D0Protocol)

var SmartmeterObis = require('smartmeter-obis');

var options = {
    'protocol': "D0Protocol",
    'transport': "SerialRequestResponseTransport",
    'transportSerialPort': "/dev/ir-usb1",
    'transportSerialBaudrate': 300,
    'protocolD0WakeupCharacters': 40,
    'protocolD0DeviceAddress': '',
    'requestInterval': 10,
    'obisNameLanguage': 'en',
    'obisFallbackMedium': 6
};

function displayData(err, obisResult) {
    if (err) {
        // handle error
        // if you want to cancel the processing because of this error call smTransport.stop() before returning
        // else processing continues
        return;
    }
    for (var obisId in obisResult) {
        console.log(
            obisResult[obisId].idToString() + ': ' +
            SmartmeterObis.ObisNames.resolveObisName(obisResult[obisId], options.obisNameLanguage).obisName + ' = ' +
            obisResult[obisId].valueToString()
        );
    }

}

var smTransport = SmartmeterObis.init(options, displayData);

smTransport.process();

setTimeout(smTransport.stop, 60000);

Usage informations

The easiest way to use the library is to use the options Object with all data to set the Library configure and initialize by it's own.

Therefor you use the init(options, storeCallback) method and provide an options Object and a callback function. The callback function is called with an error object and the parsed result as soon as a message is received completely and successfully. The callback function will get an Array of "ObisMeasurement" objects on suvccess while each entry contains all data for one datapoint. In error case you get an error object in the first parameter and can control if a new cycle should be started (return true) or if you want to stop processing (return false). The init(options, storeCallback) returns the initialized Transport instance to use to control the dataflow.

Everything else to do is to call the process() method from the returned Transport instance and the whole magic happends in the background. The called method can throw an Error as soon as invalid messages are received. In normal operation the process requests or receives the data in the defined intervals. Call stop() method from Transport instance to do a clean stop.

To debug you can also use the special debug option in the options-array.

The process

Description of options

Param Type Description
Basic configuration
[protocol] string required, value SmlProtocol, D0Protocol or JsonEfrProtocol
[transport] string required, value SerialResponseTransport, SerialRequestResponseTransport, HttpRequestTransport, LocalFileTransport, StdInTransport or TCPTransport
[requestInterval] number optional, number of seconds to wait for next request or pause serial receiving, value 0 possible to restart directly after finishing one message, Default: is 300 (=5 Minutes)
Transport specific options
[transportSerialPort] string required for Serial protocols, Serial device name, e.g. "/dev/ttyUSB0"
[transportSerialBaudrate] number optional, baudrate for initial serial connection, if not defined default values per Transport type are used (9600 for SerialResponseTransprt and 300 for SerialRequestResponseTransport)
[transportSerialDataBits] number optional, Must be one of: 8, 7, 6, or 5.
[transportSerialStopBits] number optional, Must be one of: 1 or 2.
[transportSerialParity] string optional, Must be one of: 'none', 'even', 'mark', 'odd', 'space'
[transportSerialMaxBufferSize] number optional, default value is 300000 (means after 300000 bytes without a matching message an Error is thrown )
[transportSerialMessageTimeout] number ms, optional, default value is 120000 (means after 120000ms without a matching message or new data an Error is thrown )
[transportHttpRequestUrl] string required for HttpRequestTransport, Request URL to query data from
[transportHttpRequestTimeout] number optional for HttpRequestTransport, Timeout in ms, defaut 2000
[transportLocalFilePath] string required for LocalFileTransport, File patch to read data from
[transportStdInMaxBufferSize] number optional, default value is 300000 (means after 300000 bytes without a matching message an Error is thrown )
[transportStdInMessageTimeout] number ms, optional, default value is 120000 (means after 120000ms without a matching message or new data an Error is thrown )
[transportTcpMaxBufferSize] number optional, default value is 300000 (means after 300000 bytes without a matching message an Error is thrown )
[transportTcpMessageTimeout] number ms, optional, default value is 120000 (means after 120000ms without a matching message or new data an Error is thrown )
Protocol specific options
[protocolD0WakeupCharacters] number optional for D0Protocol, number of wakeup NULL characters, default 0
[protocolD0DeviceAddress] string optional for D0Protocol, device address (max 32 characters) for SignIn-Message, default empty
[protocolD0SignOnMessage] string optional for D0Protocol, command for SignIn-Message, default "?" to query mandatory fields, other values depending on device. You can provide multiple SignOn messages separated by a comma. The delay between them can be set by parameter anotherQueryDelay
[protocolD0ModeOverwrite] string optional for D0Protocol, to ignore the mode send by the device set the correct D0 mode here. The mode send by the device in the identification message is ignored
[protocolD0BaudrateChangeoverOverwrite] number optional for D0Protocol, when the D0 mode needs a baudrate changeover, but the device information from identification message is wrong, overwrite with this value
[protocolSmlIgnoreInvalidCRC] boolean required for SmlProtocol, if false and CRC checksum is invalid an Error is thrown
[protocolSmlInputEncoding] string optionalfor SmlProtocol, if set defines the input Encoding of the data. Default is "binary" (as received from a serial connection). Other options are "ascii", "utf-8" or "base64"
[anotherQueryDelay] number optional for D0Protocol with SerialRequestResponseTransport when multiple SignOnMessages are given. Value is in ms, default 1000
OBIS options
[obisFallbackMedium] number optional, if smartmeter do not return complete OBIS IDs (without medium info) this will be used as fallback for name resolving
Debugging options
[debug] number optional, values: 0 (no logging), 1 (basic logging), 2 (detailed logging), Default: 0
[logger] function optional, logging function that accepts one parameter to log a string. Default is "console.log"

Library is tested with ...

... at least:

Please send me an info on devices where you have used the library successfully and I will add it here.

Todos

Changelog

4.0.0 (2023-11-25)

3.0.2 (2022-02-21)

2.3.0 (2021-01-23)

2.2.0 (2020-12-17)

2.1.6 (2020-11-15)

2.1.5 (2020-09-21)

2.1.4 (2020-09-21)

2.1.3 (2020-07-20)

v2.1.2 (2020-04-12)

v2.1.1 (2020-03-11)

v2.1.0 (2020-03-08)

v2.0.5 (2020-02-04)

v2.0.4 (2019-12-20)

v2.0.3 (2019-12-18)

v2.0.2 (2019-12-07)

v2.0.1 (2019-12-05)

v2.0.0 (2019-11-26)

v1.1.3 (11.11.2018)

v1.1.2 (26.03.2018)

v1.1.0 (31.01.2018)

v1.0.0 (2x.08.2017)

v0.6.0 (01.08.2017)

v0.5.12 (23.07.2017)

v0.5.11 (21.06.2017)

v0.5.7 (08.05.2017)

v0.5.6 (04.04.2017)

v0.5.5 (19.03.2017)

v0.5.2 (14.03.2017)

v0.5.1 (26.02.2017)

v0.4.1 (24.02.2017)

v0.4.0 (23.02.2017)

v0.3.5 (22.02.2017)

v0.3.4 (11.02.2017)

v0.3.3 (10.02.2017)

v0.3.2 (07.02.2017)

v0.3.1 (06.02.2017)

v0.3.0 (05.02.2017)

v0.2.6/v0.2.7 (04.02.2017)

v0.2.5

v0.2.4

v0.2.3

v0.2.2

v0.2.1

v0.0.1-0.2.0