Software and firmware update is the most complete operation OpenGate models: it is long-running, multi-step, and its progress matters as much as its outcome. It is therefore a good example of the asynchronous flow with multiple responses.

Flow diagram

OpenGate suggests a complete flow covering all the possible stages of a device update. In the real world a device may implement only part of these steps — any number and kind of steps implemented by your device is supported.

sequenceDiagram
    participant OG as OpenGate connector
    participant Dev as Device

    OG->>Dev: Operation request (HTTP POST)
    Dev-->>OG: Response ACK (HTTP 200 OK)

    Note over OG,Dev: the device reports progress,<br>one notification per step

    Dev->>OG: STEP DOWNLOADFILE (0%)
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP DOWNLOADFILE (x%)
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP DOWNLOADFILE (100%)
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP BEGINPREACTION
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP ENDPREACTION
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP BEGINPOSTACTION
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP ENDPOSTACTION
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP BEGININSTALL
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP ENDINSTALL
    OG-->>Dev: ACK (HTTP 200 OK)
    Dev->>OG: STEP ENDUPDATE
    OG-->>Dev: ACK (HTTP 200 OK)

Each notification is an HTTP POST from the device carrying the operation response, and each ACK is OpenGate’s HTTP 200 reply. Every notification updates the operation’s steps array, so the north API sees the download percentage advance in real time.

The UPDATE operation type declares the following steps: ACCEPTED, BEGINUPDATE, DOWNLOADFILE, BEGINPREACTION, ENDPREACTION, BEGININSTALL, ENDINSTALL, BEGINPOSTACTION, ENDPOSTACTION and ENDUPDATE. See the status reference for the results a step can report.

North API invocation

Back office applications invoke device update operations through the ordinary jobs API — everything you know about jobs applies. What is specific to updates is the operation name and its parameters:

Device Update Example

{
    "job" :
    {
        "request" : {
            "name" : "UPDATE",
            "parameters": [
                {
                    "name" : "bundleName",
                    "type":"string",
                    "value" : {
                        "string" : "bundle_1"
                    }
                },
                {
                    "name" : "bundleVersion",
                    "type":"string",
                    "value" : {
                        "string" : "1.0"
                    }
                }
            ],
            "active" : true,
            "notify" : true,
            "callback" : "http://[your_application_address]/[your_URI]",

            "schedule" : {
                "start" : {
                  "date" : "2012-09-10T12:33:43Z"
                },
                "stop" : {
                  "delayed" : 300000
                }
            },
            "operationParameters" : {
                "ackTimeout" : 5000,
                "timeout" : 6000,
                "retries" : 0,
                "retriesDelay" : 1000,
                "retryResultList" : ["ERROR_PROCESSING"]
            },
            "target" : {
                "append" : {
                    "entities" : [ "device_1", "device_2" ]
                }
            }
        }
    }
}

South API invocation

This is the document the device receives from the platform. The deploymentElements array is what makes an update different from any other operation: it tells the device what to download, where to put it, in which order, and how to verify it.

See the device integration section for the endpoints and transport details:

Device Update Example

{
    "operation": {
        "request": {
            "timestamp": 1453822201099,
            "name": "UPDATE",
            "parameters": [
                {
                    "name": "bundleName",
                    "value": {
                        "string": "bundle_1"
                    }
                },
                {
                    "name": "bundleVersion",
                    "value": {
                        "string": "version_1"
                    }
                },
                {
                    "name": "deploymentElements",
                    "value": {
                        "array": [
                            {
                                "type": "FIRMWARE",
                                "downloadUrl": "http://[your_opengate_address]/bundles/74427c0c-a28c-4765-92ef-30010adb733d/1002/firmware-1_1.1.bin",
                                "path": "/home",
                                "order": 1,
                                "operation": "INSTALL",
                                "option": "OPTIONAL",
                                "validators": [
                                    {
                                        "type": "SHA-256",
                                        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
                                    }
                                ],
                                "size": 18
                            }
                        ]
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}