# 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

```javascript
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](#dlms_gasconfig-object-properties) properties and [dlms_gas.init()](#dlms_gasinitconfentityname) 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](#dlms_gasdecodecustomtemplate-descriptive) 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](#dlms_gaspendingactions) 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](#dlms_gascollect) 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.

```javascript
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](#dlms_gasconfig-object-properties) section.

```javascript
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:

```javascript
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.

```javascript
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:

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

For all options, see the [dlms_gas.actions](#dlms_gasactions-object-properties) section. Although initially with this configuration the order of the actions cannot be changed (see the [dlms_gas.pendingActions](#dlms_gaspendingactions) 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.

{{% notice style="tip" %}}
CF 22 is also considered, but only as part of the FOTA process and it is not expected to be used as push notification compact frame.
{{% /notice %}}

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

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

The `template` property is a JSON following what is specified in the DLMS API documentation for the [dlms.getCompactData](/api/device_integration/connector_functions/protocol_apis/dlms#dlmsgetcompactdatatypedescription-value-descriptive-italianmode)  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](#dlms_gasdefault-object-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:

```javascript
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:

```javascript
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:

```javascript
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.

{{% notice style="info" %}}
Check `dlms_gas.behavior` object's [properties](#dlms_gasbehavior-object-properties) and [functions](#dlms_gasbehavior-object-functions) to understand how internally works behaviors management.
{{% /notice %}}

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:

```javascript
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:

```javascript
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](#dlms_gascustombehaviorbehavior) 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`.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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](#dlms_gas-properties) and it also has some main basic functions. See [dlm_gas functions section](#dlms_gas-functions).

Finally it has complex properties to specifiy Connector Functions behavior:

- `dlms_gas.config` object with [configuration properties](#dlms_gasactions-object-properties) loaded from device entity and configuration entity.
- `dlms_gas.behavior` object with [functions](#dlms_gasbehavior-object-functions) and [properties](#dlms_gasbehavior-object-properties) to manage code execution.
- `dlms_gas.actions` object with [pending actions configuration properties](#dlms_gasactions-object-properties)
- `dlms_gas.default` object with default [properties](#dlms_gasdefault-object-properties) and [functions](#dlms_gasdefault-object-functions)
- `dlms_gas.pietro` object with pietro specific [properties](#dlms_gaspietro-object-properties) and [functions](#dlms_gaspietro-object-functions)
- `dlms_gas.honeywell` object with honeywell specific [properties](#dlms_gashoneywell-object-properties) and [functions](#dlms_gashoneywell-object-functions)
- `dlms_gas.spark` object with spark specific [properties](#dlms_gasspark-object-properties) and [functions](#dlms_gasspark-object-functions)
- `dlms_gas.watertech` object with watertech specific [properties](#dlms_gaswatertech-object-properties)and [functions](#dlms_gaswatertech-object-functions)

### dlms_gas properties

Following properties represent session state.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `now` | `number` | `null` | Current session timestamp in milliseconds. It is calculated in `init` method. |
| `now_seconds` | `number` | `null` | Current session timestamp in seconds. It is calculated in `init` method. |
| `behaviorName` | `string` | `"default"` | Active behavior name. It is calculated from device manufacturer in `init` method. |
| `devCollection` | `Object` | `null` | Main device collection object. It is initialized automatically with normal `collection` object in `init` method. |
| `cellCollection`| `Object` | `null` | Cellular network collection object. It is initialized automatically in `init` method. |
| `uoCollection` | `Object` | `null` | Organization collection object. It is initialized automatically in `init` method. |
| `recUnixTime` | `number` | `null` | Initiailized from received push notification. |
| `EOGDTime` | `number` | `null` | End of Gas Day Time. Initiailized from received push notification. |
| `recMetEventsCounter` | `number` | `null` | Metrological events counter. Initiailized from received push notification. |
| `recNonMetEventsCounter` | `number` | `null` | Non-metrological events counter. Initiailized from received push notification. |
| `messagesCounter` | `number` | `0` | Count of messages in current session. |
| `numBlockErrorSession` | `number` | `0` | Used to manage fota blocks transfer. |
| `numBlockTransfSession` | `number` | `0` | Used to manage fota blocks transfer. |
| `restoreDefaultSchedule` | `boolean` | `false` | Used to manage restoring the default schedule. |
| `onlineMngFrmCntr` | `number` | `null` | Online management frame counter. It is initialized from received push notification if available, otherwise is initialized from meter previously collected data. |
| `messagesPerECL` | `number` | `null` | Count of messages per ECL. It is initialized in `init` method from used behavior |

### 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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `confEntityName` | `string`| `null` | Optional organization name. |

Examples:

```javascript
dlms_gas.init();
```

```javascript
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.

| Parameter | Type | Default | Description |
|----------|------|---------|-------------|
| `customTemplate` | `Object` | `null` | Template to force. |
| `descriptive` | `boolean`| `false` | Enable descriptive format. |

Example:

```javascript
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:

```javascript
//standard behavior
dlms_gas.pendingActions();
```

```javascript
//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:

```javascript
dlms_gas.collect();
```

{{% notice style="warning" %}}
It must used at the end of the Connector function to ensure that data collected during the execution is raised to opengate.
{{% /notice %}}

#### 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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `behavior` | `Object` | `{}` | The behavior to use. If empty, is like using `default` behavior. |

Example:

```javascript
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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `callType` | `string` | | Type of call to execute. |
| `dType` | `number` | | mtype for messages sent to device. |
| `uType` | `number` | | mtype for messages received from device. |

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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `dType` | `number` | | mtype for messages sent to device. |
| `uType` | `number` | | mtype for messages received from device. |

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:

```javascript
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:

```javascript
{
  "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.

```javascript
{
  "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.

```javascript
{
  "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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `dType` | `number` | | mtype for messages sent to device. |
| `uType` | `number` | | mtype for messages received from device. |

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:

```javascript
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:

```javascript
{
  "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.

```javascript
{
  "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.

```javascript
{
  "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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `dType` | `number` | | mtype for messages sent to device. |
| `uType` | `number` | | mtype for messages received from device. |

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:

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

Some return examples:

```javascript
{
  "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.

```javascript
{
  "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.

```javascript
{
  "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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `classId` | `number` | | Class ID of the object. |
| `obis` | `string` | | OBIS code. |
| `attrId` | `number` | | Attribute ID. |
| `accessSelector` | `number` | | Access selector (e.g., 1 for range). |
| `paramClassID` | `number` | | Selector's parameter Class ID. |
| `paramObis` | `string` | | Selector's parameter OBIS code. |
| `paramAttrId` | `number` | | Selector's parameter Attribute ID. |
| `rangeType` | `string` | | Data type for range values (e.g., 'double-long-unsigned'). |
| `rangeFrom` | `number` | | Start of range. |
| `rangeTo` | `number` | | End of range. |
| `maxRangePerPage` | `number` | | Maximum range size. For event buffer ranges, the number of elements per page. For temporal ranges max period for page. |
| `dType` | `number` | | mtype for messages sent to device. |
| `uType` | `number` | | mtype for messages received from device. |

It returns an object with the following properties:

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

Example:

```javascript
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);
```
{{% notice style="tip" %}}
There some objects to make easier the call to this method. Check the [Range retrieval configuration object section][#range-retrieval-configuration-object]
{{% /notice %}}

### 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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `orgName` | `string` | `null` | Name of the organization that the meter belongs to. |
| `confEntityName` | `string` | `null` | Name of the entity that contins configuration parameters. See `dlms_gas.init` method to see how it is initialized|
| `systemTitle` | `string` | `null` | Meter System title.  |
| `cellPrefix` | `string` | `null` | Prefix for the cell identification. It can be defined in the configuration entity. |
| `apiKey` | `string` | `null` | API Key for the platform. It must be defined in the configuration entity. |
| `periodicDataAgeMillis` | `number` | `null` | Maximum age of periodic data in milliseconds. It can be calculated from data in configuration entity. |
| `maxSecondsWithoutCom` | `number` | `null` | Maximum seconds without communication. It can be calculated from data in configuration entity. |
| `cellPlanName` | `string` | `null` | Name of the cell plan. It can be defined in the configuration entity. |
| `maxClockSkewAllowedSec` | `number` | `null` | Maximum difference in time for clock sync in seconds. It can be defined in the configuration entity. |
| `maxClockCorrection` | `number` | `null` | Maximum clock correction allowed. In this case it is filled for specified behavior |
| `numBlockError` | `number` | `null` | It contains meter's FOTA process blocks number with transfer error. |
| `numBlockTransf` | `number` | `null` | It contains meter's FOTA process successufully transferred blocks number. |
| `badSessionsCounter` | `number` | `null` | It contains meter's FOTA process failed sessions counter |
| `maxSessionsErrorsRate` | `number` | `null` | It contains FOTA process maximum block errors rate allowed in a session. It can be defined in the configuration entity. |
| `maxBadSessions` | `number` | `null` | It contains FOTA process maximum bad sessions before FOTA abort. It can be defined in the configuration entity |
| `manufacturer` | `string` | `null` | Meter manufacturer. |
| `italianMode` | `boolean` | `false` | Enable Italian specific mode. Calculated from manufacturer. |
| `deviceId` | `string` | `null` | Meter identifier. |
| `cellId` | `string` | `null` | Cell identifier. It is filled from device collected cell identifier. |
| `fotaBlockSize` | `number` | `null` | FOTA block size for current meter. It is filled from collected data. |
| `fotaEnabled` | `boolean` | `false` | Indicates if the meter has FOTA enabled. It is filled from collected data. |
| `fotaNumberOfBlocks` | `number` | `null` | FOTA total number of blocks for current meter. It is calculated and collected at the begining of FOTA process |
| `lastEventCounter` | `number` | `null` | Counter for the last event. It is filled from meter's  previously collected data. |
| `lastCommunication` | `number` | `null` | Timestamp for the last communication. It is filled from meter's previous last notification. |

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

| Property | Entity | Datastream | Default value |
| -------- | -------- | ---------- | ------------- |
| `orgName` | `Meter` | `provision.administration.organization` | `null` |
| `manufacturer` | `Meter` | `provision.device.model` | `null` |
| `deviceId` | `Meter` | `provision.device.serialNumber` | `null` |
| `systemTitle` | `Meter` | `provision.administration.identifier` | `null` |
| `lastEventCounter` | `Meter` | `metCount` | `null` |
| `cellId` | `Meter` | `NBcellID` | `null` |
| `fotaBlockSize` | `Meter` | `fotaBlockSize` | `null` |
| `fotaNumberOfBlocks` | `Meter` | `firmwareTotalBlock` | `null` |
| `fotaEnabled` | `Meter` | `fotaEnabled` | `null` |
| `numBlockError` | `Meter` | `numBlockError` | `0` |
| `numBlockTransf` | `Meter` | `numBlockTransf` | `0` |
| `badSessionsCounter` | `Meter` | `badSessionsCounter` | `0` |
| `lastCommunication` | `Meter` | `mType` | `null` |
| `cellPrefix` | `Configuration` | `provision.ACR` | `orgName_` |
| `periodicDataAgeMillis` | `Configuration` | `provision.periodicDataAgeDays` | `1296000000` (15 days in milliseconds) |
| `maxSecondsWithoutCom` | `Configuration` | `provision.maxDaysWithoutCom` | `259200` (3 days in seconds) |
| `maxClockSkewAllowedSec` | `Configuration` | `provision.maxClockSkewAllowedSec` | `120` |
| `maxSessionsErrorsRate` | `Configuration` | `provision.maxSessionsErrorsRate` | `0.2` |
| `maxBadSessions` | `Configuration` | `provision.maxBadSessions` | `3` |
| `cellPlanName` | `Configuration` | `provision.cellPlanName` | `null` |
| `apiKey` | `Configuration` | `provision.administration.apiKey` | `null` |

{{% notice style="warning" %}}
Datastream used to initialize `periodicDataAgeMillis` and `maxSecondsWithoutCom` contains time in days and they are converted to milliseconds and seconds respectively.
{{% /notice %}}

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

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

### dlms_gas.config Object Functions

#### config.__initApiKey(apiKey)

Internal utility used to initialize the API key.

| Parameter | Type     | Description                                        |
|-----------|--------- |--------------------------------------------------- |
| `apiKey`  | `string` | The API key to be forced into the session context. |

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

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

### dlms_gas.behavior Object properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `chain` | `Set<string>` | `null` | It contains the behavior chain used to resolve function or property call. It is initilized in `dlms_gas.init` |

### 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.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `manufacturer` | `string` | `null` | Meter provisioned manufacturer name. |

Next table explains current behaviors:

| Behavior name | Manufacturer |
|---------------|--------------|
| `pietro` | If manufacturer contains 'pietro' |
| `honeywell` | If manufacturer contains 'honeywell' |
| `spark` | If manufacturer contains 'spark' |
| `watertech` | If manufacturer contains 'watertech' |
| `default` | If manufacturer is null or contains none of the above |

#### 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.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `behaviorName` | `string` | `null` | The name of the behavior to calculate the chain for. If null, it uses dlms_gas.behaviorName |
| `visited` | `Set<string>` | `new Set()` | A set of behavior names that have already been visited. Used to detect circular references |

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

```javascript
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:

```javascript
//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.

{{% notice style="warning" %}}
This method should be used when specifying a custom behavior to ensure that the value returned is the best match for the current behavior chain.
{{% /notice %}}

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `propertyName` | `string` | `null` | The name of the property to retrieve |

#### 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.

{{% notice style="warning" %}}
This method should be used when specifying a custom behavior to ensure that the function returned is the best match for the current behavior chain.
{{% /notice %}}

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `functionName` | `string` | `null` | The name of the function to retrieve |

Example of function calling using behavior management:

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

{{% notice style="warning" %}}
When overriding one function in custom behavior take care to not call itselsf using this method because it will throw exception due to infinite recursion
{{% /notice %}}

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

```javascript
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.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `setClock` | `boolean` | `true` | Enable automated clock synchronization. |
| `retrieveInitialData` | `boolean" | `true` | Enable FW and static config retrieval. |
| `retrievePushEventsConfigurations` | `boolean` | `true" | Enable PUSH event config retrieval. |
| `periodicActions` | `boolean` | `true" | Enable statistics and diagnostic retrieval. |
| `automaticActions` | `boolean` | `true" | Enable logs and profile retrieval. |
| `operations` | `boolean` | `true" | Enable pending operation execution. |
| `forceInitialData` | `boolean` | `false` | Force retrieval of initial data. |
| `forcePushConf` | `boolean` | `false` | Force retrieval of push configuration. |
| `forceStatistics` | `boolean` | `false` | Force retrieval of statistics. |

### dlms_gas.default object Properties

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

| Property | Type | Value | Description |
|----------|------|---------|-------------|
| `47` | `Object` | | Specification for Compact Frame 47. Includes `template` and `initAndCollect`. See [decoding section](#customization-of-compact-frames-decoding).|
| `48` | `Object` | | Specification for Compact Frame 48. Includes `template` and `initAndCollect`. See [decoding section](#customization-of-compact-frames-decoding).|
| `49` | `Object` | | Specification for Compact Frame 49. Includes `template` and `initAndCollect`. See [decoding section](#customization-of-compact-frames-decoding).|
| `51` | `Object` | | Specification for Compact Frame 51. Includes `template` and `initAndCollect`. See [decoding section](#customization-of-compact-frames-decoding).|
| `97` | `Object` | | Specification for Compact Frame 97. Includes `template` and `initAndCollect`. See [decoding section](#customization-of-compact-frames-decoding).|
| `22` | `Object` | | Specification for Compact Frame 22. Used in FOTA process. |
| `cwport` | `number` | `1` | Used to define `dlms.cwport` when initializing client |
| `swport` | `number` | `1` | Used to define `dlms.swport` when initializing client |
| `hesSystemTitle` | `string` | `5341435341435341` | Used to define `dlms.hesSystemTitle` when initializing client |
| `conformance` | `string` | `['MULTIPLE_REFERENCES', 'GENERAL_PROTECTION', 'SELECTIVE_ACCESS']` | Used to define `dlms.conformance` when initializing client |
| `forceGetWithoutList` | `boolean` | `false` | Used to define `dlms.forceGetWithoutList` when initializing client |
| `forceSetWithoutList` | `boolean` | `false` | Used to define `dlms.forceSetWithoutList` when initializing client |
| `ignoreSystemTitleInCiphering` | `boolean` | `true` | Used to define `dlms.ignoreSystemTitleInCiphering` when initializing client |
| `onlineFramCounterRetryInc` | `number` | `5` | Used to synchronize meters counter with collected frame counter.  |
| `onlineFramCounterRetryMax` | `number` | `3` | Used to synchronize meters counter with collected frame counter.  |
| `maxClockCorrection` | `number` | `900` | Default maximum clock correction allowed. |
| `messagesPerECL` | `object` | `{ "0": 20, "1": 20, "2": 0 }` | To limit fota blocks depending on ECL value. |
| `isItalianModeManufacturer` | `boolean` | `true` | Indicates if manufacturer follows Italian mode by default. |
| `eclAttribute` | `number` | `3` | Attribute ID for ECL retrieval. |
| `errorIfWrongFotaBlockMapSize` | `boolean` | `true` | Specify if fota operation must finish immediately with error if block map length retrieved in CF22 does not match with calculated number of blocks. If false, block map array will be resized to the calculated number of blocks. |
| `statisticsRefDs` | `string` | `"MetBattRemUseTime"` | Data stream reference for statistics retrieval. |
| `supportedOps` | `Array` | | List of supported operations and their priority for execution. [see operations spec](#operations-specification). |

#### 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](#dlms_gasgetbyrangeclassid-obis-attrid-accessselector-paramclassid-paramobis-paramattrid-rangetype-rangefrom-rangeto-maxrangeperpage-dtype-utype) function.

| Property | Type | Description |
|----------|------|---------|
| `classId` | `number` | Data to be retrieved class id. |
| `obis` | `string` | Data to be retrieved obis. |
| `attrId` | `number` | Data to be retrieved attribute id. |
| `accessSelector` | `number` | Data to be retrieved attribute id. |
| `paramClassID` | `number` | Range parameter specification classID. |
| `paramObis` | `string` | Range parameter specification obis. |
| `paramAttrId` | `number` | Range parameter specification attrId. |
| `rangeType` | `string` | Range parameter specification rangeType. |
| `maxRangePerPage` | `number` | Used to specify pagination |

Next are default configurations for specified retrievals:

```javascript
{
    "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.

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | Opengate operation name. |
| `funcName` | `string` | Function to be called when specified operation is executed.|

Default value:

```json
{
    "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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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](#defaultretrievemetrologicalevents)
- [retrieveDailyProfiles](#defaultretrievedailyprofiles)

#### 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.

{{% notice style="warning" %}}
In the case of `cellCollection` it will check if cell entity exists and create if necessary.
{{% /notice %}}

#### default.collectBillingPeriodSnapshotData(billingPeriodData)

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

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `billingPeriodData` | `object` | Object containing the billing period data. |

#### 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.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `diagnostic` | `number` | Diagnostic value to be decoded. |
| `at` | `number` | Timestamp to be used for collection. If not defined current time will be used. |
| `source` | `string` | If defined it will be used as datapoint source. |
| `sourceInfo` | `object` | If defined it will be used as datapoint sourceInfo. |

#### default.collectHourlyDiagnostics(diagnosticsArray, unixTime)

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

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `diagnosticsArray` | `Array` | Array with hourly diagnostics values |
| `at` | `number` | Timestamp to be used as reference. |

#### default.collectHourlyVolumes(incsArray, at)

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

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `incsArray` | `Array` | Array with hourly volume increments |
| `at` | `number` | Timestamp to be used 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `mType` | `number` | Message type. |
| `payload` | `string` | Raw hex payload. |
| `payloadSize` | `number` | Payload size in bytes. |

Examples:

```javascript
// 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `networkStatus` | `number` | Status to be decoded. |
| `at` | `number` | Timestamp to be used for collection. If not defined current time will be used. |

#### default.collectTarifPlan(tariffPlann, at)

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

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `tariffPlann` | `array` | Array of bytes representing the tariff plan. |
| `at` | `number` | Timestamp to be used for collection. If not defined current time will be used. |

#### 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:

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `loadProfiles` | `Array` | Array of daily profiles to collect. |
| `source` | `string` | Optional source identifier. |
| `sourceInfo` | `object` | Optional source information. |

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

| Element Index |  Type | Description |
|---------------|-------|-------------|
| 0 | `number` | End of Gas day timestamp. |
| 1 | `number` | End of Gas day cumulative diagnostic |
| 2 | `number` | End of Gas day volume |
| 3 | `number` | End of Gas day volume under alarm. |

#### default.commsBatStatus(op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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).

| Parameter | Type | Description |
|-----------|------|-------------|
| `date` | `Date` | Date to convert. |

Returns an object with following fields:

| Field | Type | Description |
|-------|------|-------------|
| `result` | `Array<number>` | DLMS `octet-string` format for date (5 bytes). |
| `error` | `string` | Error message. |

Example:

```javascript
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).

| Parameter | Type | Description |
|-----------|------|-------------|
| `date` | `Date` | Date to convert. |

Returns an object with following fields:

| Field | Type | Description |
|-------|------|-------------|
| `result` | `Array<number>` | DLMS `octet-string` format for time (4 bytes). |
| `error` | `string` | Error message. |

Example:

```javascript
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](/api/device_integration/connector_functions/protocol_apis/dlms#dlmsgetcompactdatatypedescription-value-descriptive-italianmode) .

| Parameter | Type | Description |
|-----------|------|-------------|
| `customTemplate` | `object` | Template to be used for compact frame decoding. |
| `descriptive` | `boolean` | If true, the decoded values will be in a more descriptive format. |

Returns an object with following fields:

| Field | Type | Description |
|-------|------|-------------|
| `result` | `object` | Decoded data. |
| `error` | `string` | Error message. |

``` javascript
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")}`

| Parameter | Type | Description |
|-----------|------|-------------|
| `fwBytes` | `Array<number>` | Array of 6 bytes representing the firmware version. |

Returns an object with following fields:

| Field | Type | Description |
|-------|------|-------------|
| `result` | `string` | Decoded firmware version string. It is returned with next template: |
| `error` | `string` | Error message. |

```javascript
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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `event` | `number` | Event number (1, 2, 3, 4). |
| `conf` | `object` | Configuration for the event.  |

`conf` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `cf` | `number` | Compact frame to be configured |
| `addressOctStr` | `byte[]` | Ip:port string coded as byte array |
| `randomTime` | `number` | Random time to be used in communications |
| `schedule` | `Object[]` | Schedulation specification.  |

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

| Property | Type | Description |
|----------|------|-------------|
| `dateOctet` | `byte[]` | Communication periodicity expression following DLMS standard.|
| `timeOctet` | `byte[]` | Communication time specification: `[Hour, Minute, Second, Hundredths]`  |

#### default.encodeIpPort(ip, port)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `ip` | `string` | IP address to encode. |
| `port` | `number` | Port to encode. |

Returns an byte array

Example:

```javascript
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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `scheduleData` | `Object` | Object with event's day periodicty value and hour specification value from operation paraemeters. |

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

```json
[
  {
    "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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `imageTransferBlocksMap` | `Array` | List of blocks retrieved in CF22 |
| `expectedNumberOfBlocks` | `number` | Expected number of blocks calculated in FOTA process initialization. |

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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

Returns an object with following properties:

| Property | Type | Description |
|----------|------|-------------|
| `result` | `Array<number>` | Array with the calculated image identifier. |
| `error` | `string` | Error message. |

Example:

```json
{
  "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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### default.fotaRestoreDefaultSchedule(op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### default.fotaStateFromCf22(op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

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

```json
{
  "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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatus1(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatus2(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatus3(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatus4(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatus5(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatus7(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaStatusUnknown(op, fotaState)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |

#### default.fotaUpdateLostSteps(fotaState, op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `fotaState` | `object` | FOTA status object with returned by `fotaStateFromCf22` function. |
| `op` | `Object` | Object returned by `operation` api. |

#### default.fotaUpdateSuccessBlocksFromDevice(imageTransferBlocksMap)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `imageTransferBlocksMap` | `Array` | Array with boolean values representing the status of each block. |

#### 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.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `hourlyArray` | `Array` | Array with hourly data (volumes, diagnostics...) |
| `refTime` | `number` | Timestamp to be used as reference |

Returns an array with following objects:

``` json
[
  {
    "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`. 

| Parameter | Type | Description |
|-----------|------|-------------|
| `period` | `string` | Name of periodicty. Check table below for supported values. |
| `time` | `string` | Time value. It is used just to check if it is null and then return `Disabled` octet |

These are codification rules for periodicity:

| Periodicty name | Returned octet |
|----------------|----------------|
| `Disabled`     | `[-1, -1, -1, -1, -1]` |
| `every1Day`    | `[-1, -1, -1, 1, -40]` |
| `every2Day`    | `[-1, -1, -1, 2, -40]` |
| `every3Day`    | `[-1, -1, -1, 3, -40]` |
| `endOfBilling` | `[-1, -1, -1, -1, -36]` |
| `everyMonday`  | `[-1, -1, -1, -1, 1]` |
| `everyTuesday` | `[-1, -1, -1, -1, 2]` |
| `everyWednesday` | `[-1, -1, -1, -1, 3]` |
| `everyThursday` | `[-1, -1, -1, -1, 4]` |
| `everyFriday` | `[-1, -1, -1, -1, 5]` |
| `everySaturday` | `[-1, -1, -1, -1, 6]` |
| `everySunday` | `[-1, -1, -1, -1, 7]` |

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`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `period` | `string` | Name of periodicty. If it is null or `Disabled`, then "Disabled" time octet (`[-1, -1, -1, -1]`) will be returned |
| `time` | `string` | Time value. It is parsed into time octet. If it si null, then "Disabled" (`[-1, -1, -1, -1]`) octet will be returned |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |
| `stepName` | `string` | Name of the step to search. |
| `checkInCurrentResponse` | `boolean` | Whether to check in the current step response. Default value is `false` |

#### default.hourlyValues(op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `Object` | Object with decoded compact frame data return from `dlms.getCompactData()` method. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `Object` | Object with decoded compact frame data return from `dlms.getCompactData()` method. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `Object` | Object with decoded compact frame data return from `dlms.getCompactData()` method. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `Object` | Object with decoded compact frame data return from `dlms.getCompactData()` method. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `Object` | Object with decoded compact frame data return from `dlms.getCompactData()` method. |

{{% notice style="warning" %}}
In this case, because received compact frame does not contain `onlineFrameCounter` it will try to recovery from the device using previously collected frame counter to initilialize client. See [default.restoreOnlineFrameCounter()](#defaultrestoreonlineframecounter) function
{{% /notice %}}

#### default.operations()

Dispatches and executes active operations from the Opengate platform. Retrieves all alive operations for the device using [Operations JS Api](/api/device_integration/connector_functions/core_javascript_api/operation/). 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](#defaultsetclock)
- [Retrieve Initial Data](#defaultretrieveinitialdataforce)
- [Retrieve Push Events Configurations](#defaultretrievepusheventsconfigurationsforce)
- [Periodic Actions](#defaultperiodicactions)
- [Automatic Actions](#defaultautomaticactions)
- [Operations](#defaultoperations)

#### default.periodicActions()

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

- [retrieveStatistics](#defaultretrievestatisticsforce)

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### default.requestNonMetroLogs(op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `force` | `boolean` | If `true`, retrieves the data even if it was previously collected. |

#### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `force` | `boolean` | If `true`, retrieves the data even if the data is not too old. |

#### 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.

| Parameter | Type | Description |
|----------|------|-------------|
| `raw` | `number` | Raw signal quality value (0-31). |

#### default.strategy(b1, b0)

Decodes the communication strategy from two bits.

| Parameter | Type | Description |
|-----------|------|-------------|
| `b1` | `number` | First bit. |
| `b0` | `number` | Second bit. |

Return a string with composed strategy.

#### default.tauInSecondsFromRaw(raw)

Decodes TAU timer to seconds following DLMS specification.

| Parameter | Type | Description |
|----------|------|-------------|
| `raw" | `number` | 8-bit timer value. |

Example:

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

#### default.tmrInSecondsFromRaw(raw)

Decodes raw TMR to seconds following dlms specfication.

| Parameter | Type | Description |
|----------|------|-------------|
| `raw" | `number` | 8-bit timer value. |

#### default.valveManagement(op)

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

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `op` | `Object` | | Operation request object. |

### 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

| Property | Type | Value | Description |
|----------|------|---------|-------------|
| `conformance` | `string` | `['GENERAL_PROTECTION', 'SELECTIVE_ACCESS']` | Used to define `dlms.conformance` when initializing client |
| `ignoreSystemTitleInCiphering` | `boolean` | `false` | Used to define `dlms.ignoreSystemTitleInCiphering` when initializing client |

### 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.

| Parameter | Type | Description |
|-----------|------|-------------|
| `scheduleData` | `Object` | Object with event's day periodicty value and hour specification value from operation paraemeters. |

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

```json
[
  {
    "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

| Property | Type | Value | Description |
|----------|------|---------|-------------|
| `forceSetWithoutList` | `boolean` | `true` | Used to define `dlms.forceSetWithoutList` when initializing client |
| `eclAttribute` | `number` | `253` | Attribute ID for ECL retrieval. |

### dlms_gas.spark object Functions

#### spark.fotaImgVerify(op)

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

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `op` | `Object` | | Operation request object. |

#### spark.fotaCalculateIdentifier(op)

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

| Parameter | Type | Description |
|-----------|------|-------------|
| `op` | `Object` | Object returned by `operation` api. |

Returns an object with following properties:

| Property | Type | Description |
|----------|------|-------------|
| `result` | `Array<number>` | Array with the calculated image identifier. |
| `error` | `string` | Error message. |

Example:

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

### dlms_gas.watertech object Properties

| Property | Type | Value | Description |
|----------|------|---------|-------------|
| `conformance` | `string` | `['GENERAL_PROTECTION', 'SELECTIVE_ACCESS']` | Used to define `dlms.conformance` when initializing client |
| `ignoreSystemTitleInCiphering` | `boolean` | `false` | Used to define `dlms.ignoreSystemTitleInCiphering` when initializing client |

### dlms_gas.watertech object Functions

There are no specific properties for `dlms_gas.watertech`.