iotagent-node-lib 2.18.0 → 2.21.0

package/doc/installationguide.md

@@ -56,9 +56,10 @@ allowing the computer to interpret the rest of the data with more clarity and de
 }
 ```
 
-Under mixed mode, **NGSI v2** payloads are used for context broker communications by default, but this payload may also be switched
-to **NGSI LD** at service group or device provisioning time using the `ngsiVersion` field in the provisioning API.
-The `ngsiVersion` field switch may be added at either group or device level, with the device level overriding the group setting.
+Under mixed mode, **NGSI v2** payloads are used for context broker communications by default, but this payload may also
+be switched to **NGSI LD** at service group or device provisioning time using the `ngsiVersion` field in the
+provisioning API. The `ngsiVersion` field switch may be added at either group or device level, with the device level
+overriding the group setting.
 
 -   **server**: configuration used to create the Context Server (port where the IoT Agent will be listening as a Context
     Provider and base root to prefix all the paths). The `port` attribute is required. If no `baseRoot` attribute is
@@ -159,7 +160,7 @@ used for the same purpose. For instance:
 
 ```javascript
 {
-    type: "mongodb";
+    type: 'mongodb';
 }
 ```
 
@@ -241,8 +242,8 @@ used for the same purpose. For instance:
 -   **singleConfigurationMode**: enables the Single Configuration mode for backwards compatibility (see description in
     the Overview). Default to false.
 -   **timestamp**: if this flag is activated:
-    -   For NGSI-v2, the IoT Agent will add a `TimeInstant` metadata attribute to all the attributes updated from
-        device information. This flag is overwritten by `timestamp` flag in group or device
+    -   For NGSI-v2, the IoT Agent will add a `TimeInstant` metadata attribute to all the attributes updated from device
+        information. This flag is overwritten by `timestamp` flag in group or device
     -   With NGSI-LD, the standard `observedAt` property-of-a-property is created instead.
 -   **defaultResource**: default string to use as resource for the registration of new Configurations (if no resource is
     provided).
@@ -273,10 +274,11 @@ used for the same purpose. For instance:
     NGSILD-Path has not yet been included in the NGSI-LD standard (it has been proposed for the next update of the
     standard, but the final decision has yet been confirmed), take into account it could change
 -   **explicitAttrs**: if this flag is activated, only provisioned attributes will be processed to Context Broker. This
-    flag is overwritten by `explicitAttrs` flag in group or device provision.
+    flag is overwritten by `explicitAttrs` flag in group or device provision. Additionally `explicitAttrs` can be used
+    to define which meassures defined in JSON/JEXL array will be propagated to NGSI interface.
 -   **defaultEntityNameConjunction**: the default conjunction string used to compose a default `entity_name` when is not
-    provided at device provisioning time; in that case `entity_name` is composed by `type` + `:` + `device_id`.
-    Default value is `:`. This value is overwritten by `defaultEntityNameConjunction` in group provision.
+    provided at device provisioning time; in that case `entity_name` is composed by `type` + `:` + `device_id`. Default
+    value is `:`. This value is overwritten by `defaultEntityNameConjunction` in group provision.
 -   **relaxTemplateValidation**: if this flag is activated, `objectId` attributes for incoming devices are not
     validated, and may exceptionally include characters (such as semi-colons) which are
     [forbidden](https://fiware-orion.readthedocs.io/en/master/user/forbidden_characters/index.html) according to the
@@ -291,61 +293,61 @@ with container-based technologies, like Docker, Heroku, etc...
 The following table shows the accepted environment variables, as well as the configuration parameter the variable
 overrides.
 
-| Environment variable             | Configuration attribute         |
-| :------------------------------- | :------------------------------ |
-| IOTA_CB_URL                      | `contextBroker.url`             |
-| IOTA_CB_HOST                     | `contextBroker.host`            |
-| IOTA_CB_PORT                     | `contextBroker.port`            |
-| IOTA_CB_NGSI_VERSION             | `contextBroker.ngsiVersion`     |
-| IOTA_NORTH_HOST                  | `server.host`                   |
-| IOTA_NORTH_PORT                  | `server.port`                   |
-| IOTA_PROVIDER_URL                | `providerUrl`                   |
-| IOTA_AUTH_ENABLED                | `authentication.enabled`        |
-| IOTA_AUTH_TYPE                   | `authentication.type`           |
-| IOTA_AUTH_HEADER                 | `authentication.header`         |
-| IOTA_AUTH_URL                    | `authentication.url`            |
-| IOTA_AUTH_HOST                   | `authentication.host`           |
-| IOTA_AUTH_PORT                   | `authentication.port`           |
-| IOTA_AUTH_USER                   | `authentication.user`           |
-| IOTA_AUTH_PASSWORD               | `authentication.password`       |
-| IOTA_AUTH_CLIENT_ID              | `authentication.clientId`       |
-| IOTA_AUTH_CLIENT_SECRET          | `authentication.clientSecret`   |
-| IOTA_AUTH_TOKEN_PATH             | `authentication.tokenPath`      |
-| IOTA_AUTH_PERMANENT_TOKEN        | `authentication.permanentToken` |
-| IOTA_REGISTRY_TYPE               | `deviceRegistry.type`           |
-| IOTA_LOG_LEVEL                   | `logLevel`                      |
-| IOTA_TIMESTAMP                   | `timestamp`                     |
-| IOTA_IOTAM_URL                   | `iotManager.url`                |
-| IOTA_IOTAM_HOST                  | `iotManager.host`               |
-| IOTA_IOTAM_PORT                  | `iotManager.port`               |
-| IOTA_IOTAM_PATH                  | `iotManager.path`               |
-| IOTA_IOTAM_AGENTPATH             | `iotManager.agentPath`          |
-| IOTA_IOTAM_PROTOCOL              | `iotManager.protocol`           |
-| IOTA_IOTAM_DESCRIPTION           | `iotManager.description`        |
-| IOTA_MONGO_HOST                  | `mongodb.host`                  |
-| IOTA_MONGO_PORT                  | `mongodb.port`                  |
-| IOTA_MONGO_DB                    | `mongodb.db`                    |
-| IOTA_MONGO_REPLICASET            | `mongodb.replicaSet`            |
-| IOTA_MONGO_USER                  | `mongodb.user`                  |
-| IOTA_MONGO_PASSWORD              | `mongodb.password`              |
-| IOTA_MONGO_AUTH_SOURCE           | `mongodb.authSource`            |
-| IOTA_MONGO_RETRIES               | `mongodb.retries`               |
-| IOTA_MONGO_RETRY_TIME            | `mongodb.retryTime`             |
-| IOTA_MONGO_SSL                   | `mongodb.ssl`                   |
-| IOTA_MONGO_EXTRAARGS             | `mongodb.extraArgs`             |
-| IOTA_SINGLE_MODE                 | `singleConfigurationMode`       |
-| IOTA_APPEND_MODE                 | `appendMode`                    |
-| IOTA_POLLING_EXPIRATION          | `pollingExpiration`             |
-| IOTA_POLLING_DAEMON_FREQ         | `pollingDaemonFrequency`        |
-| IOTA_AUTOCAST                    | `autocast`                      |
-| IOTA_MULTI_CORE                  | `multiCore`                     |
-| IOTA_JSON_LD_CONTEXT             | `jsonLdContext`                 |
-| IOTA_FALLBACK_TENANT             | `fallbackTenant`                |
-| IOTA_FALLBACK_PATH               | `fallbackPath`                  |
-| IOTA_DEFAULT_EXPRESSION_LANGUAGE | `defaultExpressionLanguage`     |
-| IOTA_EXPLICIT_ATTRS              | `explicitAttrs`                 |
-| IOTA_DEFAULT_ENTITY_NAME_CONJUNCTION | `defaultEntityNameConjunction` |
-| IOTA_RELAX_TEMPLATE_VALIDATION   | `relaxTemplateValidation`       |
+| Environment variable                 | Configuration attribute         |
+| :----------------------------------- | :------------------------------ |
+| IOTA_CB_URL                          | `contextBroker.url`             |
+| IOTA_CB_HOST                         | `contextBroker.host`            |
+| IOTA_CB_PORT                         | `contextBroker.port`            |
+| IOTA_CB_NGSI_VERSION                 | `contextBroker.ngsiVersion`     |
+| IOTA_NORTH_HOST                      | `server.host`                   |
+| IOTA_NORTH_PORT                      | `server.port`                   |
+| IOTA_PROVIDER_URL                    | `providerUrl`                   |
+| IOTA_AUTH_ENABLED                    | `authentication.enabled`        |
+| IOTA_AUTH_TYPE                       | `authentication.type`           |
+| IOTA_AUTH_HEADER                     | `authentication.header`         |
+| IOTA_AUTH_URL                        | `authentication.url`            |
+| IOTA_AUTH_HOST                       | `authentication.host`           |
+| IOTA_AUTH_PORT                       | `authentication.port`           |
+| IOTA_AUTH_USER                       | `authentication.user`           |
+| IOTA_AUTH_PASSWORD                   | `authentication.password`       |
+| IOTA_AUTH_CLIENT_ID                  | `authentication.clientId`       |
+| IOTA_AUTH_CLIENT_SECRET              | `authentication.clientSecret`   |
+| IOTA_AUTH_TOKEN_PATH                 | `authentication.tokenPath`      |
+| IOTA_AUTH_PERMANENT_TOKEN            | `authentication.permanentToken` |
+| IOTA_REGISTRY_TYPE                   | `deviceRegistry.type`           |
+| IOTA_LOG_LEVEL                       | `logLevel`                      |
+| IOTA_TIMESTAMP                       | `timestamp`                     |
+| IOTA_IOTAM_URL                       | `iotManager.url`                |
+| IOTA_IOTAM_HOST                      | `iotManager.host`               |
+| IOTA_IOTAM_PORT                      | `iotManager.port`               |
+| IOTA_IOTAM_PATH                      | `iotManager.path`               |
+| IOTA_IOTAM_AGENTPATH                 | `iotManager.agentPath`          |
+| IOTA_IOTAM_PROTOCOL                  | `iotManager.protocol`           |
+| IOTA_IOTAM_DESCRIPTION               | `iotManager.description`        |
+| IOTA_MONGO_HOST                      | `mongodb.host`                  |
+| IOTA_MONGO_PORT                      | `mongodb.port`                  |
+| IOTA_MONGO_DB                        | `mongodb.db`                    |
+| IOTA_MONGO_REPLICASET                | `mongodb.replicaSet`            |
+| IOTA_MONGO_USER                      | `mongodb.user`                  |
+| IOTA_MONGO_PASSWORD                  | `mongodb.password`              |
+| IOTA_MONGO_AUTH_SOURCE               | `mongodb.authSource`            |
+| IOTA_MONGO_RETRIES                   | `mongodb.retries`               |
+| IOTA_MONGO_RETRY_TIME                | `mongodb.retryTime`             |
+| IOTA_MONGO_SSL                       | `mongodb.ssl`                   |
+| IOTA_MONGO_EXTRAARGS                 | `mongodb.extraArgs`             |
+| IOTA_SINGLE_MODE                     | `singleConfigurationMode`       |
+| IOTA_APPEND_MODE                     | `appendMode`                    |
+| IOTA_POLLING_EXPIRATION              | `pollingExpiration`             |
+| IOTA_POLLING_DAEMON_FREQ             | `pollingDaemonFrequency`        |
+| IOTA_AUTOCAST                        | `autocast`                      |
+| IOTA_MULTI_CORE                      | `multiCore`                     |
+| IOTA_JSON_LD_CONTEXT                 | `jsonLdContext`                 |
+| IOTA_FALLBACK_TENANT                 | `fallbackTenant`                |
+| IOTA_FALLBACK_PATH                   | `fallbackPath`                  |
+| IOTA_DEFAULT_EXPRESSION_LANGUAGE     | `defaultExpressionLanguage`     |
+| IOTA_EXPLICIT_ATTRS                  | `explicitAttrs`                 |
+| IOTA_DEFAULT_ENTITY_NAME_CONJUNCTION | `defaultEntityNameConjunction`  |
+| IOTA_RELAX_TEMPLATE_VALIDATION       | `relaxTemplateValidation`       |
 
 Note:
 

package/doc/northboundinteractions.md

@@ -163,16 +163,15 @@ The equivalent **NGSI-LD** payload is associated to an update operation (PATCH `
 
 ```json
 {
-     "temperature":  {
-          "type": "Property",
-          "value": "23"
-      },
-      "pressure" :{
-          "type": "Property",
-          "value": "720"
-      }
+    "temperature": {
+        "type": "Property",
+        "value": "23"
+    },
+    "pressure": {
+        "type": "Property",
+        "value": "720"
+    }
 }
-
 ```
 
 #### R1 - UpdateContext (response)
