The operations API defines the way the platform interacts with the Devices to perform remote operations on the device and receive the associated response.

The platform implements by default a set of device operation types that it is recommended to be implemented by the device. Find the list in the Default Operations Catalogue

To understand the possible behaviours you need understand first the next concepts:

  • Flow Strategies (Synchronous/Asynchronous): Describe different alternatives to manage the message exchange between Platform and Device using HTTP protocol

  • Operation Structure (Simple/Multistep): Describe different possibilities to complete the result of the operation. Sometimes it is necessary that the operation can be completed in two or more steps (example: update or reboot operation)

Flow Strategies

  • Synchronous: The Request/Response is embedded in a only HTTP dialog. Only a HTTP connection is used

opengate api south operation workflows synchronous
Figure 1. Synchronous Operation Strategy

  • Asynchronous :The Request/Response is embedded in different HTTP dialogues. At two or more HTTPs connections is used to communicate the request and to communicate the response or responses

    • Simple Response: Only a Final Response message is sent by the Device to answer the Request

opengate api south operation workflows asynchronous simple
Figure 2. Asynchronous Operation Strategy - Simple Response

  • Multiple Response: Multiple Partial responses can be sent by the device and a Final Response at the end of the sequence

opengate api south operation workflows asynchronous multiple
Figure 3. Asynchronous Operation Strategy - Multiple Responses

Operation Structure

  • Simple Request/Response: The Operation has only a Request and a Response to finish it. There is no intermediate steps. It can be used Synchronous or Asynchronous (Simple response) flow strategy

Example 1. Simple Response
1 Device Operation Request Json Object
{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": [
                {
                    "name": "type",
                    "value": {
                        "string": "HARDWARE"
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}
2 Device Operation Final Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": []
        }
    }
}

Note that the field "resultCode" is present in the final response

  • Multistep Response: The Operation requires a list of steps to track the operation. This steps can arrive all together in the final response or gradually in partial responses until finishing with the Final response. It can be used Synchronous or Asynchronous (Simple or Multiple response) flow strategy

Example 2. Multistep Simple Response
1 Device Operation Request Json Object
{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": [
                {
                    "name": "type",
                    "value": {
                        "string": "HARDWARE"
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}
2 Device Operation Final Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": [
                {
                    "name" : "STEP_1",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                },
                {
                    "name" : "STEP_2",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                }
            ]
        }
    }
}

Note that the field "resultCode" is present in the final response
Example 3. Multistep Multiple Responses
1 Device Operation Request Json Object
{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": [
                {
                    "name": "type",
                    "value": {
                        "string": "HARDWARE"
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}
2 Device Operation Partial Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "variableList": [],
            "steps": [
                {
                    "name" : "STEP_1",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                }
            ]
        }
    }
}
3 Device Operation Final Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278500,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": [
			    {
                    "name" : "STEP_2",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                }
			]
        }
    }
}

Note that the field "resultCode" is present in the final response

URIs

Attending to the flow strategies described above shouth operations API can be summarized:

  • It is used HTTP request/response mechanism with and embedded JSON file to both flow directions:

    • Platform → Device: Synchronous/Asynchronous Operation Request

    • Device → Platform:

      • Operation Response

      • On demand Request

  • Both Platform and Device must to implement a HTTP web service publishing a URI as defined in the next table

Table 1. Operation URIs and ports
Side URI Port

Device

/v80/devices/{device.id}/operation/request

1123 / 11235 (secure mode)

Platform

/south/v80/devices/{device.id}/operation/response

/south/v80/devices/{device.id}/operation/pending

Implicit the port through /south/

Operation Request

POST /south/v80/devices/{device.id}/operation/request

The device is notified by the platform using the URI above with the Operation Request to be executed

As stated in the workflow figure, the platform sends a HTTP request to the device using this URI.

JSON Object

This is the JSON object embedded to the HTTP Request

Table 2. Operation object attributes
Attribute Description

request
Table 3. Operation Request object attributes
Attribute Description

id

Unique identifier (platform generated) for the request. This will contain an string in UUID format

timestamp

Number with the time in seconds from epoch when platform has launched the request

deviceId(optional)

Only used when device that executes the operation is different than the device used as a gateway or proxy. Example: Operation on a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

path

Array of device identifiers traversed from the Gateway device to reach the deviceId device

Filled only when devices is not connected directly to the platform. See Device to Platform connection scenarios

name

