What is the NGSI v2 endpoint for mimicking IoT Agent commands?

Question

When testing commands Southbound, I am currently using the NGSI v1 endpoint as shown:

curl -X POST \
  'http://{{iot-agent}}/v1/updateContext' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
    "contextElements": [
        {
            "type": "Bell",
            "isPattern": "false",
            "id": "urn:ngsi-ld:Bell:001",
            "attributes": [
                {
                    "name": "ring",
                    "type": "command",
                    "value": ""
                }
            ]
        }
    ],
    "updateAction": "UPDATE"
}'

As you can see this is an NGSI v1 request. According to this presentation on Slideshare (slide 16) use of NGSI v1 is discouraged - I would like to replace this with an NGSI v2 request. I believe that all IoT Agents are now NGSI v2 capable, however I have been unable to find the details of the replacement NGSI v2 request within the documentation.

So the question is what is the equivalent cUrl command to mimic a command from Orion using NGSI v2?

Answer 1

In this document you can see a good reference on how to send commands using the NGSIv2 API:

If you take a look to the previous device example, you can find that a "ping" command was defined. Any update on this attribute “Ping” at the NGSI entity in the ContextBroker 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 ContextBroker API:

 PUT /v2/entities/[ENTITY_ID]/attrs/ping { "value": "Ping request", "type": "command" }

ContextBroker API is quite flexible and allows to update an attribute in several ways. Please have a look to the NGSIv2 specification for details.

Important note: don't use operations in the NGSI API with creation semantics. Otherwise, the entity/attribute will be created locally to ContextBroker 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
• PUT /v2/entities
• POST /v2/op/entites with actionType append , appendStrict or replace
• POST /v1/updateContext with actionType APPEND , APPEND_STRICT or REPLACE

EDIT : all the above refers to the Orion endpoint used by final client to send commands . @jason-fox has clarified that question refers to the IOTA endpoint that receives commands request from Orion (it should have been evident by the {{iot-agent}} , but I missed that part sorry :)

The Orion-to-IOTA communication for commands is based on the registration-forwarding mechanism. Currently, Orion always uses NGSIv1 to forward updates (even in the case the client uses NGSIv2 updates). In the future, we envision the usage of NGSIv2 but in order to achieve this, first we need:

• To complete the Context Source Forwarding Specification, based on NGSIv2. It is currently under discussion in this PR . Feedback is welcome as comments to that PR!
• To implement forwarding based in Context Source Forwarding Specification in Orion
• To implement NGSIv2 endpoint compliant with Context Source Forwarding Specification in the IOTAs.

While the above gets completed, the only mechanism is the current one based in NGSIv1. However, note the Orion-IOTA interaction is internal to platform component and final client could base all their interactions to the platform (in particular, to the Orion endpoint) on NGSIv2, so this is not a big issue.

Answer 2

The Context Source Forwarding Specification, based on NGSIv2 is now completed and the old /v1 endpoint has been deprecated . According to the discussions of the associated Support for NGSIv2 issue , the correct request to send is as follows:

curl -iX POST \
  http://localhost:4041/v2/op/update \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
    "actionType": "update",
    "entities": [
        {
            "type": "Bell",
            "id": "urn:ngsi-ld:Bell:001",
            "ring" : {
                "type": "command",
                "value": ""
            }
        }
    ]
}'