This API is based on HTTP standards and based on a polling mechanism.

The hawkbit update server provides REST resources which are consumed by the device to retrieve software update tasks.

Note: in DDI the target is identified using a controllerId. Controller is used as a term for the actual service/client on the device. That allows users to have in some cases even multiple clients on the same target for different tasks, e.g. Firmware update and App management.

State Machine Mapping

For historical reasons the DDI has a different state machine and status messages than the Target State Machine of the hawkBit update server.

This is kept in order to ensure that DDI stays compatible for devices out there in the field. A future version “2” of DDI might change that. DDI also defines more states than the update server, e.g. multiple DDI states are currently mapped by the DDI implementation to RUNNING state. It is possible that in the future hawkBit will fully leverage these additional states.

The DDI API allows the device to provide the following feedback messages:

DDI status.execution type handling by update server Mapped ActionStatus type
CANCELED This is send by the target as confirmation of a cancelation request by the update server. CANCELED
REJECTED This is send by the target in case an update of a cancelation is rejected, i.e. cannot be fulfilled at this point in time. Note: the target should send a CLOSED->ERROR if it believes it will not be able to proceed the action at all. WARNING
CLOSED Target completes the action either with status.result.finished SUCCESS or FAILURE as result. Note: DDI defines also a status NONE which will not be interpreted by the update server and handled like SUCCESS. ERROR (DDI FAILURE) or FINISHED (DDI SUCCESS or NONE)
PROCEEDING This can be used by the target to inform that it is working on the action. RUNNING
SCHEDULED This can be used by the target to inform that it scheduled on the action. RUNNING
RESUMED This can be used by the target to inform that it continued to work on the action. RUNNING

Resource Overview

The following chapters provide basic examples for the most important resources but we provide also a detailed resource documentation.

Base Poll Resource

GET /{tenant}/controller/v1/{controllerId}

In the answer to the baseUrl polling the backend can send action links. A possible action is a deploy command. The client makes a GET request on the given link:

Example Response

{
    "config": {
        "polling": {
            "sleep": "00:05:00"
        }
    },
    "_links": {
        "deploymentBase": {
            "href": "http://localhost:8080/default/controller/v1/example/deploymentBase/1?c=644088541"
        },
        "configData": {
            "href": "http://localhost:8080/default/controller/v1/example/configData"
        }
    }
}

Deployment Base Resource

GET /{tenant}/controller/v1/{controllerId}/deploymentBase/{id}

Example Response

{
    "deployment": {
        "download": "forced",
        "update": "forced",
        "chunks": [
            {
                "part": "os",
                "version": "1.0.0",
                "name": "Linux",
                "artifacts": [
                    {
                        "filename": "linux.zip",
                        "hashes": {
                            "sha1": "46fc56de883ec027759d8513458fe1010aa7e793",
                            "md5": "5813e9655bd6871d0c25b8d510fd8605"
                        },
                        "size": 52167,
                        "_links": {
                            "download": {
                                "href": "http://localhost:8080/default/controller/v1/example/softwaremodules/1/artifacts/linux.zip"
                            },
                            "md5sum": {
                                "href": "http://localhost:8080/default/controller/v1/example/softwaremodules/1/artifacts/linux.zip.MD5SUM"
                            }
                        }
                    }
                ]
            }
        ]
    },
    "id": "1",
    "actionHistory": {
        "status": "RETRIEVED",
        "messages": [
            "Installing update",
            "Downloading artifacts"
            ]
    }
}

Deployment Feedback Resource

To every deployment the client can post feedback back to the update-server about the deployment status.

POST /{tenant}/controller/v1/{controllerId}/deploymentBase/{id}/feedback
Content-Type: application/json

Example Body Deployment Success

{
    "id": 1,
    "time": "20140511T121314",
    "status": {
        "execution": "closed",
        "result": {
            "finished": "success",
            "progress": {}
        }
    }
}

Example Body Deployment Proceeding

{
    "id": "1",
    "time": "20140511T121314",
    "status": {
        "execution": "proceeding",
        "result": {
            "finished": "none",
            "progress": {
                "cnt": 2,
                "of": 5
            }
        },
        "details": [
            "checking hash sums"
        ]
    }
}

Example Body Deployment Error

{
    "id": 1,
    "time": "20140511T121314",
    "status": {
        "execution": "rejected",
        "result": {
            "finished": "failure",
            "progress": {}
        },
        "details": [
            "something bad happend"
        ]
    }
}