Connector functions HTTP JS API guide

This API allows users to execute HTTP related actions from a connector function.

HTTP Object

The http object is the main object of the HTTP client. It allows perform different actions such as do http request or define http response for Operation Response or Iot Collections requests through http protocol.

http object is divided in two objects:

• server: Only for CFs called from http requests. Gives access to received request and allows to specify http response to be sent.
• client: Configure and make http requests.

server Object Properties

Read only properties with received HTTP request and response object to define HTTP response to be sent.

server.response Object Properties

server.response Object Methods

server.response.send()

Creates HTTP Response with defined properties. The response will be sent once the CF is finished correctly.

Example:

http.server.response.status=200;
http.server.response.body={'msg': 'OK'};
http.server.response.send();
//continue CF execution
return collection;

In this case, after CF execution, the Http response to be generated will have 200 status code with specified body ({'msg': 'OK'}) and no specific headers.

client Object Properties

client Object Methods

Following methods return Http Request result JSON with these fields:

client.post()

Performs POST using defined configuration. Overrides defined method.

Example of use with default values:

http.client.uri = "https://remotehost/uri";
http.client.headers = {'X-Api-Key':'apikey'};
http.client.body = {'operation_name':'custom_operation_request'};
var httpResp = http.client.post();

client.put()

Performs PUT using defined configuration. Overrides defined method.

Example of use with default values:

http.client.uri = "https://remotehost/uri";
http.client.headers = {'X-Api-Key':'apikey'};
http.client.body = {'operation_name':'custom_operation_request'};
var httpResp = http.client.put();

client.get()

Performs GET using defined configuration. Overrides defined method.

Example of use with default values:

http.client.uri = "https://remotehost/uri";
http.client.headers = {'X-Api-Key':'apikey'};
var httpResp = http.client.get();

client.delete()

Performs DELETE using defined configuration. Overrides defined method.

Example of use with default values:

http.client.uri = "https://remotehost/uri";
http.client.headers = {'X-Api-Key':'apikey'};
var httpResp = http.client.delete();

client.patch()

Performs PATCH using defined configuration. Overrides defined method.

Example of use with default values:

http.client.uri = "https://remotehost/uri";
http.client.headers = {'X-Api-Key':'apikey'};
http.client.body = {'operation_name':'custom_operation_request'};
var httpResp = http.client.patch();

client.request()

Performs configured http request. method property must be defined.

Example of use with default values:

http.client.method = "GET";
http.client.uri = "https://remotehost/uri";
http.client.headers = {'X-Api-Key':'apikey'};
http.client.body = {'operation_name':'custom_operation_request'};
var httpResp = http.client.request();

Connector functions MQTT JS API guide

This API allows users to execute operations in the MQTT client from a connector function.

MQTT Object

The mqtt object is the main object of the MQTT client. It allows publishing messages to an MQTT topic.

mqtt Object Properties

mqtt Object Methods

mqtt.publish(payload)

Publish a message on mqtt topic

Example of use with default values:

mqtt.publish({'operation_name':'custom_operation_request'});

Example of use with overriden values

mqtt.device='other_device';
mqtt.topic = 'destination/topic';
mqtt.publish('Message to be sent');

Connector functions websocket JS API guide

This API allows users to send message to opened websocket.

Websocket Object Properties

Websocket Object Methods

websocket.sendMsg()

Executes specified request using the properties of the websocket object

Returns: Object

Example of use:

websocket.payload = {someField:someValue};
websocket.deviceId = 'someDeviceId'
websocket.sendMsg();

Connector functions JS API guide for the CoAP protocol

This file provides methods and properties to specify a custom return code and a custom body in the CoAP response that is sent from the OpenGate platform to the device.

coap.server.response Object: Specifying a custom CoAP response to the device.

The coap.server.response global object provides all the necessary functionality to be able to specify both the state and the body of the CoAP response to return to the device.

coap.server.response Object Properties

coap.server.response Object Methods

coap.server.response.send()

The status, body and contentFormat are saved for inclusion in the CoAP response.

Example of use

