DLMS Gas JavaScript API

Connector functions DLMS Gas JS API guide

The dlms_gas API provides a unified framework for managing Smart Gas meters from various manufacturers.

Manufacturer-based behavior

This API is designed to abstract behavior based on different manufacturers. Currently, the following behaviors have been specified:

• pietro
• watertech
• honeywell
• spark

There is a common or default behavior that serves as a basis for all manufacturers and that they overwrite when they need to. In addition, the API is designed to be extended and customized with new behaviors in the development of new CFs.

Connector Functions Implementation

Some use cases for how to implement a CF are explained below.

Standard connector function implementation with already defined behaviors

dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collect();

In this case, the call to dlms_gas.init() will initialize the initial parameters based on the device information and the configuration specified in the organization’s default entity. For more details on the behavior of dlms_gas.init(), see the dlms_gas.config properties and dlms_gas.init() function.

Next, when executing dlms_gas.decode(), the received Compact Frame will be decoded based on the standard specification of the already known compact frames (47, 48, 49, 51, 97). For more details on the behavior of dlms_gas.decode(), see the dlms_gas.decode section.

The next step is to execute the actions corresponding to the session (OpenGate operations, information requests, time change…). For more details on the actions performed, see the dlms_gas.pendingActions section.

Finally, dlms_gas.collect() is invoked, which is responsible for collecting data from the three entities involved in gas device communications: meter, network cell, and organizational unit. For more details on the behavior of dlms_gas.collect(), see the dlms_gas.collect section.

Configuration initialization

The following examples show some cases of how to vary the initial configuration.

The first case shows how to initialize the session using a configuration entity different from the organization’s. In this case, it starts from the idea that the entity representing the organization contains a suffix.

const orgName = entity._value('provision.administration.organization') + '_dev';
dlms_gas.init(orgName);

Another option is to modify the configuration once initialized. In this example, we see how the maxClockSkewAllowedSec and italianMode parameters are overwritten. The dlms_gas.config parameters are explained in the dlms_gas.config section.

dlms_gas.init();
dlms_gas.config.maxClockSkewAllowedSec = 10;
dlms_gas.config.italianMode = false;

Finally, it may be necessary to overwrite the API key. This case is not recommended, but if necessary, it is done as follows:

dlms_gas.config.__initApiKey('different-api-key');

Configuration of actions to be performed in the session

Without changing the order of the actions to be performed, it is possible to force or avoid certain actions being performed.

The following example shows how to avoid attempting to change the meter’s time.

dlms_gas.actions.setClock = false;
dlms_gas.pendingActions();

It is also possible to force some of the actions to be performed even if the conditions for their normal behavior are not met. For example, the request for certain information is only made when a device connects for the first time to the platform in order to collect some of its initial configuration. However, it is possible to force this request every time it connects:

dlms_gas.actions.forceInitialData = true;
dlms_gas.pendingActions();

For all options, see the dlms_gas.actions section. Although initially with this configuration the order of the actions cannot be changed (see the dlms_gas.pendingActions section), it is possible to overwrite the order or even change the actions to be performed with more advanced programming that we will see later.

Customization of compact frames decoding

Currently, the following Compact Frames are considered: 47, 48, 49, 51, and 97.

The specification for decoding a CF is based on objects with the following specification:

{
  "template":{},
  "initAndCollect": function(data){}
}

The template property is a JSON following what is specified in the DLMS API documentation for the dlms.getCompactData function and the typeDescription parameter. The dlms_gas.decode function calls the getCompactData function with the specified template.

The initAndCollect method is responsible for loading the decoded values of the compact frame into the devCollection object. It is not mandatory to implement this method if it is not necessary to collect the decoded CF. This method can also be used to initialize other variables of interest for the session. For example, it is common to initialize the variables dlms_gas.recUnixTime, dlms_gas.recMetEventsCounter, and dlms_gas.recNonMetEventsCounter.

The dlms_gas.decode function internally uses the corresponding template specification object (see default properties) to decode the received template, but it is possible to pass a specific object as a parameter in which to specify a different specification.

In this example, we will see what the (made-up) decoding of a compact frame identified with number 32 could look like:

const customTemplate = {
  "template": {
        'attrId': 2, 'template': 32, 'type': 'structure',
        'items': [
          { 'type': 'unsigned' },
          { 'type': 'double-long-unsigned' },
          { 'type': 'long-unsigned' },
          { 'type': 'long-unsigned' },
        ]
      },
  "initAndCollect": function (data) { 
      logger.trace(`Collecting data from cf 32`);
      dlms_gas.recUnixTime = data[1];
      dlms_gas.recMetEventsCounter = data[2];
      dlms_gas.recNonMetEventsCounter = data[3];
      dlms_gas.devCollection.addDatapoint('mType', data[0], dlms_gas.recUnixTime);
      dlms_gas.devCollection.addDatapoint('metCount', dlms_gas.recMetEventsCounter, dlms_gas.recUnixTime);
      dlms_gas.devCollection.addDatapoint('nonMetCount', dlms_gas.recNonMetEventsCounter, dlms_gas.recUnixTime);
      dlms_gas.devCollection.addDatapoint('contSinLect', false, dlms_gas.now);
  }
};
const decodeResult = dlms_gas.decode(customTemplate);

Another possibility is simply to change the decoding behavior of an already specified compact frame (47, 48, 49, 51, 97). In this case, there are several options to carry this out.

The first one is to create a completely new specification using the original template and defining the initAndCollect function:

const custom48 = {
  "template": dlms_gas.default["48"].template,
  "initAndCollect": function (data) { 
      logger.trace(`Collecting data from cf 48 with custom behavior`);
      dlms_gas.devCollection.addDatapoint(...);
      dlms_gas.devCollection.addDatapoint(...);
      dlms_gas.devCollection.addDatapoint(...);
      dlms_gas.devCollection.addDatapoint(...);
      dlms_gas.devCollection.addDatapoint(...);
      ...
  }
};
const decodeResult = dlms_gas.decode(custom48);

Following this line, it is also possible to implement the initAndCollect method using the default behavior but extending or altering that behavior as much as possible. An example could be the following, where the default behavior is used but then additional actions are performed:

const custom48 = {
  "template": dlms_gas.default["48"].template,
  "initAndCollect": function (data) { 
      logger.trace(`Collecting data from cf 48 extending default behavior`);
      dlms_gas.default["48"].initAndCollect(data);
      // extra actions: for example, adjust received time.
      dlms_gas.recUnixTime = dlms_gas.recUnixTime - (60 * 60 * 1000);
  }
};
const decodeResult = dlms_gas.decode(custom48);

Fully customized behaviors

The dlms_gas API includes objects responsible for encapsulating the functions and properties of different behaviors:

• dlms_gas.default: contains all the properties and functions used to perform all actions.
• dlms_gas.pietro: overwrites the functions and properties necessary to support the behavior of Pietro-type meters.
• dlms_gas.honeywell: overwrites the functions and properties necessary to support the behavior of Honeywell-type meters.
• dlms_gas.watertech: overwrites the functions and properties necessary to support the behavior of Watertech-type meters.
• dlms_gas.spark: overwrites the functions and properties necessary to support the behavior of Spark-type meters.

Each behavior is specified at initilization time according to device manufacturer. If the device manufacturer is unknown, the dlms_gas.default behavior will be used.

A simple way to test different behaviors is to overwrite the dlms_gas.behavior property. In the following example, the behavior is forced to be honeywell regardless of the manufacturer:

dlms_gas.behavior = 'honeywell';
dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collect();

Once dlms_gas.behavior is specified as honeywell, the rest of the logic is executed with the Honeywell behavior.

Finally, it is possible to define or extend the complete behavior of the API. It may be that with the configurations or specifications seen so far, it is not possible to adapt to a particular case. In this case, it will be necessary to define a new behavior to be used in the rest of the connector function. This is done as follows:

const newBehavior = {/*actions and properties*/};
dlms_gas.customBehavior(newBehavior);
dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collection();

When calling dlms_gas.customBehavior(newBehavior), the dlms_gas.behavior variable is initialized with the value 'custom' and the dlms_gas.custom object is initialized with the specified parameter. From here on, all other actions will be done based on what is specified in newBehavior. See dlms_gas.customBehavior for more information.

It is possible to specify “base” behavior for a custom one using the baseBehavior property. In this case, it will try to look for defined functions and properties in newBehavior and if not found, it will try to find them in baseBehavior. Finally if it is not found in baseBehavior it will try to find it in dlms_gas.default.

In next example, when looking for a function or property, it will follow next order to find it: newBehavior -> honeywell -> default.

const newBehavior = {
  "baseBehavior": "honeywell",
  /*actions and properties*/
};
dlms_gas.customBehavior(newBehavior);
dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collect();

Reviewing the decoding examples from the previous section, they could be incorporated using the concept of customBehavior.

The following example shows how to define a new compact frame specification, while maintaining the possibility for the connector function to support other compact frames because the decode method is not forced to use the specification passed as a parameter.

const newBehavior = {
  "32": {
    "template": {
        'attrId': 2, 'template': 32, 'type': 'structure',
        'items': [
          { 'type': 'unsigned' },
          { 'type': 'double-long-unsigned' },
          { 'type': 'long-unsigned' },
          { 'type': 'long-unsigned' },
        ]
      },
    "initAndCollect": function (data) { 
        logger.trace(`Collecting data from cf 32`);
        dlms_gas.recUnixTime = data[1];
        dlms_gas.recMetEventsCounter = data[2];
        dlms_gas.recNonMetEventsCounter = data[3];
        dlms_gas.devCollection.addDatapoint('mType', data[0], dlms_gas.recUnixTime);
        dlms_gas.devCollection.addDatapoint('metCount', dlms_gas.recMetEventsCounter, dlms_gas.recUnixTime);
        dlms_gas.devCollection.addDatapoint('nonMetCount', dlms_gas.recNonMetEventsCounter, dlms_gas.recUnixTime);
        dlms_gas.devCollection.addDatapoint('contSinLect', false, dlms_gas.now);
    }
  }
};
dlms_gas.customBehavior(newBehavior);
dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collect();

If you want to modify the behavior of initAndCollect of some known compact frame (47, 48, 49, 51, and 97), it is even simpler, as they internally have an overridable collection method, so you only need to define that method in the custom behavior.

const newBehavior = {
  "initAndCollectCf48": function (data) { 
    //custom behavior
  }     
};
dlms_gas.customBehavior(newBehavior);
dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collect();

The initAndCollect function of the predefined compact frames 47, 48, 49, 51, and 97 internally calls the corresponding initAndCollectCfxx method. Therefore, you only need to overwrite that method to alter its behavior.

The same concept applies to the dlms_gas.pendingActions and dlms_gas.collect functions. Internally, they call methods defined in default. Therefore, they can be easily modified. For example, the order in which actions are performed could be modified or even new actions could be added as in the following example, where the default actions are invoked first and then a custom action is invoked.

