From 8d3106c8fed602408bd78fc2b97a2549e5b9b9ff Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 9 Jan 2024 16:24:00 +0100 Subject: [PATCH 01/25] Add doc section --- doc/api.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/api.md b/doc/api.md index 447070652..5df7c6c70 100644 --- a/doc/api.md +++ b/doc/api.md @@ -9,6 +9,8 @@ - [Config groups](#config-groups) - [Devices](#devices) - [Entity attributes](#entity-attributes) + - [Device autoprovision and entity creation](#device-autoprovision-and-entity-creation) + - [Entity creation before sending commands](#entity-creation-before-sending-commands) - [Multientity support)](#multientity-support) - [Metadata support](#metadata-support) - [NGSI LD data and metadata considerations](#ngsi-ld-data-and-metadata-considerations) @@ -215,6 +217,27 @@ 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 +automaticaly when a device is created. This means that al entities into the context broker are created when data +arrives from a device, either if the device is created or autoprovisioned. + +### Entity creation before sending commands + +Before sending commands, it is needed the entity is created. This mean you need to create the entity into the context +broker by one of the multiples methods that creates an entity before updating the command attribute. Otherwise, you +would obtain an error like the following one when updating the entity into the context broker. + +```json +{ + "error": "NotFound", + "description": "The requested entity has not been found. Check type and id" +} +``` + +For further information, check the issue [fiware-orion/#4430](https://github.com/telefonicaid/fiware-orion/issues/4430) + ## Multientity support The IOTA is able to persists measures coming from a single device to more than one entity, declaring the target entities From 110a82d65909266741c94779d30ec3bf17e00179 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Thu, 11 Jan 2024 09:41:06 +0100 Subject: [PATCH 02/25] Update doc/api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fermín Galán Márquez --- doc/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api.md b/doc/api.md index 5df7c6c70..c633d1900 100644 --- a/doc/api.md +++ b/doc/api.md @@ -225,9 +225,9 @@ arrives from a device, either if the device is created or autoprovisioned. ### Entity creation before sending commands -Before sending commands, it is needed the entity is created. This mean you need to create the entity into the context -broker by one of the multiples methods that creates an entity before updating the command attribute. Otherwise, you -would obtain an error like the following one when updating the entity into the context broker. +Before sending commands, the entity needs to be created. This mean you need to create the entity into the Context +Broker by one of the multiples methods that creates an entity (check [Context Broker API](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md)) before updating the command attribute. Otherwise, you +would obtain an error like the following one when updating the entity into the Context Broker. ```json { From 46013ced03a9016dd7de1eb2be4b858683a80437 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Thu, 18 Jan 2024 18:37:22 +0100 Subject: [PATCH 03/25] Remove entity creation doc --- doc/api.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/doc/api.md b/doc/api.md index c633d1900..fda1df146 100644 --- a/doc/api.md +++ b/doc/api.md @@ -223,21 +223,6 @@ For those agents that uses IoTA Node LIB version 3.4.0 or higher, you should con automaticaly when a device is created. This means that al entities into the context broker are created when data arrives from a device, either if the device is created or autoprovisioned. -### Entity creation before sending commands - -Before sending commands, the entity needs to be created. This mean you need to create the entity into the Context -Broker by one of the multiples methods that creates an entity (check [Context Broker API](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md)) before updating the command attribute. Otherwise, you -would obtain an error like the following one when updating the entity into the Context Broker. - -```json -{ - "error": "NotFound", - "description": "The requested entity has not been found. Check type and id" -} -``` - -For further information, check the issue [fiware-orion/#4430](https://github.com/telefonicaid/fiware-orion/issues/4430) - ## Multientity support The IOTA is able to persists measures coming from a single device to more than one entity, declaring the target entities From 845f47a241bce9502d5e5e2403441251ee866bae Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Thu, 18 Jan 2024 18:37:46 +0100 Subject: [PATCH 04/25] Remove entity creation toc --- doc/api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index fda1df146..bf7359555 100644 --- a/doc/api.md +++ b/doc/api.md @@ -10,7 +10,6 @@ - [Devices](#devices) - [Entity attributes](#entity-attributes) - [Device autoprovision and entity creation](#device-autoprovision-and-entity-creation) - - [Entity creation before sending commands](#entity-creation-before-sending-commands) - [Multientity support)](#multientity-support) - [Metadata support](#metadata-support) - [NGSI LD data and metadata considerations](#ngsi-ld-data-and-metadata-considerations) From d92f237f97ff984dde0389ce9f76e7ed32adb8e0 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Thu, 18 Jan 2024 18:47:17 +0100 Subject: [PATCH 05/25] Add command execution topic --- doc/api.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/api.md b/doc/api.md index bf7359555..6aa231914 100644 --- a/doc/api.md +++ b/doc/api.md @@ -30,6 +30,7 @@ - [Measurement transformation execution](#measurement-transformation-execution) - [Measurement transformation order](#measurement-transformation-order) - [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id) + - [Commands execution](#commands-execution) - [Timestamp Processing](#timestamp-processing) - [Overriding global Context Broker host](#overriding-global-context-broker-host) - [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath) @@ -962,6 +963,33 @@ The IOTA processes the entity attributes looking for a `TimeInstant` attribute. adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the Standard `observedAt` property-of-a-property is used instead. +## Commands execution + +The way to act upon devices is through the usage of commnamds. Commands are specific set attributes that allows to +send information to the device. They are defined in the device provision. + +In order to trigger the command, it is required to update the command attribute in the Orion Context Broker. You +can use a PUT request as the following one: + +```bash +curl -L -X PUT 'http://localhost:1026/v2/entities//attrs/?type=' \ +-H 'Content-Type: application/json' \ +-d '{ + "type" : "command", + "value" : "commandValue" +}' +``` + +**Note**: It is mandatory to add the `type` URL parameter with the entity type to the request, otherwise, you could +get the following error message: + +```json +{ + "error": "NotFound", + "description": "The requested entity has not been found. Check type and id" +} +``` + ## Overriding global Context Broker host **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types From 6ae6b0bece96bd7920b3b2abfc7a136041af8ad7 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 23 Jan 2024 18:40:18 +0100 Subject: [PATCH 06/25] Add info from TC RTD --- doc/api.md | 111 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 92 insertions(+), 19 deletions(-) diff --git a/doc/api.md b/doc/api.md index 6aa231914..142677bf5 100644 --- a/doc/api.md +++ b/doc/api.md @@ -30,7 +30,8 @@ - [Measurement transformation execution](#measurement-transformation-execution) - [Measurement transformation order](#measurement-transformation-order) - [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id) - - [Commands execution](#commands-execution) + - [Command execution](#command-execution) + - [Triggering commands](#triggering-commands) - [Timestamp Processing](#timestamp-processing) - [Overriding global Context Broker host](#overriding-global-context-broker-host) - [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath) @@ -963,32 +964,104 @@ The IOTA processes the entity attributes looking for a `TimeInstant` attribute. adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the Standard `observedAt` property-of-a-property is used instead. -## Commands execution +## Command execution -The way to act upon devices is through the usage of commnamds. Commands are specific set attributes that allows to -send information to the device. They are defined in the device provision. +### Triggering commands -In order to trigger the command, it is required to update the command attribute in the Orion Context Broker. You -can use a PUT request as the following one: +This starts the process of sending data to devices. It starts by updating an attribute into the context broker. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the registry process (as shown in the previous "Register your IoT device" section). Also, you can declare the protocol you want the commands to be sent (HTTP/MQTT) with the "transport" parameter at the registry process. -```bash -curl -L -X PUT 'http://localhost:1026/v2/entities//attrs/?type=' \ --H 'Content-Type: application/json' \ --d '{ - "type" : "command", - "value" : "commandValue" -}' -``` +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: -**Note**: It is mandatory to add the `type` URL parameter with the entity type to the request, otherwise, you could -get the following error message: +``` +PUT /v2/entities//attrs/ping?type= -```json { - "error": "NotFound", - "description": "The requested entity has not been found. Check type and id" + "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//attrs` +* `PUT /v2/entities//attrs` +* `POST /v2/op/entites` with `actionType` `append`, `appendStrict` or `replace` +* `POST /v1/updateContext` with `actionType` `APPEND`, `APPEND_STRICT` 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 in a different way: + +#### 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. + +**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 ignore the "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 pull command from IoTA-JSON Agent the device should make the following request: + +``` +GET /iot/json?k=&i=&getCmd=1 +Accept: application/json +``` + +For IoT Agents it is exactly the same just changing in the request the resource, `/iot/json` by the corresponding resource employed by the agent (I.E, IoTA-UL uses `/iot/d` as default resource) and setting the correct apikey and deviceId. + +It can be also possible for a device to retrieve the commands from the IoT Agent when it sends and observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. + +``` +POST /iot/json?k=&i=&getCmd=1 +Content-Type: text/json + +{"t":25,"h":42,"l":"1299"} +``` + +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"`. + + +## MQTT devices + +For MQTT devices, it is not needed to declare and endpoint. The device is supposed to be subscribed to the following MQTT topic: + ``` +///cmd +``` + +where it will receive the command information. 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 complely procesed 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). + +#### HTTP + +**Polling** + Eventually, once the device makes the response request with the result of the command 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. + +#### MQTT + +The device should publish information in the following topic. + +``` +////cmdexe +``` + ## Overriding global Context Broker host From 0dabfdbf79d43da7eb90e57b4382ea7ca29672d9 Mon Sep 17 00:00:00 2001 From: mapedraza Date: Tue, 23 Jan 2024 22:40:09 +0100 Subject: [PATCH 07/25] Minor changes --- doc/api.md | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/doc/api.md b/doc/api.md index 142677bf5..583440c6a 100644 --- a/doc/api.md +++ b/doc/api.md @@ -32,6 +32,8 @@ - [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id) - [Command execution](#command-execution) - [Triggering commands](#triggering-commands) + - [Command reception](#command-reception) + - [Command confirmation](#command-confirmation) - [Timestamp Processing](#timestamp-processing) - [Overriding global Context Broker host](#overriding-global-context-broker-host) - [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath) @@ -968,9 +970,9 @@ adds a `TimeInstant` attribute as metadata for every other attribute in the same ### Triggering commands -This starts the process of sending data to devices. It starts by updating an attribute into the context broker. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the registry process (as shown in the previous "Register your IoT device" section). Also, you can declare the protocol you want the commands to be sent (HTTP/MQTT) with the "transport" parameter at the registry process. +This starts the process of sending data to devices. It starts by updating an attribute into the context broker. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the registry process. Also, you can declare the protocol you want the commands to be sent (HTTP/MQTT) with the `transport` parameter at the registry 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: +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//attrs/ping?type= @@ -1002,13 +1004,16 @@ Once the command is triggered, it is send to the device. Depending on transport **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 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. +Push commands are only valid for HTTP devices. For MQTT devices it is not needed to set the `endpoint` parameter. **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 ignore the "endpoint" parameter in the device provision. +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 ignore the `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"`. @@ -1025,7 +1030,7 @@ It can be also possible for a device to retrieve the commands from the IoT Agent ``` POST /iot/json?k=&i=&getCmd=1 -Content-Type: text/json +Content-Type: application/json {"t":25,"h":42,"l":"1299"} ``` @@ -1037,22 +1042,31 @@ Once the command is retrieved by the device the status is updated to `"command_s ## MQTT devices -For MQTT devices, it is not needed to declare and endpoint. The device is supposed to be subscribed to the following MQTT topic: +For MQTT devices, it is not needed to declare and endpoint. The device is supposed to be subscribed to the +following MQTT topic: ``` ///cmd ``` -where it will receive the command information. 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. +where it will receive the command information. 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 complely procesed 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). +Once the command is complely procesed 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). #### HTTP **Polling** - Eventually, once the device makes the response request with the result of the command 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. +Eventually, once the device makes the response request with the result of the command 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. #### MQTT From 3b91d76b8e32cc8a684c257ab533994f92f339e2 Mon Sep 17 00:00:00 2001 From: mapedraza Date: Wed, 24 Jan 2024 08:47:58 +0100 Subject: [PATCH 08/25] Fix indentation --- doc/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 583440c6a..165e7e35c 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1040,7 +1040,7 @@ This is also possible for IoTA-UL Agent changing in the request the resource, se Once the command is retrieved by the device the status is updated to `"command_status":"DELIVERED"`. -## MQTT devices +#### MQTT devices For MQTT devices, it is not needed to declare and endpoint. The device is supposed to be subscribed to the following MQTT topic: From e44e3c3e60807c26309c4c3ef32070175f1bd40e Mon Sep 17 00:00:00 2001 From: mapedraza Date: Wed, 24 Jan 2024 09:11:25 +0100 Subject: [PATCH 09/25] Add comments from revision --- doc/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api.md b/doc/api.md index 165e7e35c..2a94e939d 100644 --- a/doc/api.md +++ b/doc/api.md @@ -223,8 +223,8 @@ measure name, unless `explicitAttrs` is defined. Measures `id` or `type` names a ## 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 -automaticaly when a device is created. This means that al entities into the context broker are created when data -arrives from a device, either if the device is created or autoprovisioned. +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. ## Multientity support From 624b6c402dd34f6a793f47ba8e0c6ae5a0f12010 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Wed, 24 Jan 2024 11:15:43 +0100 Subject: [PATCH 10/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fermín Galán Márquez --- doc/api.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/doc/api.md b/doc/api.md index 2a94e939d..0085d3b99 100644 --- a/doc/api.md +++ b/doc/api.md @@ -970,9 +970,9 @@ adds a `TimeInstant` attribute as metadata for every other attribute in the same ### Triggering commands -This starts the process of sending data to devices. It starts by updating an attribute into the context broker. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the registry process. Also, you can declare the protocol you want the commands to be sent (HTTP/MQTT) with the `transport` parameter at the registry process. +This starts the process of sending data to devices. It starts by updating an attribute into the Context Broker. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the provisioning process. Also, you can declare 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: +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//attrs/ping?type= @@ -984,7 +984,7 @@ PUT /v2/entities//attrs/ping?type= ``` -It is important to note that parameter `type`, with the `entity_type` must be included. +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. @@ -994,7 +994,6 @@ Context Broker API is quite flexible and allows to update an attribute in severa * `POST /v2/entities//attrs` * `PUT /v2/entities//attrs` * `POST /v2/op/entites` with `actionType` `append`, `appendStrict` or `replace` -* `POST /v1/updateContext` with `actionType` `APPEND`, `APPEND_STRICT` or `REPLACE` ### Command reception @@ -1013,20 +1012,20 @@ Push commands are only valid for HTTP devices. For MQTT devices it is not needed 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 ignore the `endpoint` parameter in the device provision. +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"`. +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 `"_status": "PENDING"`. -For HTTP devices, in order to retrieve a pull command from IoTA-JSON Agent the device should make the following request: +For HTTP devices, in order to retrieve a poll command from IoTA-JSON Agent the device should make the following request: ``` GET /iot/json?k=&i=&getCmd=1 Accept: application/json ``` -For IoT Agents it is exactly the same just changing in the request the resource, `/iot/json` by the corresponding resource employed by the agent (I.E, IoTA-UL uses `/iot/d` as default resource) and setting the correct apikey and deviceId. +For IoT Agents different from IoTA-JSON it is exactly the same just changing in the request the resource, `/iot/json` by the corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource) and setting the correct `` and ``. -It can be also possible for a device to retrieve the commands from the IoT Agent when it sends and observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. +It can be also possible for a device to retrieve the commands from the IoT Agent when it sends an observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. ``` POST /iot/json?k=&i=&getCmd=1 @@ -1035,14 +1034,14 @@ Content-Type: application/json {"t":25,"h":42,"l":"1299"} ``` -This is also possible for IoTA-UL Agent changing in the request the resource, setting the correct apikey, deviceId, payload and headers. +This is also possible for IoTA-UL Agent changing in the request the resource, setting the correct ``, ``, payload and headers. -Once the command is retrieved by the device the status is updated to `"command_status":"DELIVERED"`. +Once the command is retrieved by the device the status is updated to `"_status": "DELIVERED"`. #### MQTT devices -For MQTT devices, it is not needed to declare and endpoint. The device is supposed to be subscribed to the +For MQTT devices, it is not needed to declare and 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: ``` @@ -1057,16 +1056,16 @@ will receive all of the queued commands. ### Command confirmation -Once the command is complely procesed 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 +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 `_info` +attribute. The status of the command will be stored in the `_status` attribute (`OK` if everything goes right). #### HTTP **Polling** Eventually, once the device makes the response request with the result of the command 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. +to`"_status": "OK"`. Also the result of the command delivered by the device is stored in the `_info` attribute. #### MQTT From 001f39e899aaefef253d142e0ba0281908f7086b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Wed, 24 Jan 2024 11:46:07 +0100 Subject: [PATCH 11/25] Apply suggestions from code review --- doc/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api.md b/doc/api.md index 0085d3b99..6dc8b3e72 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1041,7 +1041,7 @@ Once the command is retrieved by the device the status is updated to `" #### MQTT devices -For MQTT devices, it is not needed to declare and endpoint (i.e. if included in the provisioning request, it is not used). The device is supposed to be subscribed to the +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: ``` @@ -1069,7 +1069,7 @@ to`"_status": "OK"`. Also the result of the command delivered by the de #### MQTT -The device should publish information in the following topic. +The device should publish the result of the command in the following topic. ``` ////cmdexe From 8354832ba2a1be48d04ba74de04168e7b2083490 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Wed, 24 Jan 2024 11:54:42 +0100 Subject: [PATCH 12/25] ADD some FIXME marks with existing gaps in doc --- doc/api.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 6dc8b3e72..80cad0585 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1007,6 +1007,8 @@ Push commands are those that are sent to the device once the IoT Agent receives Push commands are only valid for HTTP devices. For MQTT devices it is not needed to set the `endpoint` parameter. +**FIXME**: example of request sent from IoTA-JSON to device listening in "http://[DEVICE_IP]:[PORT]" and response associated to that request should be included, based on the ping example shown above. + **Poll commands** Poll commands are those that are stored in the IoT Agent waiting to be retrieved by the devices. This kind of @@ -1023,6 +1025,8 @@ GET /iot/json?k=&i=&getCmd=1 Accept: application/json ``` +**FIXME**: example of response to this request should be included, based on the ping example shown above. + For IoT Agents different from IoTA-JSON it is exactly the same just changing in the request the resource, `/iot/json` by the corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource) and setting the correct `` and ``. It can be also possible for a device to retrieve the commands from the IoT Agent when it sends an observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. @@ -1048,6 +1052,8 @@ following MQTT topic: ///cmd ``` +**FIXME**: example of payload sent to this topic by the IoTA-JSON should be included, based on the ping example shown above. + where it will receive the command information. 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 @@ -1075,7 +1081,6 @@ The device should publish the result of the command in the following topic. ////cmdexe ``` - ## Overriding global Context Broker host **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types From 13edae7a91e7adae495b8b0d79a67a45cd460628 Mon Sep 17 00:00:00 2001 From: mapedraza Date: Thu, 25 Jan 2024 17:54:58 +0100 Subject: [PATCH 13/25] Add JSON examples --- doc/api.md | 81 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/doc/api.md b/doc/api.md index 80cad0585..977205951 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1003,11 +1003,22 @@ Once the command is triggered, it is send to the device. Depending on transport **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 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. -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: -**FIXME**: example of request sent from IoTA-JSON to device listening in "http://[DEVICE_IP]:[PORT]" and response associated to that request should be included, based on the ping example shown above. +``` +POST / +Content-Type: application/json + +{"ping":"Ping request"} +``` + +**FIXME**: Pending to add CB attributes values, see #1559 **Poll commands** @@ -1018,16 +1029,22 @@ to configure the device as poll commands you just need to avoid the usage of `en 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 `"_status": "PENDING"`. -For HTTP devices, in order to retrieve a poll command from IoTA-JSON Agent the device should make the following request: +For HTTP devices, in order to retrieve a poll command, the need to make a GET request to the IoT Agent to the path `/iot/json` with the following parameters: + +* `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 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: ``` GET /iot/json?k=&i=&getCmd=1 Accept: application/json -``` -**FIXME**: example of response to this request should be included, based on the ping example shown above. +{"ping":"Ping request"} +``` -For IoT Agents different from IoTA-JSON it is exactly the same just changing in the request the resource, `/iot/json` by the corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource) and setting the correct `` and ``. +For IoT Agents different from IoTA-JSON it is exactly the same just changing in the request the resource, `/iot/json` by the corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource) and setting the correct `` and ``. The response will be also different depending on the IoT Agent employed. It can be also possible for a device to retrieve the commands from the IoT Agent when it sends an observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. @@ -1045,37 +1062,61 @@ Once the command is retrieved by the device the status is updated to `" #### 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: +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: ``` ///cmd ``` -**FIXME**: example of payload sent to this topic by the IoTA-JSON should be included, based on the ping example shown above. +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"} +``` -where it will receive the command information. 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. +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 `_info` attribute. The status of the command will be stored in the `_status` attribute (`OK` if everything -goes right). +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 -**Polling** -Eventually, once the device makes the response request with the result of the command the status is updated -to`"_status": "OK"`. Also the result of the command delivered by the device is stored in the `_info` attribute. +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. The request must be made to the +following resource: + +``` +POST /iot/json/commands?k=&i= +Content-Type: application/json +Accept: application/json + +{"ping":"status_ok"} +``` #### MQTT -The device should publish the result of the command in the following topic. +The device should publish the result of the command (`{"ping":"status_ok"}` in the previous example) to a +topic following the next pattern: ``` ////cmdexe From b8efdea6363ac21bb9ce04585ecf03ed6bbaf271 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 10:12:01 +0200 Subject: [PATCH 14/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fermín Galán Márquez --- doc/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api.md b/doc/api.md index c04de03e9..95d17bade 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1324,8 +1324,7 @@ Eventually, once the device makes the response request the IoTA would update the #### 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. The request must be made to the -following resource: +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=&i= @@ -1344,6 +1343,7 @@ topic following the next pattern: ////cmdexe ``` +The IoTA is subscribed to that topic, so it gets the result of the command. When this happens, the status is updated to`"_status": "OK"`. Also the result of the command delivered by the device is stored in the `_info` attribute. ## Overriding global Context Broker host **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types From 5e0dda7fa228fd648510711331fbecdc9ba2d04d Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 10:32:12 +0200 Subject: [PATCH 15/25] Fix request examples --- doc/api.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 95d17bade..3dde3d8ef 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1259,17 +1259,29 @@ For HTTP devices, in order to retrieve a poll command, the need to make a GET re Taking the previous example, and considering the 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=&i=&getCmd=1 Accept: application/json -{"ping":"Ping request"} +``` + +**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, `/iot/json` by the corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource) and setting the correct `` and ``. The response will be also different depending on the IoT Agent employed. It can be also possible for a device to retrieve the commands from the IoT Agent when it sends an observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. +**Request** + ``` POST /iot/json?k=&i=&getCmd=1 Content-Type: application/json @@ -1277,6 +1289,16 @@ 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 ``, ``, payload and headers. Once the command is retrieved by the device the status is updated to `"_status": "DELIVERED"`. From 65daad9887dc064fe78aff29aaee9495e4a4e524 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 10:34:50 +0200 Subject: [PATCH 16/25] Fix errata --- doc/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 3dde3d8ef..52e1f0e25 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1257,7 +1257,7 @@ For HTTP devices, in order to retrieve a poll command, the need to make a GET re * `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 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: +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:** From a27284a6ea3e65fbf4aa0a83a82d9dc97a514b43 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 10:57:50 +0200 Subject: [PATCH 17/25] fix commands attrs --- doc/api.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/api.md b/doc/api.md index 52e1f0e25..4a9462b5f 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1219,7 +1219,8 @@ Context Broker API is quite flexible and allows to update an attribute in severa ### Command reception -Once the command is triggered, it is send to the device. Depending on transport protocol, it is going to be sent in a different way: +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 @@ -1240,8 +1241,6 @@ Content-Type: application/json {"ping":"Ping request"} ``` -**FIXME**: Pending to add CB attributes values, see #1559 - **Poll commands** Poll commands are those that are stored in the IoT Agent waiting to be retrieved by the devices. This kind of From 557f75aa143a9430a92ef44859a61bb8f6c22797 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 15:58:36 +0200 Subject: [PATCH 18/25] Add suggestions --- doc/api.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 4a9462b5f..679a9d4b3 100644 --- a/doc/api.md +++ b/doc/api.md @@ -11,6 +11,7 @@ - [Uniqueness of groups and devices](#uniqueness-of-groups-and-devices) - [Special measures and attributes names](#special-measures-and-attributes-names) - [Entity attributes](#entity-attributes) + - [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) @@ -245,7 +246,9 @@ measure name, unless `explicitAttrs` is defined. Measures `id` or `type` names a 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. +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 [NGSIv2 API](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md). + + ## Multientity support @@ -1190,6 +1193,8 @@ In this case a batch update (`POST /v2/op/update`) to CB will be generated with ## Command execution +This section reviews the end to end process to trigger and receive commands into devices. The URL paths and 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. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the provisioning process. Also, you can declare the protocol you want the commands to be sent (HTTP/MQTT) with the `transport` parameter at the provisioning process. @@ -1247,6 +1252,9 @@ Poll commands are those that are stored in the IoT Agent waiting to be retrieved 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. +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. 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 `"_status": "PENDING"`. @@ -1268,6 +1276,9 @@ Accept: application/json **Response:**: +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 `` and ``. 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. ``` 200 OK Content-type: application/json From 99eb5163b979168971b85ef4e649d014cc6164de Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 16:04:50 +0200 Subject: [PATCH 19/25] Fix possition --- doc/api.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/doc/api.md b/doc/api.md index 679a9d4b3..2ec172482 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1252,13 +1252,12 @@ Poll commands are those that are stored in the IoT Agent waiting to be retrieved 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. -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. 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 `"_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 `/iot/json` with the following parameters: +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. @@ -1276,9 +1275,6 @@ Accept: application/json **Response:**: -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 `` and ``. 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. ``` 200 OK Content-type: application/json @@ -1286,9 +1282,9 @@ 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, `/iot/json` by the corresponding resource employed by the agent (i.e., IoTA-UL uses `/iot/d` as default resource) and setting the correct `` and ``. The response will be also different depending on the IoT Agent employed. +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 `` and ``. The response will be also different depending on the IoT Agent employed. -It can be also possible for a device to retrieve the commands from the IoT Agent when it sends an observation. It just be needed to include the `&getCmd=1` parameter in the observation request. In the following example a device sends an JSON observation and retrieves the commands from the IoTA-JSON Agent. +**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** From 8c6347006b53722f965386daf7c50a070ad476dc Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 16:06:44 +0200 Subject: [PATCH 20/25] Update doc/api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fermín Galán Márquez --- doc/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 2ec172482..cbd9a96d8 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1307,7 +1307,7 @@ Content-type: application/json This is also possible for IoTA-UL Agent changing in the request the resource, setting the correct ``, ``, payload and headers. -Once the command is retrieved by the device the status is updated to `"_status": "DELIVERED"`. +Once the command is retrieved by the device the status is updated to `"_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 From aff5501b551127b1a935fe002899fddd857a90e9 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 16:18:33 +0200 Subject: [PATCH 21/25] Update doc/api.md --- doc/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index cbd9a96d8..d8ae78fa8 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1197,7 +1197,7 @@ This section reviews the end to end process to trigger and receive commands into ### Triggering commands -This starts the process of sending data to devices. It starts by updating an attribute into the Context Broker. You need to know which attributes correspond to commands and update them. You can declare the command related attributes at the provisioning process. Also, you can declare the protocol you want the commands to be sent (HTTP/MQTT) with the `transport` parameter at the provisioning process. +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: From 33c1e9ce6c3d2dd174e43b8fee865f85d4204170 Mon Sep 17 00:00:00 2001 From: mapedraza <40356341+mapedraza@users.noreply.github.com> Date: Tue, 30 Jul 2024 16:39:52 +0200 Subject: [PATCH 22/25] fix linter --- doc/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api.md b/doc/api.md index d8ae78fa8..5a8df5997 100644 --- a/doc/api.md +++ b/doc/api.md @@ -246,7 +246,7 @@ measure name, unless `explicitAttrs` is defined. Measures `id` or `type` names a 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 [NGSIv2 API](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md). +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). @@ -1193,7 +1193,7 @@ In this case a batch update (`POST /v2/op/update`) to CB will be generated with ## Command execution -This section reviews the end to end process to trigger and receive commands into devices. The URL paths and 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. +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 From db3b0b380f3c9cd6dd03f2df552ec06ef3b41c0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Tue, 30 Jul 2024 16:44:40 +0200 Subject: [PATCH 23/25] Update doc/api.md --- doc/api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index 5a8df5997..36c8a7cb9 100644 --- a/doc/api.md +++ b/doc/api.md @@ -246,7 +246,9 @@ measure name, unless `explicitAttrs` is defined. Measures `id` or `type` names a 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). +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). From 693775d993586fb20a6ef2207a0edf9d53b478ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Tue, 30 Jul 2024 16:45:09 +0200 Subject: [PATCH 24/25] Update doc/api.md --- doc/api.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/api.md b/doc/api.md index 36c8a7cb9..645fa7432 100644 --- a/doc/api.md +++ b/doc/api.md @@ -250,8 +250,6 @@ arrives from a device, no matter if the device is explicitly provisioned (via [d 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 From 44d24f7a94a4c44de4539f8e38a9c7f2ed42993a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Tue, 30 Jul 2024 16:47:23 +0200 Subject: [PATCH 25/25] Update doc/api.md --- doc/api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api.md b/doc/api.md index 645fa7432..a0c9ddbac 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1372,6 +1372,7 @@ topic following the next pattern: ``` The IoTA is subscribed to that topic, so it gets the result of the command. When this happens, the status is updated to`"_status": "OK"`. Also the result of the command delivered by the device is stored in the `_info` attribute. + ## Overriding global Context Broker host **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types