From 6679e3056bb11cca57bdbc0f22bec6a87837d955 Mon Sep 17 00:00:00 2001 From: chandradeep03 <49039163+chandradeep03@users.noreply.github.com> Date: Mon, 24 Jun 2019 13:01:28 +0530 Subject: [PATCH 1/5] Update stepbystep.md --- docs/stepbystep.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/stepbystep.md b/docs/stepbystep.md index c72c9b5b..46167c47 100644 --- a/docs/stepbystep.md +++ b/docs/stepbystep.md @@ -7,10 +7,10 @@ ## Introduction -This guide will show, step-by-step, how to deploy and configure an MQTT-JSON IoT Agent for its use to connect devices to +This guide will show, step-by-step, how to deploy and configure an IoTAgent-JSON IoT Agent for its use to connect devices to an external NGSI Broker (aka Context Broker). -The MQTT-JSON IoT Agent acts as a gateway for communicating devices using the MQTT protocol with NGSI brokers (or any +The IoTAgent-JSON IoT Agent acts as a gateway for communicating devices using the MQTT protocol with NGSI brokers (or any other piece which uses the NGSI protocol). The communication is based on a series of unidirectional MQTT topics (i.e.: each topic is used to _publish_ device information or to _subscribe_ to entity updates, but not both). Every topic has the same prefix, of the form: @@ -50,7 +50,7 @@ interchanged between simulated devices and the Context Broker. The following list shows the prerequisite software and versions: -- Orion Context Broker (v0.26) +- Orion Context Broker (v2.2.0) - Node.js (v0.12.0) - Mosquitto (v1.4.7) (out-of-the-box setup) - Curl (v7.19.7) @@ -109,7 +109,7 @@ An easy way to see everything is working is to get the version from the North Po curl http://localhost:4041/iot/about ``` -The result will be a JSON document indicating the MQTT-JSON IoTA version and the version of the IoTA Library in use: +The result will be a JSON document indicating the IoTAgent-JSON IoTA version and the version of the IoTA Library in use: ```json { @@ -265,7 +265,7 @@ The resulting response should look like the following: ### Retrieving configuration parameters from the Context Broker -The MQTT-JSON IoT Agent offers a special mechanism to retrieve information from the device entity, for device +The IoTAgent-JSON IoT Agent offers a special mechanism to retrieve information from the device entity, for device configuration purposes. This mechanism is based on two special topics, with suffix `/configuration/commands` and `/configuration/values`. From 98d65a8cf7e3a2ca1e1305959e63de552a12c307 Mon Sep 17 00:00:00 2001 From: chandradeep03 <49039163+chandradeep03@users.noreply.github.com> Date: Mon, 24 Jun 2019 15:34:19 +0530 Subject: [PATCH 2/5] Update usermanual.md --- docs/usermanual.md | 46 +++++++++++++++++++--------------------------- 1 file changed, 19 insertions(+), 27 deletions(-) diff --git a/docs/usermanual.md b/docs/usermanual.md index 2f1b1f9c..b76d2562 100644 --- a/docs/usermanual.md +++ b/docs/usermanual.md @@ -56,33 +56,6 @@ following query parameters: - **k (API Key)**: API Key for the service the device is registered on. - **t (timestamp)**: Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional). -#### Commands - -MQTT devices commands are always push. For HTTP Devices commands to be push they **must** be provisioned with the -`endpoint` attribute, that will contain the URL where the IoT Agent will send the received commands. Otherwise the -command will be poll. When using the HTTP transport, the command handling have two flavours: - -- **Push commands**: The request payload format will be a plain JSON, as described in the "Payload" section. The - device will reply with a 200OK response containing the result of the command in the JSON result format. - -- **Polling commands**: in this case, the Agent does not send any messages to the device, being the later responsible - of retrieving them from the IoTAgent whenever the device is ready to get commands. In order to retrieve commands - from the IoT Agent, the device will send the query parameter 'getCmd' with value '1' as part of a normal measure. As - a result of this action, the IoTAgent, instead of returning an empty body (the typical response to a measurement - report), will return a list of all the commands available for the device, in JSON format: each attribute will - represent a command, and its value the command value. The use of a JSON return object implies that only one value - can be returned for each command (last value will be returned for each one). Implementation imposes another - limitation in the available values for the commands: a command value can't be an empty string, or a string composed - exclusively by whitespaces. Whenever the device has completed the execution of the command, it will send the - response in the same way measurements are reported, but using the **command result format** as exposed in the - [Protocol section](#protocol). - -Some additional remarks regarding polling commands: - -- Commands can be also retrieved without needed of sending a mesaure. In other words, the device is not forced to send - a measure in order to get the accumulated commands. However, in this case note that `GET` method is used to carry - the `getCmd=1` query parameter (as they are no actual payload for measures, `POST` wouldn't make too much sense). - #### Configuration retrieval The protocol offers a mechanism for the devices to retrieve its configuration (or any other value it needs from those @@ -144,6 +117,25 @@ E.g.: } ``` +#### Commands + +MQTT devices commands are always push. For HTTP Devices commands to be push they **must** be provisioned with the +`endpoint` attribute, that will contain the URL where the IoT Agent will send the received commands. Otherwise the +command will be poll. When using the HTTP transport, the command handling have two flavours: + +- **Push commands**: The request payload format will be a plain JSON, as described in the "Payload" section. The + device will reply with a 200OK response containing the result of the command in the JSON result format. + +- **Polling commands**: These commands are meant to be used on those cases where the device can't be online the whole time waiting for commands. In this case, the IoTAgents must store the received commands, offering a way for the device to retrieve the pending commands upon connection. Whenever the device is ready, it itself retrieves the commands from the IoT agent. While sending a normal measure, the device sends query parameter 'getCmd' with value '1' in order to retrieve the commands from IoT Agent. The IoT Agent responds with a list of commands available for that device which are send in a JSON format. The attributes in the response body represents the commands and the values represents command values. The use of a JSON return object implies that only one value can be returned for each command (last value will be returned for each one). Implementation imposes another limitation in the available values for the commands: a command value can't be an empty string, or a string composed exclusively by whitespaces. The command payload is described in the protocol section. Whenever the device has completed the execution of the command, it will send the response in the same way measurements are reported, but using the command result format as exposed in the Protocol section. + +Some additional remarks regarding polling commands: + +- Commands can be also retrieved without needed of sending a mesaure. In other words, the device is not forced to send + a measure in order to get the accumulated commands. + + Example to retrieve commands from IoT Agent- + * curl -X GET 'http://localhost:7896/iot/json?i=motion001&k=4jggokgpepnvsb2uv4s40d59ov&getCmd=1&d=c|1' -i + ### MQTT binding MQTT binding is based on the existence of a MQTT broker and the usage of different topics to separate the different From 1242bba069de328326c1c789da27a43376d35292 Mon Sep 17 00:00:00 2001 From: chandradeep03 <49039163+chandradeep03@users.noreply.github.com> Date: Mon, 24 Jun 2019 15:39:16 +0530 Subject: [PATCH 3/5] Update stepbystep.md --- docs/stepbystep.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stepbystep.md b/docs/stepbystep.md index 46167c47..92dc611b 100644 --- a/docs/stepbystep.md +++ b/docs/stepbystep.md @@ -51,7 +51,7 @@ interchanged between simulated devices and the Context Broker. The following list shows the prerequisite software and versions: - Orion Context Broker (v2.2.0) -- Node.js (v0.12.0) +- Node.js (v8) - Mosquitto (v1.4.7) (out-of-the-box setup) - Curl (v7.19.7) - Git (v1.7.1) From 5f40dcfcbe89a436a935761e60e0e0394c305acd Mon Sep 17 00:00:00 2001 From: Chandradeep-NEC Date: Fri, 30 Oct 2020 11:05:40 +0530 Subject: [PATCH 4/5] updated for lint error --- docs/usermanual.md | 56 +++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/docs/usermanual.md b/docs/usermanual.md index ec973e7e..17bb0f2c 100644 --- a/docs/usermanual.md +++ b/docs/usermanual.md @@ -85,8 +85,8 @@ following query parameters: - **k (API Key)**: API Key for the service the device is registered on. - **t (timestamp)**: Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional). - ======= + #### Sending Commands MQTT devices commands are always push. For HTTP Devices commands to be push they **must** be provisioned with the @@ -113,24 +113,24 @@ Some additional remarks regarding polling commands: - Commands can be also retrieved without needed of sending a mesaure. In other words, the device is not forced to send a measure in order to get the accumulated commands. However, in this case note that `GET` method is used to carry the `getCmd=1` query parameter (as they are no actual payload for measures, `POST` wouldn't make too much sense). -- MQTT devices can configure (at provisioning and updating time) each command with different values of MQTT QoS and MQTT retain values, which will be used only by a command. Moreover, in the same MQTT device different commands can be configured to use different MQTT options related with QoS level and Retain message policy. I.E: +- MQTT devices can configure (at provisioning and updating time) each command with different values of MQTT QoS and + MQTT retain values, which will be used only by a command. Moreover, in the same MQTT device different commands can + be configured to use different MQTT options related with QoS level and Retain message policy. I.E: ```json { - - "commands": [ - { - "type": "command", - "name": "a_command_name_A", - "mqtt": { "qos": 2, "retain": true } - }, - { - "type": "command", - "name": "a_command_name_B", - "mqtt": { "qos": 1, "retain": false } - } - ] - + "commands": [ + { + "type": "command", + "name": "a_command_name_A", + "mqtt": { "qos": 2, "retain": true } + }, + { + "type": "command", + "name": "a_command_name_B", + "mqtt": { "qos": 1, "retain": false } + } + ] } ``` @@ -204,15 +204,29 @@ command will be poll. When using the HTTP transport, the command handling have t - **Push commands**: The request payload format will be a plain JSON, as described in the "Payload" section. The device will reply with a 200OK response containing the result of the command in the JSON result format. -- **Polling commands**: These commands are meant to be used on those cases where the device can't be online the whole time waiting for commands. In this case, the IoTAgents must store the received commands, offering a way for the device to retrieve the pending commands upon connection. Whenever the device is ready, it itself retrieves the commands from the IoT agent. While sending a normal measure, the device sends query parameter 'getCmd' with value '1' in order to retrieve the commands from IoT Agent. The IoT Agent responds with a list of commands available for that device which are send in a JSON format. The attributes in the response body represents the commands and the values represents command values. The use of a JSON return object implies that only one value can be returned for each command (last value will be returned for each one). Implementation imposes another limitation in the available values for the commands: a command value can't be an empty string, or a string composed exclusively by whitespaces. The command payload is described in the protocol section. Whenever the device has completed the execution of the command, it will send the response in the same way measurements are reported, but using the command result format as exposed in the Protocol section. +- **Polling commands**: These commands are meant to be used on those cases where the device can't be online the whole + time waiting for commands. In this case, the IoTAgents must store the received commands, offering a way for the + device to retrieve the pending commands upon connection. Whenever the device is ready, it itself retrieves the + commands from the IoT agent. While sending a normal measure, the device sends query parameter 'getCmd' with value + '1' in order to retrieve the commands from IoT Agent. The IoT Agent responds with a list of commands available for + that device which are send in a JSON format. The attributes in the response body represents the commands and the + values represents command values. The use of a JSON return object implies that only one value can be returned for + each command (last value will be returned for each one). Implementation imposes another limitation in the available + values for the commands: a command value can't be an empty string, or a string composed exclusively by whitespaces. + The command payload is described in the protocol section. Whenever the device has completed the execution of the + command, it will send the response in the same way measurements are reported, but using the command result format as + exposed in the Protocol section. Some additional remarks regarding polling commands: -- Commands can be also retrieved without needed of sending a mesaure. In other words, the device is not forced to send - a measure in order to get the accumulated commands. - +- Commands can be also retrieved without the need of sending a measure. In other words, the device is not forced to + send a measure in order to get the accumulated commands. + Example to retrieve commands from IoT Agent- - * curl -X GET 'http://localhost:7896/iot/json?i=motion001&k=4jggokgpepnvsb2uv4s40d59ov&getCmd=1&d=c|1' -i + +```text +curl -X GET 'http://localhost:7896/iot/json?i=motion001&k=4jggokgpepnvsb2uv4s40d59ov&getCmd=1' -i +``` ### MQTT binding From a32c94136edc10f5b95ca1e338637d4cbe7f9b97 Mon Sep 17 00:00:00 2001 From: Chandradeep-NEC Date: Fri, 30 Oct 2020 21:18:53 +0530 Subject: [PATCH 5/5] Updated for review comment fixing --- docs/stepbystep.md | 18 +++++++++--------- docs/usermanual.md | 2 -- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/stepbystep.md b/docs/stepbystep.md index 6861fd02..290aeb52 100644 --- a/docs/stepbystep.md +++ b/docs/stepbystep.md @@ -7,13 +7,13 @@ ## Introduction -This guide will show, step-by-step, how to deploy and configure an IoTAgent-JSON IoT Agent for its use to connect devices to -an external NGSI Broker (aka Context Broker). +This guide will show, step-by-step, how to deploy and configure an IoTAgent-JSON IoT Agent for its use to connect +devices to an external NGSI Broker (aka Context Broker). -The IoTAgent-JSON IoT Agent acts as a gateway for communicating devices using the MQTT protocol with NGSI brokers (or any -other piece which uses the NGSI protocol). The communication is based on a series of unidirectional MQTT topics (i.e.: -each topic is used to _publish_ device information or to _subscribe_ to entity updates, but not both). Every topic has -the same prefix, of the form: +The IoTAgent-JSON IoT Agent acts as a gateway for communicating devices using the MQTT protocol with NGSI brokers (or +any other piece which uses the NGSI protocol). The communication is based on a series of unidirectional MQTT topics +(i.e.: each topic is used to _publish_ device information or to _subscribe_ to entity updates, but not both). Every +topic has the same prefix, of the form: ```text ///topicSpecificPart @@ -48,10 +48,10 @@ The selected MQTT Broker for this tutorial was Mosquitto, although it could be s broker. The Mosquitto command tools will also be used along this guide to test the installation and show the information interchanged between simulated devices and the Context Broker. -The following list shows the prerequisite software and versions: +The following list shows the recommended software and versions: -- Orion Context Broker (v2.2.0) -- Node.js (v8) +- Orion Context Broker (v2.5.0) +- Node.js (v10) - Mosquitto (v1.4.7) (out-of-the-box setup) - Curl (v7.19.7) - Git (v1.7.1) diff --git a/docs/usermanual.md b/docs/usermanual.md index 17bb0f2c..cec0fbb7 100644 --- a/docs/usermanual.md +++ b/docs/usermanual.md @@ -85,8 +85,6 @@ following query parameters: - **k (API Key)**: API Key for the service the device is registered on. - **t (timestamp)**: Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional). -======= - #### Sending Commands MQTT devices commands are always push. For HTTP Devices commands to be push they **must** be provisioned with the