// sending CHANGED status (2.04), and a number 1 as body (two bytes unsigned integer - little endian)
coap.server.response.status = 204; 
coap.server.response.body = new Uint8Array([01, 00]); 
coap.server.response.send();

Connector functions DLMS JS API guide

This JavaScript code provides predefined functions to execute DLMS requests from the connector function. They are explained below.

Types of south criteria for your DLMS connector function:

Input parameters in Collection Connector Function

The main script will have access to three main vars:

• entity: json with flattened operation target device entity representation.
• gateway: json with flattened gateway entity representation. It can be null.
• payload: json that represents the DLMS message received from the device.
• contextParams: json object with execution context information. It can have some of this params:
  • apiKey: device or user apikey.
  • remoteIp: remote host where DLMS message is invoked.
  • obisCode: OBIS code of the message arrived.
  • templateId: Template identifier of the message arrived.

ContextParams for COLLECTION Connector function for DLMS connection:

{
  "apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
  "obisCode": "0.1.2.3.3.5",
}

Here is a payload example:

payload = [
	{
	    "obisCode": "0.0.49.0.75.254",
	    "attrId": 2,
	    "classId": 1,
	    "type": "octet-string",
	    "value": [2, 3, 215, 0]
	},
	{
	    "obisCode": "0.0.49.0.77.254",
	    "attrId": 4,
	    "classId": 1,
	    "type": "unsigned",
	    "value": 1
	}
]

JS DLMS API

For REQUEST Connector Functions we will use the functions described below. You have an object, named dlms, with all the functions described. You must use dlms.<function>.

If you want to collect data after executing any of these function you can call collectCF and you can set various obis code in the URL provided as you can see in the next example:

collectCF(result.data, "dlms://obis/0.1.2.3.4.5");

dlms.connect()

Opens DLMS connection (default via TCP transport).

Kind: global function

The connection parameters need to be set before calling connect:

dlms.ip = "127.0.0.1"
dlms.connect()

Add attributes

addAttr() is used both for get() and set() methods and has multiple signatures:

dlms.addAttr(classId, obisCode, attrId)

Applicable for normal gets.

// After connection has been established
dlms.addAttr(1, "1.2.3.4.5.6", 2)
var getResult = dlms.get() // More details on get() next

dlms.addAttr(classId, obisCode, attrId, type, value)

Applicable for normal sets.

// After connection has been established
dlms.addAttr(1, "1.2.3.4.5.6", 2, "unsigned", 254)
var setResult = dlms.set() // More details on set next

dlms.addAttr(classId, obisCode, attrId, data)

Applicable for normal sets.

where:

This is an alternate way of using addAttr(classId, obisCode, attrId, type, value) with the data parameters in an object.

// After connection has been established
//dlms.addAttr(1, "1.2.3.4.5.6", 2, "unsigned", 254)
dlms.addAttr(1, "1.2.3.4.5.6", 2, {"type": "unsigned", "value": 254}) // This is similar to the previous addAttr (commented)
var setResult = dlms.set() // More details on set next

It’s helpful when used in combination with get().

// After connection has been established
dlms.addAttr(1, "1.2.3.4.5.6", 2)
var getResult = dlms.get() // More details on get next
dlms.addAttr(1, "1.2.3.4.5.255", 2, getResult[0]) // Set on object 1.2.3.4.5.255 the value (and data type) retrieved from object 1.2.3.4.5.6
var setResult = dlms.set() // More details on set next

dlms.addAttr(classId, obisCode, attrId, selectiveAccess)

Applicable for gets with selective access.

where:

and

dlms.addAttr(1, "1.2.3.4.5.6", 2, {"accessSelector": 1, "accessParameters": {"type": "unsigned", "value": 254}})

// Example by range
dlms.addAttr(7, '7.0.99.99.3.255', 2, {
	accessSelector: 1,
	accessParameters: {
		type: 'structure',
		value: [{
			type: 'structure',
			value: [{
				type: 'long-unsigned',
				value: 1
			}, {
				type: 'octet-string',
				value: [0, 0, 1, 1, 0, 255]
			}, {
				type: 'integer',
				value: 2
			}, {
				type: 'long-unsigned',
				value: 0
			}]
		}, {
			type: 'double-long-unsigned',
			value: 1735884000
		}, {
			type: 'double-long-unsigned',
			value: 1736229600
		}, {
			type: 'array',
			value: []
		}]
	}
})

dlms.addAttr(attribute)

Generic signature applicable for all cases.

where:

// For normal get
dlms.addAttr({classId: 1, obisCode: "1.2.3.4.5.6", attrId: 2})
// For normal set
dlms.addAttr({classId: 1, obisCode: "1.2.3.4.5.6", attrId: 2, type: "unsigned", value: 254})
// For get with selective access
dlms.addAttr({classId: 1, obisCode: "1.2.3.4.5.6", attrId: 2, accessSelector: 1, accessParameters: {type: "unsigned", value: 254}})

data types

dateTime objects

A dateTime object is used to specify all possible values for date-time, date and time DLMS types. It may define the following attributes:

To transform this object to a Date see getDate(). Keep in mind that sets of date-time, date, time and octet-string do not accept a Date object. To transform it to a dateTime object use getDateTime().

dlms.get(descriptive, forceWithoutList)

Executes a multi DLMS get attribute request with the previously specified payload (addAttr(classId, obisCode, attrId)).

Kind: global function
Returns: Array - Array of JSONs with responses. Each JSON will have six fields: result of the get operation, the requested classId, obisCode and attrId, type with the data type of the received value and the value received from the device. An optional error field may be returned for any error that happened during the get.

Example for descriptive get:

// After connection has been established
dlms.addAttr(1, "0.0.0.0.0.0", 2) // Example for null-data
dlms.addAttr(1, "0.0.0.0.0.1", 2) // Example for array
dlms.addAttr(1, "0.0.0.0.0.2", 2) // Example for structure
dlms.addAttr(1, "0.0.0.0.0.3", 2) // Example for boolean
dlms.addAttr(1, "0.0.0.0.0.4", 2) // Example for bit-string
dlms.addAttr(1, "0.0.0.0.0.5", 2) // Example for double-long
// Rest on number examples are omitted because they are similar to double-long
dlms.addAttr(1, "0.0.0.0.0.6", 2) // Example for octet-string
dlms.addAttr(1, "0.0.0.0.0.7", 2) // Example for visible-string
// utf8-string example is omitted because it's similar to visible-string