const newBehavior = {
    "pendingActions": function () {
      dlms_gas.default.pendingActions();
      dlms_gas.custom.customPendingAction();
    },
    "customPendingAction": function() {
        // custom action
    }
};
dlms_gas.customBehavior(newBehavior);
dlms_gas.init();
dlms_gas.decode();
dlms_gas.pendingActions();
dlms_gas.collect();

The previous example shows several important concepts:

• The pendingActions function is overwritten for the new behavior, so when the main dlms_gas.pendingActions() method is invoked, the new custom function will be executed.
• A new function customPendingAction is defined and will be executed when dlms_gas.pendingActions() is invoked.
• To call to the default pendingActions function, it is done through the default object (dlms_gas.default.pendingActions();) since we want to execute all the default pending actions.
• To invoke the new customPendingAction function, we do it through custom (dlms_gas.custom.customPendingAction();), which is the object containing the new behavior.

To learn about the existing functions and properties defined for the behaviors, see the specifications for each of them in the following sections.

dlms_gas api specification

The dlms_gas object is the main entry point for Smart Gas operations.

It has several properties used to keep session status. See dlm_gas properties section and it also has some main basic functions. See dlm_gas functions section.

Finally it has complex properties to specifiy Connector Functions behavior:

• dlms_gas.config object with configuration properties loaded from device entity and configuration entity.
• dlms_gas.behavior object with functions and properties to manage code execution.
• dlms_gas.actions object with pending actions configuration properties
• dlms_gas.default object with default properties and functions
• dlms_gas.pietro object with pietro specific properties and functions
• dlms_gas.honeywell object with honeywell specific properties and functions
• dlms_gas.spark object with spark specific properties and functions
• dlms_gas.watertech object with watertech specific propertiesand functions

dlms_gas properties

Following properties represent session state.

dlms_gas functions

dlms_gas.init(confEntityName)

Initializes the DLMS Gas API context. It loads provisioned and collected data from meter entity and provisioned configuration data from configuratiion entity if it is found. By default it uses the meter’s organization name to find created configuration entity, if it was created with different name it must be passed as argument.

See dlms_gas.config for more information about configuration data.

Examples:

dlms_gas.init();

