Merge pull request #410 from Chandradeep-NEC/patch-1

Improvment of documentation

docs/stepbystep.md

@@ -7,13 +7,13 @@
 
 ## 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
-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 MQTT-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
 /<apiKey>/<deviceId>/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 (v0.26)
--   Node.js (v0.12.0)
+-   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)
@@ -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`.
 

docs/usermanual.md

@@ -111,24 +111,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 }
+        }
+    ]
 }
 ```
 
@@ -193,6 +193,39 @@ 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 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-
+
+```text
+curl -X GET 'http://localhost:7896/iot/json?i=motion001&k=4jggokgpepnvsb2uv4s40d59ov&getCmd=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