var result = dlms.get() // Descriptive (true can also be passed)
log(result[0]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.0","attrId":2,"type":"null-data","value":null}]
log(result[1]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.1","attrId":2,"type":"array","value":[{"type":"long-unsigned","value":1},{"type":"long-unsigned","value":2},{"type":"long-unsigned","value":3}]}
log(result[2]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.2","attrId":2,"type":"structure","value":[{"type":"unsigned","value":1},{"type":"long-unsigned","value":2},{"type":"array","value":[{"type":"visible-string","value":"one"},{"type":"visible-string","value":"two"}]}]}
log(result[3]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.3","attrId":2,"type":"boolean","value":true}
log(result[4]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.4","attrId":2,"type":"bit-string","value":[true,false,true]}
log(result[5]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.5","attrId":2,"type":"double-long","value":1}
log(result[6]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.6","attrId":2,"type":"octet-string","value":[116,101,115,116]}
log(result[7]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.7","attrId":2,"type":"visible-string","value":"test"}

Example for non descriptive get

// After connection has been established
// Simple value types are returned exactly the same as descriptive mode, null-data is included to viasually see this
dlms.addAttr(1, "0.0.0.0.0.0", 2) // Example for null-data
// Simple value types are returned exactly the same as descriptive mode, null-data is included to viasually see this
dlms.addAttr(1, "0.0.0.0.0.1", 2) // Example for array
dlms.addAttr(1, "0.0.0.0.0.2", 2) // Example for structure

var result = dlms.get(false) // Non descriptive
log(result[0]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.0","attrId":2,"type":"null-data","value":null}]
log(result[1]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.1","attrId":2,"type":"array","value":[1,2,3]}
log(result[2]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.2","attrId":2,"type":"structure","value":[1,2,["one","two"]]}

get results

• success
• hardware-fault
• temporary-failure
• read-write-denied
• object-undefined
• object-class-inconsistent
• object-unavailable
• type-unmatched
• scope-of-access-violated
• data-block-unavailable
• long-get-aborted
• no-long-get-in-progress
• long-set-aborted
• no-long-set-in-progress
• data-block-number-invalid
• other-reason

dlms.set(descriptive)

Executes a multi DLMS set attribute request with the previously specified payload (addAttr(classId, obisCode, attrId, type, value)).

Kind: global function
Returns: Array - Array of JSONs with responses. Each JSON will have six fields: result of the set operation, the requested classId, obisCode and attrId, type with the data type of the received value and the value received from the device. An optional error field may be returned for any error that happened during the set.

// After connection has been established
dlms.addAttr(1, "0.0.0.0.0.0", 2, "null-data", null) // Example for null-data
dlms.addAttr(1, "0.0.0.0.0.1", 2, "array", [{"type":"long-unsigned","value":1},{"type":"long-unsigned","value":2},{"type":"long-unsigned","value":3}]) // Example for array
dlms.addAttr(1, "0.0.0.0.0.2", 2, "structure", [{"type":"unsigned","value":1},{"type":"long-unsigned","value":2},{"type":"array","value":[{"type":"visible-string","value":"one"},{"type":"visible-string","value":"two"}]}]) // Example for structure
dlms.addAttr(1, "0.0.0.0.0.3", 2, "boolean", false) // Example for boolean
dlms.addAttr(1, "0.0.0.0.0.4", 2, "bit-string", [true, false, true, false]) // Example for bit-string as boolean array (default type)
dlms.addAttr(1, "0.0.0.0.0.4", 2, "bit-string", "1010") // Example for bit-string as string with the bit-string representation (alternative set value type, a get will always return it as boolean array)
dlms.addAttr(1, "0.0.0.0.0.5", 2, "double-long", 1) // Example for double-long
// Rest on number examples are omitted because they are similar to double-long
dlms.addAttr(1, "0.0.0.0.0.6", 2, "octet-string", [116, 101, 115, 116]) // Example for octet-string as byte array (default type)
dlms.addAttr(1, "0.0.0.0.0.6", 2, "octet-string", "test") // Example for octet-string as string (alternative set value type, a get will always return it as byte array)
dlms.addAttr(1, "0.0.0.0.0.7", 2, "visible-string", "test") // Example for visible-string
// utf8-string example is omitted because it's similar to visible-string

var result = dlms.set() // Descriptive mode does not really matter, because return should always be null-data.
log(result[0]) // Expected output: {"result":"success","classId":1,"obisCode":"0.0.0.0.0.0","attrId":2,"type":"null-data","value":null}]
// All remaining results are similar, including returning null-data.

set results

They are the same as get results.

dlms.addMethod(classId, obisCode, methodId, type, value)

addMethod() is used for method() function.

dlms.method(descriptive)

Executes a multi DLMS method (or action) request with the previously specified payload (addMethod(classId, obisCode, methodId, type, value)).

Kind: global function
Returns: Array - Array of JSONs with responses. Each JSON will have six fields: result of the method operation, the requested classId, obisCode and methodId, type with the data type of the received value and the value received from the device. An optional error field may be returned for any error that happened during the method (for example an error decoding the optional return parameters).

// After connection has been established
dlms.addMethod(7, "1.0.99.1.0.255", 2) // Example for method needing null-data as parameter (default type and value)
dlms.addMethod(7, "1.0.99.1.0.254", 2, "unsigned", 0) // Example for method needing 0 (unsigned) as parameter

var result = dlms.method()
log(result[0]) // Expected output: {"result":"success","classId":1,"obisCode":"1.0.99.1.0.255","methodId":2,"type":"null-data","value":null}]
log(result[1]) // Expected output: {"result":"success","classId":1,"obisCode":"1.0.99.1.0.254","methodId":2,"type":"boolean","value":true}

action results

• success
• hardware-fault
• temporary-failure
• read-write-denied
• object-undefined
• object-class-inconsistent
• object-unavailable
• type-unmatched
• scope-of-access-violated
• data-block-unavailable
• long-action-aborted
• no-long-action-in-progress
• other-reason

dlms.initializeNextFrameCounter(currentFrameCounter)

Sets the invocation counter of the ciphering to the next value of the received frame counter. This is used for devices that maintain two separate frame counters (one for transmit and one for receive). Usually the current Management Frame Counter - On-line is received in a CompactFrame notification and that value is the one that needs to be passed to this function for that device.

Kind: global function

dlms.getInvocationCounter()

Returns the current invocation counter of the ciphering.

Kind: global function Returns: number (integer).

dlms.disconnect()

Close the DLMS connection.

Kind: global function

dlms.getCompactData(typeDescription, value, descriptive, italianMode)

Extract the compact data serialized in a byte array according to the description given.

Kind: global function
Returns: Object - Object containing result and/or error. On success, result contains the parsed compact data (either in descriptive (with type in each value) or non-descriptive (direct values) format depending on the descriptive parameter). On error, the error will contain the error description and result may be null or contain a best-effort decoding of the compact data that may be incorrect.

Here is a description example:

var typeDescription = {"type": "structure", "items": [
		{"type": "long-unsigned"},
		{"type": "unsigned"},
		{"type": "array", "length": 1, "subtype": {"type": "long-unsigned"}},
		{"type": "array", "length": 1, "subtype": {"type": "double-long-unsigned"}},
		{"type": "structure", "items": [
			{"type": "unsigned"}, {"type": "long-unsigned"}
		]},
		{"type": "octet-string"}
	]
}

Here is an example of the function result in descriptive and non descriptive modes:

var {result: data, error} = dlms.getCompactData(typeDescription, payload);
if (error) {
    log("Error: " + error);
} else {
    log(data) // Expected output: {"type":"structure","value":[{"type":"long-unsigned","value":1},{"type":"unsigned","value":2},{"type":"array","value":[{"type":"long-unsigned","value":3}]},{"type":"array","value":[{"type":"double-long-unsigned","value":4}]},{"type":"structure","value":[{"type":"unsigned","value":5},{"type":"long-unsigned","value":6}]},{"type":"octet-string","value":[83,112,97,114,101,32,79,98,106,101,99,116]}]}
}

var {result: data, error} = dlms.getCompactData(typeDescription, payload, false);
if (error) {
    log("Error: " + error);
} else {
    log(data) // Expected output: [1,2,[3],[4],[5,6],[83, 112, 97, 114, 101, 32, 79, 98, 106, 101, 99, 116]]
}

dlms.getDate(value) ⇒ Date

Extract the Date of a dateTime object or an octet-string. Some dateTime objects or octet-string may not contain a complete date and this method will return a date that may not be as accurate as you expect. You should check the dateTime object for unspecified value.

Kind: global function Returns: Date

// compact-data containing all 

var dateTime = data[0]
log(dateTime) // Expected output: {"type":"date-time","value":{"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2,"hour":10,"minute":26,"second":55,"hundredthsOfSecond":0,"deviation":-60,"status":0}}
log(dlms.getDate(dateTime).toISOString()) // Expected output: 2023-11-28T11:26:55.000Z
log(dlms.getDate(dateTime.value).toISOString()) // Expected output: 2023-11-28T11:26:55.000Z

var date = data[1]
log(date) // Expected output: {"type":"date","value":{"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2}}
log(dlms.getDate(date).toISOString()) // Expected output: 2023-11-28T00:00:00.000Z
log(dlms.getDate(date.value).toISOString()) // Expected output: 2023-11-28T00:00:00.000Z

var time = data[2]
log(time) // Expected output: {"type":"date","value":{"hour":16,"minute":1,"second":2,"hundredthsOfSecond":20}}
log(dlms.getDate(time).toISOString()) // Expected output: 0000-01-01T16:01:02.200Z
log(dlms.getDate(time.value).toISOString()) // Expected output: 0000-01-01T16:01:02.200Z

var octet = data[3]
log(octet) // Expected output: {"type":"octet-string","value":[7, 231, 11, 28, 2, 10, 26, 55, 0, -1, -60, 0]}
log(dlms.getDate(octet).toISOString()) // Expected output: 2023-11-28T11:26:55.000Z
log(dlms.getDate(octet.value).toISOString()) // Expected output: 2023-11-28T11:26:55.000Z

var undefinedDateTimeInOctet = data[4]
log(undefinedDateTimeInOctet) // Expected output: {"type":"octet-string","value":[-1, -1, -1, -1, -1, -1, -1, -1, -1, -128, 0, -1]}
log(dlms.getDate(undefinedDateTimeInOctet).toISOString()) // Expected output: 0000-01-01T00:00:00.000Z
log(dlms.getDate(undefinedDateTimeInOctet.value).toISOString()) // Expected output: 0000-01-01T00:00:00.000Z

log(dlms.getDate(dlms.unspecifiedDateTime()).toISOString()) // Expected output: 0000-01-01T00:00:00.000Z

dlms.getDateTime(value)

Extract the dateTime object of a Date or an octet-string. The resulting dateTime objects generated from a Date will use UTC time specifying a deviation of 0. If you need something else construct the dateTime object manually.

Kind: global function Returns: Object

log(dlms.getDateTime(new Date('2023-11-28T10:24:00.000Z'))) // Expected output: {"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2,"hour":10,"minute":24,"second":0,"hundredthsOfSecond":0,"deviation":0,"status":0}
log(dlms.getDateTime(new Date('2023-11-28T10:24:00.299Z'))) // Expected output: {"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2,"hour":10,"minute":24,"second":0,"hundredthsOfSecond":29,"deviation":0,"status":0}
log(dlms.getDateTime(new Date('Tue Nov 28 2023 11:24:00 GMT+0100'))) // Expected output: {"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2,"hour":10,"minute":24,"second":0,"hundredthsOfSecond":0,"deviation":0,"status":0}

// compact-data containing all values

var octet = data[0]
log(octet) // Expected output: {"type":"octet-string","value":[7, 231, 11, 28, 2, 10, 26, 55, 0, -1, -60, 0]}
log(dlms.getDateTime(octet)) // Expected output: {"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2,"hour":10,"minute":26,"second":55,"hundredthsOfSecond":0,"deviation":-60,"status":0}
log(dlms.getDateTime(octet)) // Expected output: {"year":2023,"month":11,"dayOfMonth":28,"dayOfWeek":2,"hour":10,"minute":26,"second":55,"hundredthsOfSecond":0,"deviation":-60,"status":0}

var undefinedDateTimeInOctet = data[1]
log(undefinedDateTimeInOctet) // Expected output: {'type': 'octet-string', 'value': [-1, -1, -1, -1, -1, -1, -1, -1, -1, -128, 0, -1]}
log(dlms.getDateTime(undefinedDateTimeInOctet)) // Expected output: {"year":65535,"month":255,"dayOfMonth":255,"dayOfWeek":255,"hour":255,"minute":255,"second":255,"hundredthsOfSecond":255,"deviation":32768,"status":255}
log(dlms.getDateTime(undefinedDateTimeInOctet.value)) // Expected output: {"year":65535,"month":255,"dayOfMonth":255,"dayOfWeek":255,"hour":255,"minute":255,"second":255,"hundredthsOfSecond":255,"deviation":32768,"status":255}

dlms.undefinedDateTime()

Get dateTime object with all its fields set to not specified.

You can also use unspecifiedDateTime().

Kind: global function Returns: Object

dlms.addAttr(1, '0.0.0.0.0.0', 2, 'octet-string', dlms.undefinedDateTime())
log(dlms.getDate(dlms.undefinedDateTime()).toISOString()) // Expected output: 0000-01-01T00:00:00.000Z

dlms.unspecifiedDateTime()

Get dateTime object with all its fields set to not specified.

You can also use undefinedDateTime().

Kind: global function Returns: Object

dlms.addAttr(1, '0.0.0.0.0.0', 2, 'octet-string', dlms.unspecifiedDateTime())
log(dlms.getDate(dlms.unspecifiedDateTime()).toISOString()) // Expected output: 0000-01-01T00:00:00.000Z

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)