dlms_gas.init(entity._value("provision.administration.organiaztion)+"_dev");

dlms_gas.decode(customTemplate, descriptive)

Decodes received payload after identifying the template and collects data. Internally it calls to behavior specific decode method. See DLMS Manufacturer Behavior section below for full specification of that method.

Example:

var res = dlms_gas.decode();

dlms_gas.pendingActions()

Executes the full session flow. Internally it calls to behavior specific pendingActions method. See DLMS Manufacturer Behavior section below for full specification of that method.

By default it executes the following actions:

1. sync clock: check and sync device clock
2. retrieve initial data: used to retrieve data that is expected only once on device onboarding like firmware, apn configuration, etc. This data will be asked if it is not collected already.
3. retrieve push events configurations: like initial data retrieving but for push events configurations, it will be asked if it is not collected already.
4. periodic actions: used to retrieve data that must be retrieved periodically like statistics.
5. automatic actions: used to retrieve data depending on previously collected data and received data in push notification.
6. opengate operations: used to execute operations requested from opengate.

Previous actions execution can be controlled by dlms_gas.actions object properties. If the action is not enabled, it will not be executed. If it is forced it will ignore previous checks like statistics age or if initial data was already collected.

Examples:

//standard behavior
dlms_gas.pendingActions();

//skip statistics and force push events configuration retrieval
dlms_gas.actions.retrieveStatistics = false;
dlms_gas.actions.retrievePushEventsConfigurations = true;
dlms_gas.actions.forcePushConf = true;
dlms_gas.pendingActions();

dlms_gas.collect()

Used at the end of the script to send collected data for meter entity, cell enity and organization entity. Internally it calls to specific behavior collect method.

Example:

dlms_gas.collect();

dlms_gas.customBehavior(behavior)

Changes the default behavior to a custom one. Internall it set dlms_gas.behaviorName property to "custom" and dlms_gas.custom property with the behavior provided as argument.

See DLMS Manufacturer Behavior section below for full specification of this method.

Example:

const customBehavior = {/*behavior specification*/};
dlms_gas.customBehavior(customBehavior);

dlms_gas._exec(callType, dType, uType)

It executes specified standard dlms call (get, set, method). It will use the dType and uType for msRaw collection. It will return an object with the result from dlms standard function or with the error message. This method is just utility and is not intended to be used directly. Instead it must be used dlms_gas.get, dlms_gas.set, dlms_gas.method or dlms_gas.getByRange.

Internally this method will do several actions:

• Call collectMsRaw before and after the dlms standard function call.
• Increase dlms_gas.messagesCounter property before the dlms call.
• Increase and collect onlineMngFrmCntr if the dlms call was successful.
• At the end, cleans dlms.attrList and dlms.methodList arrays.

Returned object will contain an object with the following properties:

• error: Error message if some error occurs.
• result: Return result from dlms standard function call. The result depends on the dlms method called (get, set, method).

dlms_gas.get(dType, uType)

It wrapes dlms.get calls adding extra behavior. dType and uType will be used for msRaw collection. The dlms.get response will be flattened in order to store the values in a single object. See examples below.

Returned object will contain.

object with the following properties:

• error: Error message if some error occurs.
• [classid_obis_attrid]: Values for the requested attributes, if attribute request was successful.

Example:

dlms.addAttr(1, '0.0.94.39.58.255', 2);
dlms.addAttr(45, '0.1.25.4.0.255', 2);
dlms.addAttr(3, '0.0.96.6.6.255', 2);
const res = dlms_gas.get(-8, 4);

Some return examples:

{
  "1_0.94.39.58.255_2": ...returned value from dlms.get... ,
  "45_0.1.25.4.0.255_2": ...returned value from dlms.get... ,
  "3_0.96.6.6.255_2": ...returned value from dlms.get...
}

If some attribute request fails, the error will be added to the error property.

{
  "error": "...errors specification separated by ';'",
  "1_0.0.94.39.58.255_2": ...returned value from dlms.get...
}

If the dlms.get request fails, the error property will be set and no attribute values will be returned.

{
  "error": "... error message ..."
}

dlms_gas.set(dType, uType)

It wrapes dlms.set calls adding extra behavior. dType and uType will be used for msRaw collection. The dlms.set response will be flattened in order to store the values in a single object. See examples below.

Returned object will contain an object with the following properties:

• error: Error message if some error occurs.
• [classid_obis_attrid]: Results for the modified attributes.

Example:

dlms.addAttr(22, '0.0.15.0.1.255', 2, 'structure', [{ 'type': 'octet-string', 'value': [0, 0, 10, 0, 106, -1] }, { 'type': 'long-unsigned', 'value': vst }]);
dlms.addAttr(22, '0.0.15.0.1.255', 4, 'array', [{ 'type': 'structure', 'value': [{ 'type': 'octet-string', 'value': timeOctet }, { 'type': 'octet-string', 'value': dateOctet }] }]);
const dlmsResp = dlms_gas.set(-13, 6);

Some return examples:

{
  "22_0.0.15.0.1.255_2": "success",
  "22_0.0.15.0.1.255_4": "success"
}

If some attribute modification returns an error, the error will be added to the error property and the response will be “success” for the rest of the attributes.

{
  "error": "...errors specification...",
  "22_0.0.15.0.1.255_2": "error message",
  "22_0.0.15.0.1.255_4": "success"
}

If the dlms.set request fails, the error property will be set and no attribute values will be returned.

{
  "error": "... error message ..."
}

dlms_gas.method(dType, uType)

It wrapes dlms.method calls adding extra behavior. dType and uType will be used for msRaw collection. The dlms.method response will be flattened in order to store the values in a single object. See examples below.

Returned object will contain.

object with the following properties:

• error: Error message if some error occurs.
• [classid_obis_attrid]: Results for the modified attributes, if attribute modification was successful.

Example:

dlms.addMethod(3, '7.0.96.5.1.255', 1, 'integer', 0);
const dlmsResp = dlms_gas.method(-18, 18);

Some return examples:

{
  "3_7.0.96.5.1.255_1": "success"
}

If some method execution returns an error, the error will be added to the error property and the response will be “success” for the rest of the attributes.

{
  "error": "...errors specification...",
  "3_7.0.96.5.1.255_1": "error message"
}

If the dlms.method request fails, the error property will be set and no attribute values will be returned.

{
  "error": "... error message ..."
}

dlms_gas.getByRange(classId, obis, attrId, accessSelector, paramClassID, paramObis, paramAttrId, rangeType, rangeFrom, rangeTo, maxRangePerPage, dType, uType)

It retrieves values by range using dlms.get with selective access. It retrieves all the values within the range, even if the device returns values in multiple pages. In case of any page retrieval fails, the error will be added to the error property and the response will be “success” for the rest of the pages.

It returns an object with the following properties:

• result: Array of all values retrieved.
• error: Error message if any error occurs.

Example:

const res = dlms_gas.getByRange(7, '0.0.99.1.0.255', 2, 1, 8, '0.0.1.0.0.255', 2, 'double-long-unsigned', lastIndex, currentIndex, 10, -8, 4);

dlms_gas.config Object Properties

Following properties are loaded from device entity and from “configuration entity” when executing dlms_gas.init method. Some of them contain connected meter status and data and other contain configuration values from configuration entity.

Next table indicates which datastreams are used to init these properties:

It is possible to override this values after init calling to dlms_gas.init():

dlms_gas.init();
dlms_gas.config.maxClockSkewAllowedSec = 60;

dlms_gas.config Object Functions

config.__initApiKey(apiKey)

Internal utility used to initialize the API key.

If it is necessary to specify manually the apikey from Connector Function it must be called after dlms_gas.init call. Example:

dlms_gas.init();
dlms_gas.config.__initApiKey('your-api-key');

dlms_gas.behavior Object properties

dlms_gas.behavior Object Functions

behavior.getName(manufacturer)

Calculates and returns behavior name from manufacturer parameter (Not case session). This method is called from dlms_gas.init function only if dlms_gas.behaviorName is null.

Next table explains current behaviors:

behavior.calculateChain(behaviorName, visited)

Internall utility to calculate recursively the behavior chain. It is called from dlms_gas.init and it will return a Set with all behaviors to be checked when a function or property is called. It will take into account that specified behavior exists, if not it will return default behavior as last element of the chain. Something similiar will happen if there is a circular baseBehavior reference.

For example, if custom behavior is defined with pietro as baseBehavior:

const chain = dlms_gas.behavior.calculateChain('custom');
//it will return following chain: ['custom', 'pietro', 'default']

In case that custom behavior has invalid baseBehavior (it doesn’t exist), it will return following chain:

//having custom behavior with invalid baseBehavior, for example 'nonExistentBehavior'
const chain = dlms_gas.behavior.calculateChain('custom');
//it will return following chain: ['custom', 'default']

behavior.property(propertyName)

Returns property value from behavior chain in order to call it. It will return the property value if exists in any behavior in the chain, if not it will return null.

behavior.function(functionName)

Returns function from behavior chain in order to call it. It will return the function if exists in any behavior in the chain, if not it will empty function.

Example of function calling using behavior management:

    const address = dlms_gas.behavior.function("encodeIpPort")(pConf.platform.ip, pConf.platform.port);

Example of bad use of function method and how to override correctly the function:

const cb = {
  "retrieveStatistics": function(data){
    dlms_gas.behavior.function('retrieveStatistics')(); //Bad practice: Infinite recursion
    dlms_gas.default.retrieveStatistics(); //the correct way to do it
    dlms_gas.honeywell.retrieveStatistics(); //the correct way to do it
    //... extra code ...
  }
}

dlms_gas.actions Object Properties

Control flags to enable or disable specific automated tasks.

dlms_gas.default object Properties

Following properties are defined in dlms_gas.default and used when no manufacturer specific property is defined.

Range retrieval configuration object

To simplify metrological events, non-metrological events, daily profiles and hourly profiles retrieval customization following object is used to define range selection parameters. It is used internally when calling getByRange function.

Next are default configurations for specified retrievals:

{
    "metEventsRangeSelection": {
      "classId": 7,
      "obis": '7.0.99.98.1.255',
      "attrId": 2,
      "accessSelector": 1,
      "paramClassID": 1,
      "paramObis": [0, 0, 96, 15, 1, -1],
      "paramAttrId": 2,
      "rangeType": "long-unsigned",
      "maxRangePerPage": 7
    },
    "nonMetEventsRangeSelection": {
      "classId": 7,
      "obis": '7.0.99.98.0.255',
      "attrId": 2,
      "accessSelector": 1,
      "paramClassID": 1,
      "paramObis": [0, 0, 96, 15, 2, -1],
      "paramAttrId": 2,
      "rangeType": "long-unsigned",
      "maxRangePerPage": 8
    },
    "dailyProfilesRangeSelection": {
      "classId": 7,
      "obis": '7.0.99.99.3.255',
      "attrId": 2,
      "accessSelector": 1,
      "paramClassID": 1,
      "paramObis": [0, 0, 1, 1, 0, -1],
      "paramAttrId": 2,
      "rangeType": "double-long-unsigned",
      "maxRangePerPage": 10 * 24 * 3600
    },
    "hourlyRangeSelection": {
      "classId": 7,
      "obis": '7.0.99.99.2.255',
      "attrId": 2,
      "accessSelector": 1,
      "paramClassID": 1,
      "paramObis": [0, 0, 1, 1, 0, -1],
      "paramAttrId": 2,
      "rangeType": "double-long-unsigned",
      "maxRangePerPage": 20 * 3600
    }
}

Operations specification

supportedOps is used to specify Opengate operations execution. This property is an array of objects that contains operation name and function to be called. Operations will be executed following the order they are defined in the array.

Default value:

{
    "supportedOps":
      [{
        "name": "ValveManagement",
        "funcName": "valveManagement"
      }, {
        "name": "ResetDiagnostic",
        "funcName": "resetDiagnostic"
      }, {
        "name": "RequestNonMetroLogs",
        "funcName": "requestNonMetroLogs"
      }, {
        "name": "HourlyValues",
        "funcName": "hourlyValues"
      }, {
        "name": "CommsBatStatus",
        "funcName": "commsBatStatus"
      }, {
        "name": "APNConfig",
        "funcName": "apnConfig"
      }, {
        "name": "PushStrategy",
        "funcName": "pushStrategy"
      }, {
        "name": "FOTA",
        "funcName": "fota"
      }]
}

On one hand it is possible to specify custom array with custom functions. On the other hand it is possible just to override specified function (for example "valveManagement" function) just to customize specific operation behavior.

dlms_gas.default object Functions

default.apnConfig(op)

Apn configuration operation logic. Configures the SIM APN and PLMN code on the device and processes the operation response.

default.automaticActions()

Orchestrates automatic data retrieval functions. These functions retrieve data from the device depending on last collected data and new received data. Following functions are called in order:

• retrieveMetrologicalEvents
• retrieveDailyProfiles

default.closeConnection()

Called at then end of pendingActions function. In this case (default behavior) it is empty.

default.collect()

Sends the gathered datapoints for the device, cell, and organizational unit. It takes into account if dls_gas.devCollection, dls_gas.cellCollection or dls_gas.uoCollection are defined and they have identifier field is defined.

default.collectBillingPeriodSnapshotData(billingPeriodData)

Collects the billing period data snapshot. Receives an with the values of decoded billing period snapshot:

default.collectDiagnostic(diagnostic, at, source, sourceInfo)

Decodes a 16-bit diagnostic value into individual status flags that are collected with specified at, source and sourceInfo.

default.collectHourlyDiagnostics(diagnosticsArray, unixTime)

Collects an array of hourly diagnostics values with at time as reference.

default.collectHourlyVolumes(incsArray, at)

Collects an array of hourly volume increments with at time as reference.

default.collectMsRaw(mType, payload, payloadSize)

Internal utility to collect raw messages. It adds msRaw datapoint to device, cell and organizational unit collections. Datapoint is composed by provided arguments.

Examples:

// For received compact frame
dlms_gas.manufacturer.function("collectMsRaw")(contextParams.templateId, utils.bytes.toHexString(payload.value), payload.value.length);
// For dlms request sent to device
dlms_gas.manufacturer.function("collectMsRaw")(-22);
// For dlms response received from device
dlms_gas.manufacturer.function("collectMsRaw")(22);

default.collectNetworkStatus(networkStatus, at)

Decodes an 8-bit network status integer value into individual flags and adds it to the device collection.

default.collectTarifPlan(tariffPlann, at)

Transforms and collects received array of two numbers into an array of two bytes hexadecimal string.

default.collectDailyLoadProfilesArray(loadProfiles, source, sourceInfo)

Collects from received daily profiles with specified source and sourceInfo. Each element of array must be an object with the following fields:

Each element of the array is an array with 4 elements:

default.commsBatStatus(op)

Comms bat status retrieval operation logic. Retrieves battery status and communication statistics from the device and processes the operation response.

default.configClient()

Initializes the dlms client parameters for sending requests to the device. This method is called from dlms_gas.init function.

default.createCellIfNecessary()

Automatically provisions a new NBIoT Cell entity in Opengate if it doesn’t exist. It uses NBcellID as entity name.

default.dateToDateOctet(date)

Converts a JavaScript Date object into DLMS octet-string format for date (5 bytes).

Returns an object with following fields:

Example:

const date = new Date("2026-04-23T05:30:00.000Z");
const dateOctet = dlms_gas.manufacturer.function("dateToDateOctet")(date);
// Example: dateOctet = { result: [ 7, 234, 4, 23, 4 ] }

default.dateToTimeOctet(date)

Converts a JavaScript Date object into DLMS octet-string format for time (4 bytes).

Returns an object with following fields:

Example:

const date = new Date("2026-04-23T05:30:00.000Z");
const dateOctet = dlms_gas.manufacturer.function("dateToTimeOctet")(date);
// Example: dateOctet = { result: [ 5, 30, 0, 0 ] }

default.decode(customTemplate, descriptive)

The main entry point for Compact Frame decoding. It identifies the correct template based on the templateId in the context (or it uses the provided customTemplate), performs the decoding, and triggers the collection logic.

If customTemplate is provided, it is used to decode the compact frame, otherwise predefined templates will be used.

For compact frame decoding see dlms api documentation .

Returns an object with following fields:

const decodedData = dlms_gas.manufacturer.function("decode")();
// Correct result: decodedData = { result: [22, 225, 37, 203, 0, 15, 225, 233, 128, 255, 123, 32, 241, 71, 57, 187, 177, 79, 2, 48] }
// some error case: decodedData = { error: "error description" }

default.decodeFw(fwBytes)

Decodes a 6-byte array into a descriptive firmware version string including version numbers, build commit (hex), and date.

Returned version will be something like this: Version:${major}.${minor}.${patch};Build:0x${commitField.toString(16).toUpperCase().padStart(4, "0")};Fecha:${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}

Returns an object with following fields:

const fwBytes = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06];
const fwVersion = dlms_gas.manufacturer.function("decodeFw")(fwBytes);
// Example: fwVersion = { result: "Version:1.2.3;Build:0x4506;Fecha:2026-04-23" }

default.doPushEventConfiguration(event, conf)

Internal function that executes the actual DLMS set operations to apply push event configurations.

conf object has the following properties:

schedule is an array of four objects. Each object has the following properties:

default.encodeIpPort(ip, port)

Encodes an IP address and port into a 22-byte octet-string for push configuration.

Returns an byte array

Example:

const ip = "127.0.0.1";
const port = 8080;
const ipPort = dlms_gas.manufacturer.function("encodeIpPort")(ip, port);
// Example: ipPort = [ 49, 50, 55, 46, 48, 46, 48, 46, 49, 58, 56, 48, 56, 48];

default.eventScheduleArray(scheduleData)

Event DLMS schedule array generation logic. Generates the event schedule array for push events configuration. Adds the 4 events with corresponding periodicity and hour specification including disabled events.

Returns an array of objects with date and time octet. Example:

[
  {
    "dateOctet": "[-1, -1, -1, 3, -40]",
    "timeOctet": "[0, 5, 0, 0]"
  },
  {
    "dateOctet": "[-1, -1, -1, 3, -40]",
    "timeOctet": "[3, 5, 0, 0]"
  },
  {
    "dateOctet": "[-1, -1, -1, -1, -1]",
    "timeOctet": "[-1, -1, -1, -1]"
  },
  {
    "dateOctet": "[-1, -1, -1, -1, -1]",
    "timeOctet": "[-1, -1, -1, -1]"
  }
]

default.fota(op)

FOTA configuration operation logic. It manages specific scheduling, fota process initialization, blocks transfers by sessions and different process status management. It manage the operation status allong all the process.

default.fotaAdjustBlocks(imageTransferBlocksMap, expectedNumberOfBlocks)

Recalculates and returns blocks map according to the expectedNumberOfBlocks calculated at the FOTA operation beginig. If received array shorter than expected it is filled with false values. If it is larger, it is truncated to the expected number of blocks.

Returns an array with the adjusted blocks status map.

default.fotaBlocksTransfer(op, blocksStatusMap)

Orchestrates the transmission of multiple firmware blocks in a single session, respecting the maximum messages allowed for the current ECL. It manages specially first and last block sent to update operation status. It also manages errors per session.

default.fotaBlockTransfer(blockIndex, bundleName, bundleVersion, deploymentName, deploymentVersion)

Executes the actual transmission of a single firmware block calling dlms.sendFotaPage method. It increase success and error counters.

default.fotaCalculateIdentifier(op)

Calculates the unique image identifier based on KDL, hashtag, and activation date. It adds at the beginning of the identifier follwing bytes 014D.

Returns an object with following properties:

Example:

{
  "result": "[1, 77, 14, 50, 145, 16, 132, 16, 233, 67, 18, 99, 235, 189,...]"
}

default.fotaCheckAllowed(op)

Verifies if the device is correctly configured for FOTA (valid block size and FOTA enabled). It updates operation status according to the validation.

default.fotaCheckBadSessions()

Aborts the FOTA process if the number of consecutive bad sessions reaches the maximum allowed threshold and throws an error. It uses badSessionsCounter and maxBadSessions from dlms_gas.config.

default.fotaCheckSessionBlocksErrors()

Just checks session errors rate and updates bad sessions counter.

default.fotaContinueProcess(op)

Internal function used to continue FOTA operation from different sessions: it manage different process status, sends blocks and finalizes operation according to final status (including device default scheduling).

It updates operation status using op parameter.

default.fotaImgActivate(op)

Function intended to invoke image activation DLMS method, but actually is empty function in default behavior. It can be implemented in specific behaviors.

default.fotaImgVerify(op)

Function intended to invoke image verification DLMS method, but actually is empty function in default behavior. It can be implemented in specific behaviors.

default.fotaImgTransferInitiate(op)

Invokes image transfer process initiation DLMS method and calculates the total number of blocks based on the firmware size and configured block size. It updates operation status.

default.fotaRestoreDefaultSchedule(op)

Restores the default push strategy schedule after the FOTA process is finished or cancelled. It updates operation status.

default.fotaScheduleForFota(op)

Temporary updates the push strategy schedule to a more aggressive frequency (every hour) during the FOTA process to speed up block transmission. It updates operation status.

default.fotaStartProcess(op)

Internal function used to complete first steps of FOTA operation: device status validation, device special scheduling and fota process initialization in the meter.

It updates operation status using op parameter.

default.fotaStateFromCf22(op)

It retrieves CF22 and updates session data to continue with FOTA proess.

It returns an object with transfer status and transfered blocks map. Example:

{
  "transferStatus": 1,
  "blocksMap": "[true, true, false, false]"
}

default.fotaStatus0(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 0. Actually it calls fotaStatusUnknown function because this function is not supposed to be executed.

default.fotaStatus1(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 1. Try to send pending blocks or call image verification function.

default.fotaStatus2(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 2. In default behavior it does nothing.

default.fotaStatus3(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 3. It just calls to fotaImgActivate function.

default.fotaStatus4(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 4. It finishes the FOTA process with image verification error.

default.fotaStatus5(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 5. In default behavior it does nothing.

default.fotaStatus6(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 6. Asks to device for new firmware data, restores default scheduling and finlizes FOTA operation.

default.fotaStatus7(op, fotaState)

Executed when the devices Compact Frame 22 retrieve status 7. It finishes the FOTA process with image activation error.

default.fotaStatusUnknown(op, fotaState)

Executed when the devices Compact Frame 22 retrieve an unexpected status. In default behavior it just incresaes bad sessions counter.

default.fotaUpdateLostSteps(fotaState, op)

Function that depending on fotaState (process status and blocks maps) updates operation lost steps.

default.fotaUpdateSuccessBlocksFromDevice(imageTransferBlocksMap)

Updates the internal block transmission counter based on the blocks retrieved form CF 22.

default.getHourlyArrayWithAt(hourlyArray, refTime)

From an array with hourly data (volumes, diagnostics…) and with refTime as reference, build an array with the at time of each increment.

Returns an array with following objects:

[
  {
    "value": "120",
    "at": "1783051200"
  },
  {
    "value": "125",
    "at": "1783054800"
  },
  {
    "value": "150",
    "at": "1783058400"
  },
  {
    "value": "200",
    "at": "1783062000"
  }
  ....
]

default.getPeriodictyOctet(period, time)

Returns the DLMS date octet-string representing the periodicity for push event schedulation. It takes into account both period and time.

These are codification rules for periodicity:

If invalid periodicty is used, an exception will be thrown.

default.getTimeOctet(period, time)

Returns the DLMS time octet for push event schedulation. It takes into account both period and time.

default.getStepByName(op, stepName, checkInCurrentResponse)

Search in passed operation object if the step is already completed. If checkInCurrentResponse is not specified, it will check only in steps completed in the operation. If checkInCurrentResponse is specified and it is true, it will check also in the steps added in current execution.

default.hourlyValues(op)

Horly values retrieval operation logic. Retrieves hourly incremental volume values from the device by range and processes the operation response.

default.initAndCollectCf47(data)

Function called from dlms_gas.decode after decoding 47 compact frame from received notification. Initialize parameters to be used later and collects received fields.

default.initAndCollectCf48(data)

Function called from dlms_gas.decode after decoding 48 compact frame from received notification. Initialize parameters to be used later and collects received fields.

default.initAndCollectCf49(data)

Function called from dlms_gas.decode after decoding 49 compact frame from received notification. Initialize parameters to be used later and collects received fields.

default.initAndCollectCf51(data)

Function called from dlms_gas.decode after decoding 51 compact frame from received notification. Initialize parameters to be used later and collects received fields.

default.initAndCollectCf97(data)

Function called from dlms_gas.decode() after decoding 97 compact frame from received notification. Initialize parameters to be used later and collects received fields.

default.operations()

Dispatches and executes active operations from the Opengate platform. Retrieves all alive operations for the device using Operations JS Api. It iterates through supportedOps and executes the process for any matching active operation.

default.pendingActions()

The main entry point for a standard communication session. It orchestrates the actions to be performed in a session. It uses dlms_gas.actions object to determine which actions to perform.

The order of actions are:

• Set Clock
• Retrieve Initial Data
• Retrieve Push Events Configurations
• Periodic Actions
• Automatic Actions
• Operations

default.periodicActions()

Orchestrates periodic data retrieval functions. These functions retrieve data from the device periodically:

• retrieveStatistics

default.pushStrategy(op)

Push configuration operation logic. Configures the push communication strategy (Compact Frame selection, platform address/port, and scheduling) for the four supported push events and process the operation response.

default.requestNonMetroLogs(op)

Non metrological logs retrieval operation logic. Retrieves non-metrological event logs from the device by range and processes the operation response.

default.resetDiagnostic(op)

Reset diagnostic operation logic. Resets the device’s diagnostic status flags by executing the corresponding DLMS method and process the operation response.

default.restoreOnlineFrameCounter()

This method is used when received compact frame does not contain onlineFrameCounter and it is necessary to request it to the device in order to set correct values for next requests.

In uses previously collected online onlineFrameCounter to initilialize the client’s online frame counter and then it requests the device to retrieve its actual value. If the device does not response it tries again increasing used frames counter with the value specified in onlineFramCounterRetryInc property. It will try to request onlineFrameCounter to the device up to onlineFramCounterRetryMax times.

default.retrieveDailyProfiles()

If the device does not communicate in last days it will ask for all missing daily profiles.

default.retrieveInitialData(force)

Retrieves one-time device information. It will check if device.software datastream is not collected or force parameter is true. If so it will retrieve following data:

• Metrological and Non-metrological Firmware versions.
• APN configuration.
• FOTA block configuration.

default.retrieveMetrologicalEvents()

Retrieves missing metrological events from the device by range, starting from the last collected counter.

default.retrievePushEventsConfigurations(force)

Retrieves configuration for all push events (1-4) configuration. It will check for each event if confCFx datastream is not collected or force parameter is true. If so it will retrieve push event configuration.

default.retrieveStatistics(force)

Retrieves periodically communication statistics (Signal Power, RSRQ, RSRP, ECL, Battery remaining time….). It will check statisticsRefDs datastreams at value and if the data is too old (using periodicDataAgeMillis as reference). Statistics retrieval can be forced using force parameter.

default.rsrqFromRaw(raw)

Returns converted raw RSRQ to dB/dBm following standard dlms specfication.

default.rsrpFromRaw(raw)

Returns converted raw RSRQ to dB/dBm following standard dlms specfication.

default.setClock()

Checks drift and synchronizes device time.

default.signalQualityFromRaw(raw)

Converts raw CSQ value to dBm following DLMS specification.

default.strategy(b1, b0)

Decodes the communication strategy from two bits.

Return a string with composed strategy.

default.tauInSecondsFromRaw(raw)

Decodes TAU timer to seconds following DLMS specification.

Example:

var s = dlms_gas.manufacturer.function("tauInSecondsFromRaw")(0x21);

default.tmrInSecondsFromRaw(raw)

Decodes raw TMR to seconds following dlms specfication.

default.valveManagement(op)

Valve managment operation logic. Executes valve Open/Close commands and process the operation response.

dlms_gas.pietro object Properties

There are no specific properties for dlms_gas.pietro.

dlms_gas.pietro object Functions

pietro.decodeFw(fwBytes)

Specific firmware decoding for Pietro devices. It returns a simplified version string.

dlms_gas.honeywell object Properties

dlms_gas.honeywell object Functions

honeywell.closeConnection()

Graceful disconnect via DLMS method specific for Honeywell devices.

honeywell.retrieveStatistics(force)

Specific statistics retrieval for Honeywell devices, excluding some attributes not supported by these devices.

honeywell.tauInSecondsFromRaw(raw)

Overrides the default TAU conversion to return directlty the raw value.

honeywell.tmrInSecondsFromRaw(raw)

Overrides the default TMR conversion to return directlty the raw value.

honeywell.eventScheduleArray(scheduleData)

Event DLMS schedule array generation logic. Generates the event schedule array for push events configuration. Adds just the events not disabledwith corresponding periodicity and hour specification.

Returns an array of objects with date and time octet. Example:

[
  {
    "dateOctet": "[-1, -1, -1, 3, -40]",
    "timeOctet": "[0, 5, 0, 0]"
  },
  {
    "dateOctet": "[-1, -1, -1, 3, -40]",
    "timeOctet": "[3, 5, 0, 0]"
  }
]

dlms_gas.spark object Properties

dlms_gas.spark object Functions

spark.fotaImgVerify(op)

Invokes FOTA image verify DLMS method. It updates the operation status accordingly to the response

spark.fotaCalculateIdentifier(op)

Calculates the unique image identifier based on KDL, hashtag, and activation date.

Returns an object with following properties:

Example:

{
  "result": "[14, 50, 145, 16, 132, 16, 233, 67, 18, 99, 235, 189,...]"
}

dlms_gas.watertech object Properties

dlms_gas.watertech object Functions

There are no specific properties for dlms_gas.watertech.