String with the name or identifier of the type of operation.

The platform implements by default a set of device operations type that it is recommended to be implemented by the device. Find the list in the Default Operations Catalogue

New, adhoc operations can be added to the platform depending on the device capabilities

parameters[]

Array of parameters associated to the operation request. See Parameter Object
Table 4. Operation Request parameter object attributes
Attribute Description

name

Name of the parameter

value

This is a polyvalent field that can be any of the JSON supported data types:

"value" : 10

  • String delimited with double-quotation marks. Example:

"value" : "string value"

  • Boolean either of the values true or false. Example:

"value" : true

  • Array of JSON data types. Example:

"value" : [ "text1", "text2" ]

  • Object with JSON format. Example:

"value" : {
    "field1": "text",
    "field2": 12
}

  • Null. Example:

"value" : null

Operation Request Example

HTTP Request JSON example
{
    "operation" :
    {
        "request" :
        {
            "id" : "f508ce84-01e9-11e5-a322-1697f925ec7b",
            "deviceId": "device_1",
            "path" : [],
            "timestamp" : 1432454275000,
            "name" : "SET_CLOCK",
            "parameters": [
                {
                    "name" : "datetime",
                    "value" : "YYYY-MM-DD"
                },
                {
                    "name" : "time",
                    "value" : "hh:mm:ss.s"
                },
                {
                    "name" : "timezone",
                    "value" : "(+/-)hh:mm"
                },
                {
                    "name" : "daylightsavingtime",
                    "value" : "(+/-)hh:mm"
                }
            ]
        }
    }
}

A similar behaviour of the platform can be implemented using CURL

curl --request POST \
     --data-binary @opengate-api-south-operation-request-set-clock.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_device_address]/south/v80/devices/{device.id}/operation/request \
     -H "Content-type: application/json"

On demand Operation Request

Is a mechanism to allow the Device asking for the pending operations requests to the Platform. The platform answers with the pending requests.

opengate api south operation workflows ondemand
Figure 4. Ondemand Operation Request

Used by the devices that are sleeping when they wake up to take pending operation requests

POST /south/v80/devices/{device.id}/operation/pending

The device ask to the platform for pending operations using the URI above with the Operation Request to be executed

JSON Objects

Table 5. On demand operation object
Attribute Description

trustedBoot(optional)

In this case you are indicating that is required a validation type trusted_boot, it’s not necessary introduce the field value but if you introduce it all the message received by the platform will compare the trustedBoot value with the provisioned value if are diferent the message will not be collected

operation

See Operation request object definition
Table 6. Operation Request object attributes
Attribute Description

deviceId(optional)

Only used when device that executes the operation is different than the device used as a gateway or proxy. Example: Operation on a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

path(optional)

Array of device identifiers traversed from the Gateway device to reach the deviceId device

Only the next pending operation request is returned. If there is more than one pending operations the device has to call several times until there is no more operation requests pending

As stated in the work flow figure, the device sends a HTTP request to the platform using this URI

If you are going to use http this is an example using curl of operation request

curl --request POST \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_platform_address]/south/v80/devices/{device.id}/operation/pending \
     -H "Content-type: application/json"
Example of ondemand operation request json from an asset
{
    "trustedBoot": "ñasdohfñasjkdfñ",
    "operation": {
        "request": {
            "deviceId": "asset_1",
            "path": [
                "gateway1"
            ]
        }
    }
}

In the response we should see a status code of 201 (created)

HTTP/1.1 201 Created

If you are going to use mqtt you have to send a message to the topic odm/operationOnDemand with a string with deviceId identification

The device must be waiting some seconds for receiving the request of the pending operation, the platform will send the first of the operations ordered by date, the older the first, when the device finish the execution of an operation have to ask again for new operations repiting the last cicle. when there is no more operation the device will not recive a request.

Response (Device to Platform)

POST /south/v80/devices/{device.id}/operation/response

There is no difference between Synchronous and Asynchronous flow strategies implies regarding to the Jsons format. Only when this file is embedded in to the HTTP body

  • Synchronous: The file is embedded in the HTTP Response

  • Asynchronous: : The file is embedded in a new HTTP POST initiated in the device

JSON Object

Table 7. Reponse object
Attribute Description

version

indicates the version of the structure

trustedBoot(optional)

In this case you are indicating that is required a validation type trusted_boot, it’s not necessary introduce the field value but if you introduce it all the message received by the platform will compare the trustedBoot value with the provisioned value if are diferent the message will not be collected