@@ -285,7 +284,8 @@ This is an **NGSI-LD** response to `/ngsi-ld/v1/entities/<entity>`
 ```
 
 In this case, the response to the QueryContext is a list of responses, one for each requested entity, indicating whether
-the information has been retrieved successfully (in the HTTP Status code) and the requested Context information in the body of the response.
+the information has been retrieved successfully (in the HTTP Status code) and the requested Context information in the
+body of the response.
 
 Application level errors can be specified for each entity in this payload.
 
@@ -305,7 +305,7 @@ Context Element, but with the request as a whole.
 
 ### Scenario 1: active attributes
 
-![General ](./img/scenario1.png "Scenario 1: active attributes")
+![General ](./img/scenario1.png 'Scenario 1: active attributes')
 
 In this scenario, the interaction is started by the device, that is going to actively send a piece of data to the
 platform. When the IoTAgent receives the data, it sends it to the Context Broker through a P1 request. The Context
@@ -319,7 +319,7 @@ updating process, and can occur at any time (they are to completely different pr
 
 ### Scenario 2: lazy attributes
 
-![General ](./img/scenario2.png "Scenario 2: lazy attributes")
+![General ](./img/scenario2.png 'Scenario 2: lazy attributes')
 
 This scenario requires that the attributes that are going to be requested are marked as provided by the IoT Agent,
 through a registration process (NGSIv9). Examples of this registration process will be provided in the practical section
@@ -345,7 +345,7 @@ queries (and thus P2 and R2 payloads).
 
 ### Scenario 3: commands
 
-![General ](./img/scenario3.png "Scenario 3: commands")
+![General ](./img/scenario3.png 'Scenario 3: commands')
 
 This scenario requires that the attributes that are going to be requested are marked as provided by the IoT Agent,
 through a registration process (NGSIv9). Examples of this registration process will be provided in the practical section
@@ -359,15 +359,26 @@ use three kinds of attributes:
 -   An attribute will be used as the _input attribute_ (the attribute registered in the Context Provider). This input
     attribute can be thought of as a command issued to the IoTAgent (from here the name of the scenario) whose value is
     the set of arguments of the command. Only updateContext operations will be used to interact with this attributes.
+    Typically this attribute is of type `command`.
 
 -   Another attribute will be used as the _result attribute_. This attribute will be updated from the IoTAgent, and its
     value stored in the Context Broker. This attribute will contain the result of the command (this result can be
     information in case the command was a "information retrieval" command or the result of an action if it was an
-    "actuator command"). Typically, the name of this attribute will be the same of the input attribute, with an
-    additional sufix (`_info`).
+    "actuator command"). Initially its value is empty. Typically, the name of this attribute will be the same of the
+    input attribute, with an additional sufix (`_info`) and the type is `commandResult`.
 
 -   Another attribute with the same characteristics as the later will be used to indicate whether the command has ended
-    successfully or whether an error has been reported.
+    successfully or whether an error has been reported. Typically, the name of this attribute will be the same of the
+    input attribute, with an additional sufix (`_status`) and the type is `commandStatus`. The possible values of this
+    attribute are: `ERROR`, `EXPIRED`, `PENDING`, `DELIVERED`, `UNKNOWN` with the following meanings:
+    -   ERROR: There is a kind of error.
+    -   EXPIRED: This meens that pull command has been expired without be delivered to device according with
+        `pollingExpiration` time defined by config.
+    -   PENDING: In a PUSH command means that command has been sent to device but not device has still not respond. In a
+        PULL command means that command has been stored and device still has no ask for it.
+    -   DELIVERED: The command has been delivered to phisical device.
+    -   OK: The command has been delivered and device has respond.
+    -   UNKNOWN: This is the initial value.
 
 In this scenario, the interaction is also initiated by the User. The user starts the scenario by sending an update
 request P1 to the Context Broker, to the input attribute (1). The Context Broker redirects this same payload to the
@@ -835,7 +846,6 @@ The IoT Agent detects the selected attribute is a command, and replies to the Co
 ```json
 [
     {
-
         "type": "device",
         "id": "Dev0001",
         "switch": {
@@ -854,7 +864,6 @@ The Context Broker, forwards the same response to the user, thus replying the or
 ```json
 [
     {
-
         "type": "device",
         "id": "Dev0001",
         "switch": {
@@ -882,11 +891,11 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             "isPattern": "false",
             "id": "Dev0001",
             "switch_info": {
-                "type": "command_info",
+                "type": "commandResult",
                 "value": "Switched successfully!"
             },
             "switch_status": {
-                "type": "command_status",
+                "type": "commandStatus",
                 "value": "OK"
             }
         }
@@ -906,11 +915,11 @@ The Context Broker replies to the IoT Agent with a R1 payload (200 OK):
         "type": "device",
         "id": "Dev0001",
         "switch_info": {
-            "type": "command_info",
+            "type": "commandResult",
             "value": ""
         },
-        "switch_status":  {
-            "type": "command_status",
+        "switch_status": {
+            "type": "commandStatus",
             "value": ""
         }
     }
@@ -936,8 +945,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "attributes": [
-    	"switch_info",
-    	"switch_status"
+        "switch_info",
+        "switch_status"
     ]
 }' "https://<platform-ip>:10027/v2/op/query"
 ```
@@ -947,20 +956,18 @@ The Context Broker replies with all the desired data, in R2 format (200 OK):
 ```json
 [
     {
-
         "type": "device",
         "id": "Dev0001",
         "switch_info": {
-            "type": "command_info",
+            "type": "commandResult",
             "value": "Switched successfully!"
         },
         "switch_status": {
-            "type": "command_status",
+            "type": "commandStatus",
             "value": "OK"
         }
     }
 ]
-
 ```
 
 ### Scenario 3: commands (error)
@@ -978,11 +985,11 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             "isPattern": "false",
             "id": "Dev0001",
             "switch_info":{
-                "type": "command_info",
+                "type": "commandResult",
                 "value": "The switch could not be switched due to the following error: switch blocked"
             },
             "switch_status":{
-                "type": "command_status",
+                "type": "commandStatus",
                 "value": "ERROR"
             }
         }
@@ -999,11 +1006,11 @@ In this case, the Context Broker reply with the following response (200 OK):
         "type": "device",
         "id": "Dev0001",
         "switch_info": {
-            "type": "command_info",
+            "type": "commandResult",
             "value": ""
         },
         "switch_status": {
-            "type": "command_status",
+            "type": "commandStatus",
             "value": ""
         }
     }

package/doc/requirements.txt

@@ -0,0 +1,4 @@
+mkdocs==1.2.3
+Pygments==2.9.0
+Markdown==3.3.4
+jinja2==3.0.0

package/{docs → doc}/roadmap.md

@@ -13,7 +13,7 @@ only, and this section may be revised to provide newer information at any time.
 
 Disclaimer:
 
--   This section has been last updated in March 2020. Please take into account its content could be obsolete.
+-   This section has been last updated in March 2022. Please take into account its content could be obsolete.
 -   Note we develop this software in Agile way, so development plan is continuously under review. Thus, this roadmap has
     to be understood as rough plan of features to be done along time which is fully valid only at the time of writing
     it. This roadmap has not be understood as a commitment on features and/or dates.
@@ -25,19 +25,17 @@ Disclaimer:
 The following list of features are planned to be addressed in the short term, and incorporated in a release of the
 product:
 
--   Selectively ignore measure in the southbound interface (community)
--   JEXL support in expressions (community)
 -   cgroup literal in configuration groups management API (community)
 -   Metadata processing improvements
--   Add MongoDB authentication support
+-   Improve command functionalities (binary data + expression + mapping)
 
 ### Medium term
 
 The following list of features are planned to be addressed in the medium term, typically within the subsequent
 release(s) generated in the next 9 months after the next planned release:
 
--   Support for "delta" measures (i.e. "temperature _increased_ in 5 degress" instead of "temperature _is_ 25")
--   Removal support for NGSIv1 (which currently is deprecated)
+-   Accept JEXL Expressions for entity name in autoprovisioned devices (#1145)
+-   Refactor entities-NGSI-v2.js module (#1166)
 
 ### Long term
 
@@ -48,3 +46,20 @@ us if you wish to get involved in the implementation or influence the roadmap:
 -   Incremental introduccion of ECMAScript6 syntax (previous analysis of which sub-set of interesting aspect we want to
     take)
 -   Use the lightweight ingestion mechanism for connection oriented updates implemented in Context Broker
+-   Add support to other transport protocols (BacNET, Modbus, etc)
+
+### Features already completed
+
+The following list contains all features that were in the roadmap and have already been implemented.
+
+-   Support for "delta" measures (i.e. "temperature _increased_ in 5 degress" instead of "temperature _is_ 25")
+-   Allow to handle binary messages ([iota-ul#530](https://github.com/telefonicaid/iotagent-ul/issues/530))
+-   Removal support for NGSIv1 (#966) ([2.18.0](https://github.com/telefonicaid/iotagent-node-lib/releases/tag/2.18.0))
+-   Selectively ignore measure in the southbound interface
+    ([iotagent-json#416](https://github.com/telefonicaid/iotagent-json/issues/416),
+    [iotagent-ul#372](https://github.com/telefonicaid/iotagent-ul/issues/372))
+    ([2.13.0](https://github.com/telefonicaid/iotagent-node-lib/releases/tag/2.13.0))
+-   JEXL support in expressions (#801, #687, #868)
+    ([2.13.0](https://github.com/telefonicaid/iotagent-node-lib/releases/tag/2.13.0))
+-   Add MongoDB authentication support (#844)
+    ([2.12.0](https://github.com/telefonicaid/iotagent-node-lib/releases/tag/2.12.0))

package/doc/usermanual.md

@@ -25,7 +25,7 @@ More values will be added in the future to the library. The applications using t
 Registry just by using the following function:
 
 ```javascript
-iotagentLib.statsRegistry.add("statName", statIncrementalValue, callback);
+iotagentLib.statsRegistry.add('statName', statIncrementalValue, callback);
 ```
 
 The first time this function is invoked, it will add the new stat to the registry. Subsequent calls will add the value
@@ -80,7 +80,7 @@ In order to use the library, add the following dependency to your package.json f
 In order to use this library, first you must require it:
 
 ```javascript
-var iotagentLib = require("iotagent-node-lib");
+var iotagentLib = require('iotagent-node-lib');
 ```
 
 The library supports four groups of features, one for each direction of the communication: client-to-server and
@@ -209,8 +209,8 @@ function setCommandResult(entityName, resource, apikey, commandName, commandResu
 ###### Description
 
 Update the result of a command in the Context Broker. The result of the command has two components: the result of the
-command itself will be represented with the suffix `_result` in the entity while the status is updated in the attribute
-with the `_info` suffix.
+command itself will be represented with the suffix `_info` in the entity while the status is updated in the attribute
+with the `_status` suffix.
 
 ###### Params
 
@@ -265,16 +265,16 @@ Once all the updates have taken place, the callback must be invoked with the upd
 
 ```javascript
 callback(null, {
-    type: "TheType",
+    type: 'TheType',
     isPattern: false,
-    id: "EntityID",
+    id: 'EntityID',
     attributes: [
         {
-            name: "lumniscence",
-            type: "Lumens",
-            value: "432",
-        },
-    ],
+            name: 'lumniscence',
+            type: 'Lumens',
+            value: '432'
+        }
+    ]
 });
 ```
 
@@ -303,16 +303,16 @@ The callback must be invoked with the updated Context Element, using the informa
 
 ```javascript
 callback(null, {
-    type: "TheType",
+    type: 'TheType',
     isPattern: false,
-    id: "EntityID",
+    id: 'EntityID',
     attributes: [
         {
-            name: "lumniscence",
-            type: "Lumens",
-            value: "432",
-        },
-    ],
+            name: 'lumniscence',
+            type: 'Lumens',
+            value: '432'
+        }
+    ]
 });
 ```
 
@@ -686,6 +686,38 @@ unexpectedly dead, a new process is created automatically to keep always the max
 -   iotAgent: The IoT Agent Objects, used to start the agent.
 -   callback: The callback function.
 
+##### iotagentLib.request()
+
+###### Signature
+
+```javascript
+function request(options, callback)
+```
+
+###### Description
+
+Make a direct HTTP request using the underlying request library (currently [got](https://github.com/sindresorhus/got)),
+this is useful when creating agents which use an HTTP transport for their southbound commands, and removes the need for
+the custom IoT Agent to import its own additional request library
+
+###### Params
+
+-   options: definition of the request (see
+    [got options](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md) for more details). The
+    following attributes are currently exposed.
+    -   `method` - HTTP Method
+    -   `searchParams` - query string params
+    -   `qs` - alias for query string params
+    -   `headers`
+    -   `responseType` - either `text` or `json`. `json` is the default
+    -   `json` - a supplied JSON object as the request body
+    -   `body` - any ASCII text as the request body. It takes precedence over `json` if both are provided at the same
+        time (not recommended).
+    -   `url` - the request URL
+    -   `uri` - alternative alias for the request URL.
+-   callback: The callback currently returns an `error` Object, the `response` and `body`. The `body` is parsed to a
+    JSON object if the `responseType` is JSON.
+
 #### Generic middlewares
 
 This collection of utility middlewares is aimed to be used to north of the IoT Agent Library, as well as in other

package/docker/Mosquitto/Dockerfile

@@ -1,18 +1,35 @@
-FROM centos:7.9.2009
+ARG  IMAGE_TAG=11.2-slim
+FROM debian:${IMAGE_TAG}
 
-COPY aclfile /root/
-COPY startMosquitto.sh /bin
+ARG CLEAN_DEV_TOOLS
+ENV CLEAN_DEV_TOOLS ${CLEAN_DEV_TOOLS:-1}
 
 ENV CONGIF_FROM_ENV true
 
-RUN yum update -y && yum install -y wget \
-  && yum install -y epel-release \
-  && yum update -y epel-release \
-  && yum install -y mosquitto \
-  && chmod 755 /bin/startMosquitto.sh \
-  && mkdir /var/log/mosquitto \
-  && chown mosquitto:mosquitto /var/log/mosquitto \
-  && yum clean all
+COPY aclfile /root/
+COPY startMosquitto.sh /bin
+
+RUN \
+    # Install security updates
+    apt-get -y update && \
+    apt-get -y upgrade && \
+    # Install dependencies
+    apt-get -y install \
+       wget \
+       mosquitto && \
+    cp /etc/mosquitto/mosquitto.conf /etc/mosquitto/mosquitto.conf.orig && \
+    chmod 755 /bin/startMosquitto.sh && \
+    mkdir -p /var/log/mosquitto && \
+    chown mosquitto:mosquitto /var/log/mosquitto && \
+    mkdir -p /var/run/mosquitto/ && \
+    chown mosquitto:mosquitto /var/run/mosquitto && \
+    echo "INFO: Cleaning unused software..." && \
+    apt-get clean && \
+    apt-get -y autoremove --purge && \
+    if [ ${CLEAN_DEV_TOOLS} -eq 0 ] ; then exit 0 ; fi && \
+    # remove the same packages we installed at the beginning to build Orch
+    apt-get -y autoremove --purge \
+        wget
 
 
 EXPOSE 1883

package/docker/Mosquitto/README.md

@@ -2,9 +2,11 @@ Thi directory containts the Dockerfile (and associated files) for a container of
 This container is provide as a help for users to test with MQTT, but it is just an auxiliary material in this repository.
 
 The following releases matches with eclipse-mosquitto version:
-- 1.5.0 uses mosquitto-1.6.10-1.el7.x86_64
-- 1.4.0 uses mosquitto-1.6.10-1.el7.x86_64
-- 1.3.0 uses mosquitto-1.6.8-1.el7.x86_64
-- 1.2.0 uses mosquitto-1.6.7-1.el7.x86_64
-- 1.1.0 uses mosquitto-1.5.8-1.el7.x86_64
-- 1.0.0 uses mosquitto-1.4.8-1.el7.x86_64
+- 2.0.0 uses mosquitto-2.0.11 from Debian 11
+- 1.6.0 uses mosquitto-1.6.10-1.el7.x86_64 (from Centos7)
+- 1.5.0 uses mosquitto-1.6.10-1.el7.x86_64 (from Centos7)
+- 1.4.0 uses mosquitto-1.6.10-1.el7.x86_64 (from Centos7)
+- 1.3.0 uses mosquitto-1.6.8-1.el7.x86_64 (from Centos7)
+- 1.2.0 uses mosquitto-1.6.7-1.el7.x86_64 (from Centos7)
+- 1.1.0 uses mosquitto-1.5.8-1.el7.x86_64 (from Centos7)
+- 1.0.0 uses mosquitto-1.4.8-1.el7.x86_64 (from Centos7)

package/docker/Mosquitto/startMosquitto.sh

@@ -1,19 +1,29 @@
 #!/usr/bin/env bash
 
-if [ "${CONGIF_FROM_ENV}" = true ] ; then    
+echo "INFO: startMosquitto..."
+
+if [ "${CONGIF_FROM_ENV}" = true ] ; then
+    cp /etc/mosquitto/mosquitto.conf.orig /etc/mosquitto/mosquitto.conf
+    sed -i 's/log_dest file \/var\/log\/mosquitto\/mosquitto.log/log_dest stderr/g' /etc/mosquitto/mosquitto.conf
     echo "log_timestamp true" >> /etc/mosquitto/mosquitto.conf
     echo "log_timestamp_format %Y-%m-%dT%H:%M:%S" >> /etc/mosquitto/mosquitto.conf
     echo 'listener 9001' >> /etc/mosquitto/mosquitto.conf
     echo 'protocol websockets' >> /etc/mosquitto/mosquitto.conf
     echo 'listener 1883' >> /etc/mosquitto/mosquitto.conf
-    echo 'protocol mqtt' >> /etc/mosquitto/mosquitto.conf    
+    echo 'protocol mqtt' >> /etc/mosquitto/mosquitto.conf
     if ! [ -z "${IOTA_PASS}" ] ; then
       # Only if IOTA_PASS is set and not empty MQTT user/pass authentication is used
       touch /etc/mosquitto/pwfile
       sed -i '$ i acl_file /etc/mosquitto/aclfile\npassword_file /etc/mosquitto/pwfile' /etc/mosquitto/mosquitto.conf
-      mv /root/aclfile /etc/mosquitto/aclfile
-      mosquitto_passwd -b /etc/mosquitto/pwfile iota ${IOTA_PASS}
+      cp -f /root/aclfile /etc/mosquitto/aclfile
+      sed -i 's/user iota/user '${IOTA_USER}'/g' /etc/mosquitto/aclfile
+      mosquitto_passwd -b /etc/mosquitto/pwfile ${IOTA_USER} ${IOTA_PASS}
     fi
 fi
 
+echo "INFO: content /etc/mosquitto/mosquitto.conf: "
+cat /etc/mosquitto/mosquitto.conf
+
+echo "INFO: start: startMosquitto -c /etc/mosquitto/mosquitto.conf"
+
 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf