iotagent-node-lib 4.4.0 → 4.5.0

package/config.js

@@ -76,7 +76,8 @@ var config = {
     subservice: '/gardens',
     providerUrl: 'http://192.168.56.1:4041',
     deviceRegistrationDuration: 'P1M',
-    defaultType: 'Thing'
+    defaultType: 'Thing',
+    expressLimit: '1Mb'
 };
 
 module.exports = config;

package/doc/admin.md

@@ -260,13 +260,13 @@ the `mongob` section (as described bellow). E.g.:
 
 It configures the MongoDB driver for those repositories with 'mongodb' type. If the `host` parameter is a list of
 comma-separated IPs, they will be considered to be part of a Replica Set. In that case, the optional property
-`replicaSet` should contain the Replica Set name. If the database requires authentication, username (`user`),
-password (`password`) and authSource (`authSource`) can be set. If the database requires TLS/SSL connection but any
-validation of the certificate chain is not mandatory, all you need is to set the ssl (`ssl`) option as `true` to connect
-the database. If you need to add more complex option(s) such as `retryWrites=true` or `w=majority` when connection
-database, extraArgs (`extraArgs`) can be used to perform it. For The MongoBD driver will retry the connection at startup
-time `retries` times, waiting `retryTime` seconds between attempts, if those attributes are present (default values are
-5 and 5 respectively). E.g.:
+`replicaSet` should contain the Replica Set name. If the database requires authentication, username (`user`), password
+(`password`) and authSource (`authSource`) can be set. If the database requires TLS/SSL connection but any validation of
+the certificate chain is not mandatory, all you need is to set the ssl (`ssl`) option as `true` to connect the database.
+If you need to add more complex option(s) such as `retryWrites=true` or `w=majority` when connection database, extraArgs
+(`extraArgs`) can be used to perform it. For The MongoBD driver will retry the connection at startup time `retries`
+times, waiting `retryTime` seconds between attempts, if those attributes are present (default values are 5 and 5
+respectively). E.g.:
 
 ```javascript
 {
@@ -421,6 +421,14 @@ characters (such as semi-colons) which are
 specification. When provisioning devices, it is necessary that the developer provides valid `objectId`-`name` mappings
 whenever relaxed mode is used, to prevent the consumption of forbidden characters.
 
+#### `expressLimit`
+
+IotAgents, as all Express applications that use the body-parser middleware, have a default limit to the request body
+size that the application will handle. This default limit for ioiotagnets are 1Mb. So, if your IotAgent receives a
+request with a body that exceeds this limit, the application will throw a “Error: Request entity too large”.
+
+The 1Mb default can be changed setting the `expressLimit` configuration parameter (or equivalente `IOTA_EXPRESS_LIMIT` environment variable).
+
 ### Configuration using environment variables
 
 Some of the configuration parameters can be overriden with environment variables, to ease the use of those parameters
@@ -482,6 +490,7 @@ overrides.
 | IOTA_EXPLICIT_ATTRS                  | `explicitAttrs`                 |
 | IOTA_DEFAULT_ENTITY_NAME_CONJUNCTION | `defaultEntityNameConjunction`  |
 | IOTA_RELAX_TEMPLATE_VALIDATION       | `relaxTemplateValidation`       |
+| IOTA_EXPRESS_LIMIT                   | `expressLimit`                  |
 
 Note:
 

package/doc/api.md

@@ -11,7 +11,7 @@
         -   [Uniqueness of groups and devices](#uniqueness-of-groups-and-devices)
     -   [Special measures and attributes names](#special-measures-and-attributes-names)
     -   [Entity attributes](#entity-attributes)
-    -   [Multientity support)](#multientity-support)
+    -   [Multientity support](#multientity-support)
     -   [Metadata support](#metadata-support)
         -   [NGSI LD data and metadata considerations](#ngsi-ld-data-and-metadata-considerations)
     -   [Advice on Attribute definitions](#advice-on-attribute-definitions)
@@ -32,6 +32,7 @@
         -   [Measurement transformation order](#measurement-transformation-order)
         -   [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id)
     -   [Timestamp Processing](#timestamp-processing)
+    -   [Multimeasure support](#multimeasure-support)
     -   [Overriding global Context Broker host](#overriding-global-context-broker-host)
     -   [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath)
     -   [Secured access to the Context Broker](#secured-access-to-the-context-broker)
@@ -286,32 +287,37 @@ e.g.:
 
 ```json
 {
-     "entity_type": "Lamp",
-     "resource":    "/iot/d",
-     "protocol":    "PDI-IoTA-UltraLight",
-..etc
-     "commands": [
-        {"name": "on","type": "command"},
-        {"name": "off","type": "command"}
-     ],
-     "attributes": [
-        {"object_id": "s", "name": "state", "type":"Text"},
-        {"object_id": "l", "name": "luminosity", "type":"Integer",
-          "metadata":{
-              "unitCode":{"type": "Text", "value" :"CAL"}
-          }
+    "entity_type": "Lamp",
+    "resource": "/iot/d",
+    "protocol": "PDI-IoTA-UltraLight",
+    "commands": [
+        { "name": "on", "type": "command" },
+        { "name": "off", "type": "command" }
+    ],
+    "attributes": [
+        { "object_id": "s", "name": "state", "type": "Text" },
+        {
+            "object_id": "l",
+            "name": "luminosity",
+            "type": "Integer",
+            "metadata": {
+                "unitCode": { "type": "Text", "value": "CAL" }
+            }
         }
-     ],
-     "static_attributes": [
-          {"name": "category", "type":"Text", "value": ["actuator","sensor"]},
-          {"name": "controlledProperty", "type": "Text", "value": ["light"],
-            "metadata":{
-              "includes":{"type": "Text", "value" :["state", "luminosity"]},
-              "alias":{"type": "Text", "value" :"lamp"}
+    ],
+    "static_attributes": [
+        { "name": "category", "type": "Text", "value": ["actuator", "sensor"] },
+        {
+            "name": "controlledProperty",
+            "type": "Text",
+            "value": ["light"],
+            "metadata": {
+                "includes": { "type": "Text", "value": ["state", "luminosity"] },
+                "alias": { "type": "Text", "value": "lamp" }
             }
-          },
-     ]
-   }
+        }
+    ]
+}
 ```
 
 Metadata could also has `expression` like attributes in order to expand it:
@@ -320,35 +326,37 @@ e.g.:
 
 ```json
 {
-     "entity_type": "Lamp",
-     "resource":    "/iot/d",
-     "protocol":    "PDI-IoTA-UltraLight",
-..etc
-     "commands": [
-        {"name": "on","type": "command"},
-        {"name": "off","type": "command"}
-     ],
-     "attributes": [
-        {"object_id": "s", "name": "state", "type":"Text"},
-        {"object_id": "l", "name": "luminosity", "type":"Integer",
-          "metadata":{
-              "unitCode":{"type": "Text", "value" :"CAL"}
-          }
+    "entity_type": "Lamp",
+    "resource": "/iot/d",
+    "protocol": "PDI-IoTA-UltraLight",
+    "commands": [
+        { "name": "on", "type": "command" },
+        { "name": "off", "type": "command" }
+    ],
+    "attributes": [
+        { "object_id": "s", "name": "state", "type": "Text" },
+        {
+            "object_id": "l",
+            "name": "luminosity",
+            "type": "Integer",
+            "metadata": {
+                "unitCode": { "type": "Text", "value": "CAL" }
+            }
         }
-     ],
-     "static_attributes": [
-          {"name": "category", "type":"Text", "value": ["actuator","sensor"]},
-          {"name": "controlledProperty", "type": "Text", "value": ["light"],
-            "metadata":{
-              "includes":{"type": "Text",
-                          "value" :["state", "luminosity"],
-                          "expression": "level / 100"
-                         },
-              "alias":{"type": "Text", "value" :"lamp"}
+    ],
+    "static_attributes": [
+        { "name": "category", "type": "Text", "value": ["actuator", "sensor"] },
+        {
+            "name": "controlledProperty",
+            "type": "Text",
+            "value": ["light"],
+            "metadata": {
+                "includes": { "type": "Text", "value": ["state", "luminosity"], "expression": "level / 100" },
+                "alias": { "type": "Text", "value": "lamp" }
             }
-          },
-     ]
-   }
+        }
+    ]
+}
 ```
 
 ### NGSI-LD data and metadata considerations
@@ -458,6 +466,8 @@ mappings of the provision. If `explicitAttrs` is provided both at device and con
 precedence. Additionally `explicitAttrs` can be used to define which measures (identified by their attribute names, not
 by their object_id) defined in JSON/JEXL array will be propagated to NGSI interface.
 
+Note that when `explicitAttrs` is an array or a JEXL expression resulting in to Array, if this array is empty then `TimeInstant` is not propaged to CB.
+
 The different possibilities are summarized below:
 
 Case 1 (default):
@@ -1044,6 +1054,127 @@ Some additional considerations to take into account:
     measure of after a mapping, as described in the previous bullet) then it is refused (so a failover to server
     timestamp will take place).
 
+## Multimeasure support
+
+A device could receive several measures at the same time.
+
+For example:
+
+```json
+[
+    {
+        "vol": 0
+    },
+    {
+        "vol": 1
+    },
+    {
+        "vol": 2
+    }
+]
+```
+
+In this case a batch update (`POST /v2/op/update`) to CB will be generated with the following NGSI v2 payload:
+
+```json
+{
+    "actionType": "append",
+    "entities": [
+        {
+            "id": "ws",
+            "type": "WeatherStation",
+            "vol": {
+                "type": "Number",
+                "value": 0
+            }
+        },
+        {
+            "id": "ws",
+            "type": "WeatherStation",
+            "vol": {
+                "type": "Number",
+                "value": 1
+            }
+        },
+        {
+            "id": "ws",
+            "type": "WeatherStation",
+            "vol": {
+                "type": "Number",
+                "value": 1
+            }
+        }
+    ]
+}
+```
+
+Moreover if a multimeasure contains TimeInstant attribute, then CB update is sorted by attribute TimeInstant:
+
+For example:
+
+```json
+[
+    {
+        "vol": 0,
+        "TimeInstant": "2024-04-10T10:15:00Z"
+    },
+    {
+        "vol": 1,
+        "TimeInstant": "2024-04-10T10:10:00Z"
+    },
+    {
+        "vol": 2,
+        "TimeInstant": "2024-04-10T10:05:00Z"
+    }
+]
+```
+
+In this case a batch update (`POST /v2/op/update`) to CB will be generated with the following NGSI v2 payload:
+
+```json
+{
+    "actionType": "append",
+    "entities": [
+        {
+            "id": "ws",
+            "type": "WeatherStation",
+            "vol": {
+                "type": "Number",
+                "value": 2
+            },
+            "TimeInstant": {
+                "type": "DateTime",
+                "value": "2024-04-10T10:05:00Z"
+            }
+        },
+        {
+            "id": "ws",
+            "type": "WeatherStation",
+            "vol": {
+                "type": "Number",
+                "value": 1
+            },
+            "TimeInstant": {
+                "type": "DateTime",
+                "value": "2024-04-10T10:10:00Z"
+            }
+        },
+        {
+            "id": "ws",
+            "type": "WeatherStation",
+            "vol": {
+                "type": "Number",
+                "value": 0
+            },
+            "TimeInstant": {
+                "type": "DateTime",
+                "value": "2024-04-10T10:15:00Z"
+            }
+        }
+    ]
+}
+```
+
 ## Overriding global Context Broker host
 
 **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types

package/doc/requirements.txt

@@ -1,4 +1,4 @@
 mkdocs==1.2.4
 Pygments==2.15.0
 Markdown==3.3.4
-jinja2==3.1.3
+jinja2==3.1.4

package/lib/commonConfig.js

@@ -156,7 +156,8 @@ function processEnvironmentVariables() {
         'IOTA_FALLBACK_TENANT',
         'IOTA_FALLBACK_PATH',
         'IOTA_LD_SUPPORT_NULL',
-        'IOTA_LD_SUPPORT_DATASET_ID'
+        'IOTA_LD_SUPPORT_DATASET_ID',
+        'IOTA_EXPRESS_LIMIT'
     ];
     const iotamVariables = [
         'IOTA_IOTAM_URL',
@@ -468,6 +469,11 @@ function processEnvironmentVariables() {
             ? config.defaultEntityNameConjunction
             : ':';
     }
+    if (process.env.IOTA_EXPRESS_LIMIT) {
+        config.expressLimit = process.env.IOTA_EXPRESS_LIMIT;
+    } else {
+        config.expressLimit = config.expressLimit ? config.expressLimit : '1mb';
+    }
 }
 
 function setConfig(newConfig) {

package/lib/services/devices/deviceRegistryMemory.js

@@ -176,7 +176,7 @@ function getByName(name, service, subservice, callback) {
     getByNameAndType(name, null, service, subservice, callback);
 }
 
-function update(device, callback) {
+function update(previousDevice, device, callback) {
     registeredDevices[device.service][device.id] = deepClone(device);
     callback(null, device);
 }

package/lib/services/devices/deviceRegistryMongoDB.js

@@ -290,9 +290,9 @@ function getByName(name, service, servicepath, callback) {
  *
  * @param {Object} device       Device object with the new values to write.
  */
-function update(device, callback) {
+function update(previousDevice, device, callback) {
     logger.debug(context, 'Storing updated values for device [%s]:\n%s', device.id, JSON.stringify(device, null, 4));
-    getDevice(device.id, device.apikey, device.service, device.subservice, function (error, data) {
+    getDevice(device.id, previousDevice.apikey, device.service, device.subservice, function (error, data) {
         if (error) {
             callback(error);
         } else {

package/lib/services/devices/deviceService.js

@@ -444,8 +444,8 @@ function unregisterDevice(id, apikey, service, subservice, callback) {
     });
 }
 
-function updateRegisterDevice(deviceObj, entityInfoUpdated, callback) {
-    deviceHandler.updateRegisterDevice(deviceObj, entityInfoUpdated, callback);
+function updateRegisterDevice(deviceObj, previousDevice, entityInfoUpdated, callback) {
+    deviceHandler.updateRegisterDevice(deviceObj, previousDevice, entityInfoUpdated, callback);
 }
 
 /**
@@ -518,7 +518,8 @@ function getDevice(deviceId, apikey, service, subservice, callback) {
  * @param {String} device           JSON object contain the device to update.
  */
 function updateDevice(device, callback) {
-    config.getRegistry().update(device, callback);
+    logger.debug(context, 'updateDevice %j', device);
+    config.getRegistry().update(device, device, callback);
 }
 
 /**

package/lib/services/devices/devices-NGSI-LD.js

@@ -182,7 +182,7 @@ function updateEntityNgsiLD(deviceData, updatedDevice, callback) {
  *
  * @param {Object} deviceObj                    Object with all the device information (mandatory).
  */
-function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
+function updateRegisterDeviceNgsiLD(deviceObj, previousDevice, entityInfoUpdated, callback) {
     if (!deviceObj.id || !deviceObj.type) {
         callback(new errors.MissingAttributes('Id or device missing', deviceObj));
         return;
@@ -280,7 +280,7 @@ function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
                 apply(
                     config.getRegistry().get,
                     deviceObj.id,
-                    deviceObj.apikey,
+                    previousDevice.apikey,
                     deviceObj.service,
                     deviceObj.subservice
                 ),
@@ -289,7 +289,7 @@ function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
                 apply(combineWithNewDevice, deviceObj),
                 apply(registrationUtils.sendRegistrations, false),
                 apply(registrationUtils.processContextRegistration, deviceObj),
-                config.getRegistry().update
+                apply(config.getRegistry().update, previousDevice)
             ],
             callback
         );
@@ -299,7 +299,7 @@ function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
                 apply(
                     config.getRegistry().get,
                     deviceObj.id,
-                    deviceObj.apikey,
+                    previousDevice.apikey,
                     deviceObj.service,
                     deviceObj.subservice
                 ),
@@ -308,7 +308,7 @@ function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
                 apply(combineWithNewDevice, deviceObj),
                 apply(registrationUtils.sendRegistrations, false),
                 apply(registrationUtils.processContextRegistration, deviceObj),
-                config.getRegistry().update
+                apply(config.getRegistry().update, previousDevice)
             ],
             callback
         );

package/lib/services/devices/devices-NGSI-mixed.js

@@ -38,11 +38,11 @@ const deviceHandlerV2 = require('./devices-NGSI-v2');
  *
  * @param {Object} deviceObj                    Object with all the device information (mandatory).
  */
-function updateRegisterDeviceNgsiMixed(deviceObj, entityInfoUpdated, callback) {
+function updateRegisterDeviceNgsiMixed(deviceObj, previousDevice, entityInfoUpdated, callback) {
     if (config.checkNgsiLD(deviceObj)) {
-        deviceHandlerLD.updateRegisterDevice(deviceObj, entityInfoUpdated, callback);
+        deviceHandlerLD.updateRegisterDevice(deviceObj, previousDevice, entityInfoUpdated, callback);
     } else {
-        deviceHandlerV2.updateRegisterDevice(deviceObj, entityInfoUpdated, callback);
+        deviceHandlerV2.updateRegisterDevice(deviceObj, previousDevice, entityInfoUpdated, callback);
     }
 }
 

package/lib/services/devices/devices-NGSI-v2.js

@@ -247,7 +247,7 @@ function updateEntityNgsi2(deviceData, updatedDevice, callback) {
  *
  * @param {Object} deviceObj                    Object with all the device information (mandatory).
  */
-function updateRegisterDeviceNgsi2(deviceObj, entityInfoUpdated, callback) {
+function updateRegisterDeviceNgsi2(deviceObj, previousDevice, entityInfoUpdated, callback) {
     if (!deviceObj.id || !deviceObj.type) {
         callback(new errors.MissingAttributes('Id or device missing', deviceObj));
         return;
@@ -352,7 +352,7 @@ function updateRegisterDeviceNgsi2(deviceObj, entityInfoUpdated, callback) {
                 apply(
                     config.getRegistry().get,
                     deviceObj.id,
-                    deviceObj.apikey,
+                    previousDevice.apikey, // it could be updated
                     deviceObj.service,
                     deviceObj.subservice
                 ),
@@ -361,7 +361,7 @@ function updateRegisterDeviceNgsi2(deviceObj, entityInfoUpdated, callback) {
                 apply(combineWithNewDevice, deviceObj),
                 apply(registrationUtils.sendRegistrations, false),
                 apply(registrationUtils.processContextRegistration, deviceObj),
-                config.getRegistry().update
+                apply(config.getRegistry().update, previousDevice)
             ],
             callback
         );
@@ -371,7 +371,7 @@ function updateRegisterDeviceNgsi2(deviceObj, entityInfoUpdated, callback) {
                 apply(
                     config.getRegistry().get,
                     deviceObj.id,
-                    deviceObj.apikey,
+                    previousDevice.apikey,
                     deviceObj.service,
                     deviceObj.subservice
                 ),
@@ -380,7 +380,7 @@ function updateRegisterDeviceNgsi2(deviceObj, entityInfoUpdated, callback) {
                 apply(combineWithNewDevice, deviceObj),
                 apply(registrationUtils.sendRegistrations, false),
                 apply(registrationUtils.processContextRegistration, deviceObj),
-                config.getRegistry().update
+                apply(config.getRegistry().update, previousDevice)
             ],
             callback
         );

package/lib/services/ngsi/entities-NGSI-LD.js

@@ -341,7 +341,7 @@ function generateNGSILDOperationHandler(operationName, entityName, typeInformati
         } else if (
             response &&
             operationName === 'update' &&
-            (response.statusCode === 200 || response.statusCode === 204)
+            (response.statusCode === 200 || response.statusCode === 204 || response.statusCode === 201)
         ) {
             logger.info(context, 'Received the following response from the CB: Value updated successfully\n');
             alarms.release(constants.ORION_ALARM);