operation

See Operation Response object definition
Table 8. Operation Response object attributes
Attribute Description

id

Unique identifier (platform generated) for the request/response. This will contain an string in UUID format and it must be the same than the received request

timestamp

Number with the time in seconds from epoch when platform has launched the request

deviceId (optional, mandatory with MQTT)

Only used when device that response to the executed operation is different than the device used as a gateway or proxy. Example: Operation on a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

name

String with the name or identifier of the type of operation.

The platform implements by default a set of device operations type that it is recommended to be implemented by the device. Find the list in the Default Operations Catalogue

New, adhoc operations can be added to the platform depending on the device capabilities

path

String indicating the path of the underliying device

resultCode (optional)

String indicating the result code. Valid values are:

  • SUCCESSFUL: The operation request has been executed and finished without errors

  • OPERATION_PENDING

  • ERROR_IN_PARAM

  • NOT_SUPPORTED

  • ALREADY_IN_PROGRESS

  • ERROR_PROCESSING

  • ERROR_TIMEOUT

  • TIMEOUT_CANCELLED

  • CANCELLED

  • CANCELLED_INTERNAL

When this field is present the platform considers that the operation has finished

If the field is not present the platform considers a partial response in a multi-step operation that requires notifying intermediate results before to complete the operation. Example File downloading progress

resultDescription (optional)

String indicating the result code. Present when "resultCode" parameter is included

steps[](optional)

Array of steps returned associated to the operation response. See Step Object
Table 9. Operation Response Step object attributes
Attribute Description

name

String with the name of the step.

result

String indicating the result code. Valid values are:

  • ERROR: The step has been executed and finished with error

  • SUCCESSFUL: The step has been executed and finished with success

  • SKIPPED

timestamp

Number with the time in seconds from epoch when platform has launched the request

description

String describing the result

response[](optional)

Array of variables returned associated to the step. See Parameter Object
Operation Response JSON example
{
    "version" : "7.0",
    "operation" :
    {
        "response" :
        {
            "id" : "f508ce84-01e9-11e5-a322-1697f925ec7b",
            "timestamp" : 1432454282000,
            "deviceId" : "device_1",
            "name" : "SET_CLOCK",
            "resultCode" : "SUCCESS",
            "resultDescription" : "No Error",
        }
    }
}

As stated in the work flow figure, the device sends a HTTP or HTTPS request on the device using this URI

A similar behaviour of the platform can be implemented using CURL

curl --request POST \
     --data-binary @operation_response.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/south/v80/devices/{device.id}/operation/response \
     -H "Content-type: application/json"

Multistep Operation JSON example

Operation Request
{
    "operation" :
    {
        "request" :
        {
            "id" : "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
            "deviceId": "device_1",
            "path" : [],
            "timestamp" : 1432454276000,
            "name" : "EQUIPMENT_DIAGNOSTIC",
            "parameters": [
                {
                    "name" : "name",
                    "value" : "DEVICE"
                }
            ]
        }
    }
}
Operation Response JSON example
{
    "version" : "7.0",
    "operation" :
    {
        "response" :
        {
            "id" : "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
            "timestamp" : 1432454278000,
            "deviceId" : "device_1",
            "name" : "EQUIPMENT_DIAGNOSTIC",
            "resultCode" : "SUCCESS",
            "resultDescription" : "No Error",
            "steps":[
                {
                    "name":"MOTHER_BOARD",
                    "timestamp" : 1432454278000,
                    "result":"SUCCESSFUL",
                    "description":"Motherboard is Ok"
                },
                {
                    "name":"COMMUNICATIONS_MODULE",
                    "timestamp" : 1432454278000,
                    "result":"SUCCESSFUL",
                    "description":"Communications is Ok"
                },
                {
                    "name":"STORAGE",
                    "timestamp" : 1432454278000,
                    "result":"SUCCESSFUL",
                    "description":"Storage is Ok"
                }
            ]
        }
    }
}

Security

In this flow the platform is implements the role of HTTP server and it has to implement the next security strategy:

By default the security mechanism implemented by the platform is based on API_KEY. This key is included in the HTTP header.

It is possible configure the platform to use a different KEY organization or per channel.

HTTPS for encryption messages is supported and can be configured in the platform.

Other mechanisms as mutual authentication using HTTPS PKI infrastructure can be supported.