iotagent-node-lib 4.4.0 → 4.6.0

package/doc/api.md

@@ -10,8 +10,9 @@
         -   [Devices](#devices)
         -   [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)
+    -   [Device to NGSI Mapping](#device-to-ngsi-mapping)
+    -   [Device autoprovision and entity creation](#device-autoprovision-and-entity-creation)
+    -   [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)
@@ -26,12 +27,18 @@
         -   [Examples of JEXL expressions](#examples-of-jexl-expressions)
         -   [Available functions](#available-functions)
         -   [Expressions with multiple transformations](#expressions-with-multiple-transformations)
+        -   [Expression support in metadata](#expression-support-in-metadata)
     -   [Measurement transformation](#measurement-transformation)
         -   [Measurement transformation definition](#measurement-transformation-definition)
         -   [Measurement transformation execution](#measurement-transformation-execution)
         -   [Measurement transformation order](#measurement-transformation-order)
         -   [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id)
-    -   [Timestamp Processing](#timestamp-processing)
+    -   [Command execution](#command-execution)
+        -   [Triggering commands](#triggering-commands)
+        -   [Command reception](#command-reception)
+        -   [Command confirmation](#command-confirmation)
+    -   [TimeInstant and Timestamp flag](#timeinstant-and-timestamp-flag)
+    -   [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)
@@ -43,10 +50,10 @@
     -   [Config group API](#config-group-api)
         -   [Config group datamodel](#config-group-datamodel)
         -   [Config group operations](#config-group-operations)
-            -   [Retrieve config groups `GET /iot/services`](#retrieve-config-groups-get-iotservices)
-            -   [Create config group `POST /iot/services`](#create-config-group-post-iotservices)
-            -   [Modify config group `PUT /iot/services`](#modify-config-group-put-iotservices)
-            -   [Remove config group `DELETE /iot/services`](#remove-config-group-delete-iotservices)
+            -   [Retrieve config groups `GET /iot/groups`](#retrieve-config-groups-get-iotgroups)
+            -   [Create config group `POST /iot/groups`](#create-config-group-post-iotgroups)
+            -   [Modify config group `PUT /iot/groups`](#modify-config-group-put-iotgroups)
+            -   [Remove config group `DELETE /iot/groups`](#remove-config-group-delete-iotgroups)
     -   [Device API](#device-api)
         -   [Device datamodel](#device-datamodel)
         -   [Device operations](#device-operations)
@@ -63,6 +70,8 @@
             -   [Retrieve log level `GET /admin/log`](#retrieve-log-level-get-adminlog)
         -   [About operations](#about-operations)
             -   [List IoTA Information `GET /iot/about`](#list-iota-information-get-iotabout)
+        -   [Metrics](#metrics)
+            -   [Retrieve metrics `GET /metrics`](#retrieve-metrics-get-metrics)
 
 <!-- /TOC -->
 
@@ -127,9 +136,9 @@ For every config group, the pair (resource, apikey) _must_ be unique (as it is u
 which device). Those operations of the API targeting specific resources will need the use of the `resource` and `apikey`
 parameters to select the appropriate instance.
 
-Config groups can be created with preconfigured sets of attributes, service information, security information and other
-parameters. The specific parameters that can be configured for a given config group are described in the
-[Config group datamodel](#config-group-datamodel) section.
+Config groups can be created with preconfigured sets of attributes, service and subservice information, security
+information and other parameters. The specific parameters that can be configured for a given config group are described
+in the [Config group datamodel](#config-group-datamodel) section.
 
 ### Devices
 
@@ -155,7 +164,7 @@ parameters defined at device level in database, the parameters are inherit from
 
 ### Uniqueness of groups and devices
 
-Group service uniqueness is defined by the combination of: service, subservice and apikey
+Group uniqueness is defined by the combination of: service, subservice, resource and apikey
 
 Device uniqueness is defined by the combination of: service, subservice, device_id and apikey. Note that several devices
 with the same device_id are allowed in the same service and subservice as long as their apikeys are different.
@@ -170,32 +179,47 @@ applies to autoprovisioned attributes and is also available at JEXL context with
 
 In case of provisioning attributes using `id` or `type` as names (please don't do that ;), they are ignored.
 
-## Entity attributes
+## Device to NGSI Mapping
 
-In the config group/device model there are four list of attributes with different purpose to configure how the
-information coming from the device (measures) is mapped to the Context Broker attributes:
+The way to map the information coming or going to the device to the NGSI attributes is defined in the group or device.
+It is possible to define the entity type and the entity ID that a device will use in the Context Broker. It can be
+configured for a single device in the device provisioning, or it can be defined for all the devices in a group.
+
+The entity type should be defined both in the group and in the device, but the entity name (entity ID) is not defined in
+the group. In that case, if there is no a existing device the same device ID, the entity name of the device generated
+will be a concatenation of the entity type and the device ID (I.E: `entityType:device_id`). It is possible to define the
+entity name as an expression, using the [Expression Language](#expression-language-support) through the `entityNameExp`
+attribute in the group.
+
+It is also possible to configure how each of the measures obtained from the device is mapped to different attributes.
+The name and type of the attribute is configured by the user (globally for all the devices in the group or in a per
+device preprovisioning). Device measures can have four different behaviors:
 
 -   **`attributes`**: Are measures that are pushed from the device to the IoT agent. This measure changes will be sent
     to the Context Broker as updateContext requests over the device entity. NGSI queries to the context broker will be
     resolved in the Broker database. For each attribute, its `name` and `type` must be provided. Additional `metadata`
-    is optional.
+    is optional. They are called internally as _active attributes_.
 
 -   **`lazy`**: Passive measures that are pulled from the device to the IoT agent. When a request for data from a lazy
-    attribute arrives to the Context Broker, it forwards the request to the Context Provider of that entity, in this
-    case the IoT Agent. The IoT Agent will then ask the device for the information needed, transform that information to
-    a NGSI format and return it to the Context Broker. This operation will be synchronous from the customer perspective:
-    the Context Broker won't return a response until the device has returned its response to the IoT Agent. For each
-    attribute, its `name` and `type` must be provided.
+    attribute arrives to the Context Broker, it forwards the request to the IoT Agent (that behaves as NGSI Context
+    Provider for all the lazy attributes or commands). The IoT Agent will then ask the device for the information
+    needed, transform that information to a NGSI format and return it to the Context Broker. This operation will be
+    synchronous from the customer perspective: the Context Broker won't return a response until the device has returned
+    its response to the IoT Agent. For each attribute, its `name` and `type` must be provided. They are called
+    internally as _lazy attributes_.
 
 -   **`static`**: It is static attributes that are persisted in the Context Broker. They are not updated by the device,
     but they can be modified by the user. They are useful to store information about the device that is not updated by
     the device itself. For instance, a `location` static attribute is can be used to store the location of a fixed
     device.
 
--   **`commands`**: Commands are actions that can be invoked in the device. They are similar to attributes, but they are
-    not updated by the device. They are updated by the Context Broker, and the IoT Agent will be in charge of
-    translating the updateContext request to the proper action in the device. Two additional attributes are created for
-    each command: `status` and `info`. For each command, its `name` and `type` must be provided.
+-   **`commands`**: Commands are actions that can be invoked in the device. They are entity attributes, but they are not
+    updated by the device, they are updated by the Context Broker. In this case, the interaction will begin by setting
+    an attribute in the device's entity, for which the IoT Agent will be regitered as Context Provider. The IoT Agent
+    will return an immediate response to the Context Broker, and will be held responsible of contacting the device to
+    perform the command itself using the device specific protocol. Special `status` and `info` attributes should be
+    update. For each command, its `name` and `type` must be provided. For further information, please refer to
+    [Command execution](#command-execution) section.
 
 All of them have the same syntax, a list of objects with the following attributes:
 
@@ -236,6 +260,17 @@ Note that, when information coming from devices, this means measures, are not de
 device, the IoT agent will store that information into the destination entity using the same attribute name than the
 measure name, unless `explicitAttrs` is defined. Measures `id` or `type` names are invalid, and will be ignored.
 
+## Device autoprovision and entity creation
+
+For those agents that uses IoTA Node LIB version 3.4.0 or higher, you should consider that the entity is not created
+automatically when a device is created. This means that all entities into the Context Broker are created when data
+arrives from a device, no matter if the device is explicitly provisioned (via
+[device provisioning API](#create-device-post-iotdevices)) or autoprovisioned.
+
+If for any reason you need the entity at CB before the first measure of the corresponding device arrives to the
+IOTAgent, you can create it in advance using the Context Broker
+[NGSI v2 API](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md).
+
 ## Multientity support
 
 The IOTA is able to persists measures coming from a single device to more than one entity, declaring the target entities
@@ -286,69 +321,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"}
-          }
-        }
-     ],
-     "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"}
+    "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" }
             }
-          },
-     ]
-   }
-```
-
-Metadata could also has `expression` like attributes in order to expand it:
-
-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"}
-          }
         }
-     ],
-     "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"] },
+                "alias": { "type": "Text", "value": "lamp" }
             }
-          },
-     ]
-   }
+        }
+    ]
+}
 ```
 
 ### NGSI-LD data and metadata considerations
@@ -458,6 +461,9 @@ 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):
@@ -546,6 +552,7 @@ really useful when you need to adapt measure (for example, to change the units,
 of expression in the IoT Agent are:
 
 -   [Measurement transformation](#measurement-transformation).
+-   [Metadata](#expression-support-in-metadata)
 -   Commands payload transformation (push and pull).
 -   Auto provisioned devices entity name. It is configured at config Group level by setting the `entityNameExp`
     parameter. It defines an expression to generate the Entity Name for autoprovisioned devices.
@@ -558,12 +565,18 @@ expression. In all cases the following data is available to all expressions:
 -   `id`: device ID
 -   `entity_name`: NGSI entity Name (principal)
 -   `type`: NGSI entity type (principal)
--   `service`: device service
--   `subservice`: device subservice
+-   `service`: device service (`Fiware-Service`)
+-   `subservice`: device subservice (`Fiware-ServicePath`)
 -   `staticAttributes`: static attributes defined in the device or config group
 
 Additionally, for attribute expressions (`expression`, `entity_name`), `entityNameExp` and metadata expressions
-(`expression`) measures are available in the **context** used to evaluate them.
+(`expression`) the following is available in the **context** used to evalute:
+
+-   measures, as `<AttributeName>`
+-   metadata (both for attribute measurement in the case of NGSI-v2 measurements and static attribute) are available in
+    the **context** under the following convention: `metadata.<AttributeName>.<MetadataName>` or
+    `metadata.<StaticAttributeName>.<MetadataName>` in a similar way of defined for
+    [Context Broker](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#metadata-support)
 
 ### Examples of JEXL expressions
 
@@ -609,50 +622,52 @@ to incorporate new transformations from the IoT Agent configuration file in a fa
 
 Current common transformation set:
 
-| JEXL Transformation                  | Equivalent JavaScript Function                                                                                          |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| jsonparse: (str)                     | `JSON.parse(str);`                                                                                                      |
-| jsonstringify: (obj)                 | `JSON.stringify(obj);`                                                                                                  |
-| indexOf: (val, char)                 | `String(val).indexOf(char);`                                                                                            |
-| length: (val)                        | `String(val).length;`                                                                                                   |
-| trim: (val)                          | `String(val).trim();`                                                                                                   |
-| substr: (val, int1, int2)            | `String(val).substr(int1, int2);`                                                                                       |
-| addreduce: (arr)                     | <code>arr.reduce((i, v) &vert; i + v));</code>                                                                          |
-| lengtharray: (arr)                   | `arr.length;`                                                                                                           |
-| typeof: (val)                        | `typeof val;`                                                                                                           |
-| isarray: (arr)                       | `Array.isArray(arr);`                                                                                                   |
-| isnan: (val)                         | `isNaN(val);`                                                                                                           |
-| parseint: (val)                      | `parseInt(val);`                                                                                                        |
-| parsefloat: (val)                    | `parseFloat(val);`                                                                                                      |
-| toisodate: (val)                     | `new Date(val).toISOString();`                                                                                          |
-| timeoffset:(isostr)                  | `new Date(isostr).getTimezoneOffset();`                                                                                 |
-| tostring: (val)                      | `val.toString();`                                                                                                       |
-| urlencode: (val)                     | `encodeURI(val);`                                                                                                       |
-| urldecode: (val)                     | `decodeURI(val);`                                                                                                       |
-| replacestr: (str, from, to)          | `str.replace(from, to);`                                                                                                |
-| replaceregexp: (str, reg, to)        | `str.replace(new RegExp(reg), to);`                                                                                     |
-| replaceallstr: (str, from, to)       | `str.replaceAll(from, to);`                                                                                             |
-| replaceallregexp: (str, reg, to)     | `str.replaceAll(new RegExp(reg,"g"), to);`                                                                              |
-| split: (str, ch)                     | `str.split(ch);`                                                                                                        |
-| joinarrtostr: (arr, ch)              | `arr.join(ch);`                                                                                                         |
-| concatarr: (arr, arr2)               | `arr.concat(arr2);`                                                                                                     |
-| mapper: (val, values, choices)       | <code>choices[values.findIndex((target) &vert; target == val)]);</code>                                                 |
-| thmapper: (val, values, choices)     | <code>choices[values.reduce((acc,curr,i,arr) &vert; (acc==0)&vert;&vert;acc?acc:val<=curr?acc=i:acc=null,null)];</code> |
-| bitwisemask: (i,mask,op,shf)         | <code>(op==="&"?parseInt(i)&mask: op==="&vert;"?parseInt(i)&vert;mask: op==="^"?parseInt(i)^mask:i)>>shf;</code>        |
-| slice: (arr, init, end)              | `arr.slice(init,end);`                                                                                                  |
-| addset: (arr, x)                     | <code>{ return Array.from((new Set(arr)).add(x)) }</code>                                                               |
-| removeset: (arr, x)                  | <code>{ let s = new Set(arr); s.delete(x); return Array.from(s) }</code>                                                |
-| touppercase: (val)                   | `String(val).toUpperCase()`                                                                                             |
-| tolowercase: (val)                   | `String(val).toLowerCase()`                                                                                             |
-| round: (val)                         | `Math.round(val)`                                                                                                       |
-| floor: (val)                         | `Math.floor(val)`                                                                                                       |
-| ceil: (val)                          | `Math.ceil(val)`                                                                                                        |
-| tofixed: (val, decimals)             | `Number.parseFloat(val).toFixed(decimals)`                                                                              |
-| gettime: (d)                         | `new Date(d).getTime()`                                                                                                 |
-| toisostring: (d)                     | `new Date(d).toISOString()`                                                                                             |
-| localestring: (d, timezone, options) | `new Date(d).toLocaleString(timezone, options)`                                                                         |
-| now: ()                              | `Date.now()`                                                                                                            |
-| hextostring: (val)                   | `new TextDecoder().decode(new Uint8Array(val.match(/.{1,2}/g).map(byte => parseInt(byte, 16))))`                        |
+| JEXL Transformation                  | Equivalent JavaScript Function                                                                                           |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| jsonparse: (str)                     | `JSON.parse(str);`                                                                                                       |
+| jsonstringify: (obj)                 | `JSON.stringify(obj);`                                                                                                   |
+| indexOf: (val, char)                 | `String(val).indexOf(char);`                                                                                             |
+| length: (val)                        | `String(val).length;`                                                                                                    |
+| trim: (val)                          | `String(val).trim();`                                                                                                    |
+| substr: (val, int1, int2)            | `String(val).substr(int1, int2);`                                                                                        |
+| addreduce: (arr)                     | <code>arr.reduce((i, v) &vert; i + v));</code>                                                                           |
+| lengtharray: (arr)                   | `arr.length;`                                                                                                            |
+| typeof: (val)                        | `typeof val;`                                                                                                            |
+| isarray: (arr)                       | `Array.isArray(arr);`                                                                                                    |
+| isnan: (val)                         | `isNaN(val);`                                                                                                            |
+| parseint: (val)                      | `parseInt(val);`                                                                                                         |
+| parsefloat: (val)                    | `parseFloat(val);`                                                                                                       |
+| toisodate: (val)                     | `new Date(val).toISOString();`                                                                                           |
+| timeoffset:(isostr)                  | `new Date(isostr).getTimezoneOffset();`                                                                                  |
+| tostring: (val)                      | `val.toString();`                                                                                                        |
+| urlencode: (val)                     | `encodeURI(val);`                                                                                                        |
+| urldecode: (val)                     | `decodeURI(val);`                                                                                                        |
+| replacestr: (str, from, to)          | `str.replace(from, to);`                                                                                                 |
+| replaceregexp: (str, reg, to)        | `str.replace(new RegExp(reg), to);`                                                                                      |
+| replaceallstr: (str, from, to)       | `str.replaceAll(from, to);`                                                                                              |
+| replaceallregexp: (str, reg, to)     | `str.replaceAll(new RegExp(reg,"g"), to);`                                                                               |
+| split: (str, ch)                     | `str.split(ch);`                                                                                                         |
+| joinarrtostr: (arr, ch)              | `arr.join(ch);`                                                                                                          |
+| concatarr: (arr, arr2)               | `arr.concat(arr2);`                                                                                                      |
+| mapper: (val, values, choices)       | <code>choices[values.findIndex((target) &vert; target == val)]);</code>                                                  |
+| thmapper: (val, values, choices)     | <code>choices[values.reduce((acc,curr,i,arr) &vert; (acc==0)&vert;&vert;acc?acc:val<=curr?acc=i:acc=null,null)];</code>  |
+| bitwisemask: (i,mask,op,shf)         | <code>(op==="&"?parseInt(i)&mask: op==="&vert;"?parseInt(i)&vert;mask: op==="^"?parseInt(i)^mask:i)>>shf;</code>         |
+| slice: (arr, init, end)              | `arr.slice(init,end);`                                                                                                   |
+| addset: (arr, x)                     | <code>{ return Array.from((new Set(arr)).add(x)) }</code>                                                                |
+| removeset: (arr, x)                  | <code>{ let s = new Set(arr); s.delete(x); return Array.from(s) }</code>                                                 |
+| touppercase: (val)                   | `String(val).toUpperCase()`                                                                                              |
+| tolowercase: (val)                   | `String(val).toLowerCase()`                                                                                              |
+| round: (val)                         | `Math.round(val)`                                                                                                        |
+| floor: (val)                         | `Math.floor(val)`                                                                                                        |
+| ceil: (val)                          | `Math.ceil(val)`                                                                                                         |
+| tofixed: (val, decimals)             | `Number.parseFloat(val).toFixed(decimals)`                                                                               |
+| gettime: (d)                         | `new Date(d).getTime()`                                                                                                  |
+| toisostring: (d)                     | `new Date(d).toISOString()`                                                                                              |
+| localestring: (d, timezone, options) | `new Date(d).toLocaleString(timezone, options)`                                                                          |
+| now: ()                              | `Date.now()`                                                                                                             |
+| hextostring: (val)                   | `new TextDecoder().decode(new Uint8Array(val.match(/.{1,2}/g).map(byte => parseInt(byte, 16))))`                         |
+| valuePicker: (val,pick)              | <code>valuePicker: (val,pick) => Object.entries(val).filter(([_, v]) => v === pick).map(([k, _]) => k)</code>            |
+| valuePickerMulti: (val,pick)         | <code>valuePickerMulti: (val,pick) => Object.entries(val).filter(([_, v]) => pick.includes(v)).map(([k, _]) => k)</code> |
 
 You have available this [JEXL interactive playground][99] with all the transformations already loaded, in which you can
 test all the functions described above.
@@ -681,6 +696,50 @@ Another example using functions that return more than one value is the following
 
 For a location value `"40.4165, -3.70256"`, the result of the previous expression will be `-3.70256`.
 
+### Expression support in metadata
+
+Metadata could also has `expression` like attributes in order to expand it:
+
+e.g.:
+
+```json
+{
+    "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" }
+            }
+        }
+    ]
+}
+```
+
+Note that there is no order into metadata structure and there is no warranty about which metadata attribute expression
+will be evaluated first.
+
 ## Measurement transformation
 
 The IoTAgent Library provides support for measurement transformation using a
@@ -1007,13 +1066,34 @@ Will now generate the following NGSI v2 payload:
 }
 ```
 
-## Timestamp Processing
+## TimeInstant and Timestamp flag
+
+As part of the device to entity mapping process, the IoT Agent creates and updates automatically a special timestamp
+attribute called `TimeInstant`. This timestamp is represented as two different properties of the mapped entity:
 
-Timestamp processing done by IOTA is as follows:
+-   An attribute `TimeInstant` is added to updated entities in the case of NGSI-v2, which captures as an ISO8601
+    timestamp when the associated measurement was observed. With NGSI-LD, the Standard `observedAt` property is used
+    instead
 
--   An attribute `TimeInstant` is added to updated entities
--   In the case of NGSI-v2, a `TimeInstant` metadata is added in each updated attribute. With NGSI-LD, the Standard
-    `observedAt` property-of-a-property is used instead.
+-   With NGSI-v2, an attribute metadata named `TimeInstant` per active or lazy attribute mapped, which captures as an
+    ISO8601 timestamp when the associated measurement (represented as attribute value) was observed. With NGSI-LD, the
+    Standard `observedAt` property-of-a-property is used instead.
+
+If timestamp is not explicily defined when sending the measures through the IoT Agent (for further details on how to
+attach timestamp information to the measures, please refer to the particular IoT Agent implementation documentation),
+the arrival time on the server when receiving the measurement will be used to generate a `TimeInstant` for both the
+entity attribute and the attribute metadata.
+
+This functionality can be turned on and off globaly through the use of the `timestamp` configuration flag or
+`IOTA_TIMESTAMP` variable as well as `timestamp` flag in device or group provision (in this case, the device or group
+level flag takes precedence over the global one). The default value is `true`.
+
+The `timestamp` configuration value used, according to the priority:
+
+1.  The one defined at device level
+2.  The one defined at group level (if not defined at device level)
+3.  The one defined at [IoTA configuration level](admin.md#timestamp) / `IOTA_TIMESTAMP` env var (if not defined at
+    group level or device level)
 
 Depending on the `timestamp` configuration and if the measure contains a value named `TimeInstant` with a correct value,
 the IoTA behaviour is described in the following table:
@@ -1027,13 +1107,6 @@ the IoTA behaviour is described in the following table:
 | Not defined            | Yes                            | TimeInstant and metadata updated with measure value    |
 | Not defined            | No                             | TimeInstant and metadata updated with server timestamp |
 
-The `timestamp` conf value used is:
-
--   The one defined at device level
--   The one defined at group level (if not defined at device level)
--   The one defined at [IoTA configuration level](admin.md#timestamp) / `IOTA_TIMESTAMP` env var (if not defined at
-    group level or device level)
-
 Some additional considerations to take into account:
 
 -   If there is an attribute which maps a measure to `TimeInstant` attribute (after
@@ -1043,6 +1116,348 @@ Some additional considerations to take into account:
 -   If the resulting `TimeInstant` not follows [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) (either from a direct
     measure of after a mapping, as described in the previous bullet) then it is refused (so a failover to server
     timestamp will take place).
+-   the timestamp of different attributes belonging to the same measurement record may not be equal.
+-   the arrival time and the measurement timestamp will not be the same in the general case (when explicitly defining
+    the timestamp in the measurement)
+-   if `timezone` field is defined as part of the provisioning of the device or group, timestamp fields will be
+    generated using it. For instance, if `timezone` is set to `America/Los_Angeles`, a possible timestamp could be
+    `2025-08-05T00:35:01.468-07:00`. If `timezone` field is not defined, by default Zulu Time Zone (UTC +0) will be
+    used. Following the previous example, timestamp could be `2015-08-05T07:35:01.468Z`.
+
+E.g.: in the case of a device that can take measurements every hour of both temperature and humidity and sends the data
+once every day, at midnight, the `TimeInstant` reported for each measurement will be the hour when that measurement was
+observed (e.g. 4:00 PM), while all the measurements will have an arrival time around midnight. If no timestamps were
+reported with such measurements, the `TimeInstant` attribute would take those values around midnight.
+
+## 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"
+            }
+        }
+    ]
+}
+```
+
+## Command execution
+
+This section reviews the end-to-end process to trigger and receive commands into devices. The URL paths and messages
+format is based on the [IoT Agent JSON](https://github.com/telefonicaid/iotagent-json). It may differ in the case of
+using any other IoT Agent. In that case, please refer to the specific IoTA documentation.
+
+### Triggering commands
+
+This starts the process of sending data to devices. It starts by updating an attribute into the Context Broker defined
+as `command` in the [config group](#config-group-datamodel) or in the [device provision](#device-datamodel). Commands
+attributes are created using `command` as attribute type. Also, you can define the protocol you want the commands to be
+sent (HTTP/MQTT) with the `transport` parameter at the provisioning process.
+
+For a given device provisioned with a `ping` command defined, any update on this attribute "ping" at the NGSI entity in
+the Context Broker will send a command to your device. For instance, to send the `ping` command with value
+`Ping request` you could use the following operation in the Context Broker API:
+
+```
+PUT /v2/entities/<entity_id>/attrs/ping?type=<entity_type>
+
+{
+  "value": "Ping request",
+  "type": "command"
+}
+
+```
+
+It is important to note that parameter `type`, with the entity type must be included.
+
+Context Broker API is quite flexible and allows to update an attribute in several ways. Please have a look to the
+[Orion API](<[http://telefonicaid.github.io/fiware-orion/api/v2/stable](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md)>)
+for details.
+
+**Important note**: don't use operations in the NGSI API with creation semantics. Otherwise, the entity/attribute will
+be created locally to Context Broker and the command will not progress to the device (and you will need to delete the
+created entity/attribute if you want to make it to work again). Thus, the following operations _must not_ be used:
+
+-   `POST /v2/entities`
+-   `POST /v2/entities/<id>/attrs`
+-   `PUT /v2/entities/<id>/attrs`
+-   `POST /v2/op/entites` with `actionType` `append`, `appendStrict` or `replace`
+
+### Command reception
+
+Once the command is triggered, it is send to the device. Depending on transport protocol, it is going to be sent to the
+device in a different way. After sending the command, the IoT Agent will have updated the value of `ping_status` to
+`PENDING` for entity into the Context Broker. Neither `ping_info` nor `ping` will be updated.
+
+#### HTTP devices
+
+**Push commands**
+
+Push commands are those that are sent to the device once the IoT Agent receives the request from the Context Broker. In
+order to send push commands it is needed to set the `"endpoint": "http://[DEVICE_IP]:[PORT]/"` in the device or group
+provision. The device is supposed to be listening for commands at that URL in a synchronous way. Make sure the device
+endpoint is reachable by the IoT Agent. Push commands are only valid for HTTP devices. For MQTT devices it is not needed
+to set the `endpoint` parameter.
+
+Considering using the IoTA-JSON Agent, and given the previous example, the device should receive a POST request to
+`http://[DEVICE_IP]:[PORT]` with the following payload:
+
+```
+POST /
+Content-Type: application/json
+
+{"ping":"Ping request"}
+```
+
+**Poll commands**
+
+Poll commands are those that are stored in the IoT Agent waiting to be retrieved by the devices. This kind of commands
+are typically used for devices that doesn't have a public IP or the IP cannot be reached because of power or netkork
+constrictions. The device connects to the IoT Agent periodically to retrieve commands. In order to configure the device
+as poll commands you just need to avoid the usage of `endpoint` parameter in the device provision.
+
+Once the command request is issued to the IoT agent, the command is stored waiting to be retrieved by the device. In
+that moment, the status of the command is `"<command>_status": "PENDING"`.
+
+For HTTP devices, in order to retrieve a poll command, the need to make a GET request to the IoT Agent to the path used
+as `resource` in the provisioned group (`/iot/json` by default in IoTA-JSON if no `resource` is used) with the following
+parameters:
+
+**FIXME [#1524](https://github.com/telefonicaid/iotagent-node-lib/issues/1524)**: `resource` different to the default
+one (`/iot/json` in the case of the [IoTA-JSON](https://github.com/telefonicaid/iotagent-json)) is not working at the
+present moment, but it will when this issue gets solved.
+
+-   `k`: API key of the device.
+-   `i`: Device ID.
+-   `getCmd`: This parameter is used to indicate the IoT Agent that the device is requesting a command. It is needed to
+    set it to `1`
+
+Taking the previous example, and considering the usage of the IoTA-JSON Agent, the device should make the following
+request, being the response to this request a JSON object with the command name as key and the command value as value:
+
+**Request:**
+
+```
+GET /iot/json?k=<apikey>&i=<deviceId>&getCmd=1
+Accept: application/json
+
+```
+
+**Response:**:
+
+```
+200 OK
+Content-type: application/json
+
+{"ping":"Ping request"}
+```
+
+For IoT Agents different from IoTA-JSON it is exactly the same just changing in the request the resource by the
+corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource instead of `/iot/json`)
+and setting the correct `<apikey>` and `<deviceId>`. The response will be also different depending on the IoT Agent
+employed.
+
+**FIXME [#1524](https://github.com/telefonicaid/iotagent-node-lib/issues/1524)**: `resource` different to the default
+one (`/iot/json` in the case of the [IoTA-JSON](https://github.com/telefonicaid/iotagent-json)) is not working at the
+present moment, but it will when this issue gets solved.
+
+**Request**
+
+```
+POST /iot/json?k=<apikey>&i=<deviceId>&getCmd=1
+Content-Type: application/json
+
+{"t":25,"h":42,"l":"1299"}
+```
+
+**Response**
+
+```
+200 OK
+Content-type: application/json
+
+{"ping":"Ping request"}
+```
+
+This is also possible for IoTA-UL Agent changing in the request the resource, setting the correct `<apikey>`,
+`<deviceId>`, payload and headers.
+
+Once the command is retrieved by the device the status is updated to `"<command>_status": "DELIVERED"`. Note that status
+`DELIVERED` only make sense in the case of poll commands. In the case of push command it cannot happen.
+
+#### MQTT devices
+
+For MQTT devices, it is not needed to declare an endpoint (i.e. if included in the provisioning request, it is not
+used). The device is supposed to be subscribed to the following MQTT topic where the IoT Agent will publish the command:
+
+```
+/<apiKey>/<deviceId>/cmd
+```
+
+In the case of using the IoTA-JSON Agent, the device should subscribe to the previous topic where it is going to receive
+a message like the following one when a command is triggered in the Context Broker like the previous step:
+
+```json
+{ "ping": "Ping request" }
+```
+
+Please note that the device should subscribe to the broker using the disabled clean session mode (enabled using
+`--disable-clean-session` option CLI parameter in `mosquitto_sub`). This option means that all of the subscriptions for
+the device will be maintained after it disconnects, along with subsequent QoS 1 and QoS 2 commands that arrive. When the
+device reconnects, it will receive all of the queued commands.
+
+### Command confirmation
+
+Once the command is completely processed by the device, it should return the result of the command to the IoT Agent.
+This result will be progressed to the Context Broker where it will be stored in the `<command>_info` attribute. The
+status of the command will be stored in the `<command>_status` attribute (`OK` if everything goes right).
+
+For the IoTA-JSON, the payload of the confirmation message must be a JSON object with name of the command as key and the
+result of the command as value. For other IoT Agents, the payload must follow the corresponding protocol. For a given
+`ping` command, with a command result `status_ok`, the response payload should be:
+
+```JSON
+{"ping":"status_ok"}
+```
+
+Eventually, once the device makes the response request the IoTA would update the attributes `ping_status` to `OK` and
+`ping_info` to `status_ok` for the previous example.
+
+#### HTTP
+
+In order confirm the command execution, the device must make a POST request to the IoT Agent with the result of the
+command as payload, no matter if it is a push or a poll command. Following with the IoTAgent JSON case, the request must
+be made to the `/iot/json/commands`, this way:
+
+```
+POST /iot/json/commands?k=<apikey>&i=<deviceId>
+Content-Type: application/json
+Accept: application/json
+
+{"ping":"status_ok"}
+```
+
+#### MQTT
+
+The device should publish the result of the command (`{"ping":"status_ok"}` in the previous example) to a topic
+following the next pattern:
+
+```
+/<iotagent-protocol>/<apiKey>/<deviceId>/cmdexe
+```
+
+The IoTA is subscribed to that topic, so it gets the result of the command. When this happens, the status is updated
+to`"<command>_status": "OK"`. Also the result of the command delivered by the device is stored in the `<command>_info`
+attribute.
 
 ## Overriding global Context Broker host
 
@@ -1312,7 +1727,7 @@ Config group is represented by a JSON object with the following fields:
 
 The following actions are available under the config group endpoint:
 
-#### Retrieve config groups `GET /iot/services`
+#### Retrieve config groups `GET /iot/groups`
 
 List all the config groups for the given `fiware-service` and `fiware-servicepath`. The config groups that match the
 `fiware-servicepath` are returned in any other case.
@@ -1336,14 +1751,14 @@ Successful operations return `Content-Type` header with `application/json` value
 
 _**Response payload**_
 
-A JSON object with a services field that contains an array of services that match the request. See the
-[config group datamodel](#service-group-datamodel) for more information.
+A JSON object with a `groups` field that contains an array of groups that match the request. See the
+[config group datamodel](#config-group-datamodel) for more information.
 
 Example:
 
 ```json
 {
-    "services": [
+    "groups": [
         {
             "resource": "/deviceTest",
             "apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
@@ -1380,7 +1795,7 @@ Example:
 }
 ```
 
-#### Create config group `POST /iot/services`
+#### Create config group `POST /iot/groups`
 
 Creates a set of config groups for the given service and service path. The service and subservice information will taken
 from the headers, overwritting any preexisting values.
@@ -1394,14 +1809,14 @@ _**Request headers**_
 
 _**Request payload**_
 
-A JSON object with a `services` field. The value is an array of config groups objects to create. See the
-[config group datamodel](#service-group-datamodel) for more information.
+A JSON object with a `groups` field. The value is an array of config groups objects to create. See the
+[config group datamodel](#config-group-datamodel) for more information.
 
 Example:
 
 ```json
 {
-    "services": [
+    "groups": [
         {
             "resource": "/deviceTest",
             "apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
@@ -1435,7 +1850,7 @@ _**Response headers**_
 
 Successful operations return `Content-Type` header with `application/json` value.
 
-#### Modify config group `PUT /iot/services`
+#### Modify config group `PUT /iot/groups`
 
 Modifies the information of a config group, identified by the `resource` and `apikey` query parameters. Takes a service
 group body as the payload. The body does not have to be complete: for incomplete bodies, just the attributes included in
@@ -1457,8 +1872,8 @@ _**Request headers**_
 
 _**Request payload**_
 
-A JSON object with the config group information to be modified. See the
-[config group datamodel](#service-group-datamodel) for more information.
+A JSON object with the config group information to be modified. See the [config group datamodel](config-group-datamodel)
+for more information.
 
 Example:
 
@@ -1475,7 +1890,7 @@ _**Response code**_
 -   400 MISSING_HEADERS if any of the mandatory headers is not present.
 -   500 SERVER ERROR if there was any error not contemplated above.:
 
-#### Remove config group `DELETE /iot/services`
+#### Remove config group `DELETE /iot/groups`
 
 Removes a config group, identified by the `resource` and `apikey` query parameters.
 
@@ -1895,6 +2310,57 @@ Example:
 }
 ```
 
+### Metrics
+
+The IoT Agent Library exposes a [openmetrics-compatible](https://github.com/OpenObservability/OpenMetrics) endpoint for
+telemetry collectors to gather application statistics.
+
+#### Retrieve metrics `GET /metrics`
+
+_**Response code**_
+
+-   `200` `OK` if successful.
+-   `406` `Wrong Accept Header` If accept format is not supported.
+-   `500` `SERVER ERROR` if there was any error not contemplated above.
+
+_**Response body**_
+
+Returns the current value of the server stats,
+
+-   If `Accept` header contains `application/openmetrics-text; version=(1.0.0|0.0.1)`, the response has content-type
+    `application/openmetrics-text; version=<the requested version>; charset=utf-8`
+-   Else, If `Accept` header is missing or supports `text/plain` (explicitly or by `*/*`) , the response has
+    content-type `text/plain; version=0.0.4; charset=utf-8` (legacy format for [prometheus](https://prometheus.io))
+-   In any other case, returns an error message with `406` status.
+
+For the kind of metrics exposed by the application, the actual payload itself is completely the same for both
+content-types, and follows the openmetrics specification, e.g:
+
+```
+# HELP deviceCreationRequests global metric for deviceCreationRequests
+# TYPE deviceCreationRequests counter
+deviceCreationRequests 0
+# HELP deviceRemovalRequests global metric for deviceRemovalRequests
+# TYPE deviceRemovalRequests counter
+deviceRemovalRequests 0
+# HELP measureRequests global metric for measureRequests
+# TYPE measureRequests counter
+measureRequests 0
+# HELP raiseAlarm global metric for raiseAlarm
+# TYPE raiseAlarm counter
+raiseAlarm 0
+# HELP releaseAlarm global metric for releaseAlarm
+# TYPE releaseAlarm counter
+releaseAlarm 0
+# HELP updateEntityRequestsOk global metric for updateEntityRequestsOk
+# TYPE updateEntityRequestsOk counter
+updateEntityRequestsOk 2
+# HELP updateEntityRequestsError global metric for updateEntityRequestsError
+# TYPE updateEntityRequestsError counter
+updateEntityRequestsError 5
+# EOF
+```
+
 [1]:
     https://czosel.github.io/jexl-playground/#/?context=%7B%0A%20%20%22longitude%22%3A%205%2C%0A%20%20%22latitude%22%3A%2037%2C%0A%20%20%22level%22%3A223%0A%7D&input=%7Bcoordinates%3A%20%5Blongitude%2Clatitude%5D%2C%20type%3A%20'Point'%7D&transforms=%7B%0A%7D
 [2]: