Developing OTA Capabilities on Devices


The OTA capability largely depends on the physical configuration and function of the device. EnOS provides a device SDK that includes OTA capabilities for hardware developers, which supports the following capabilities.

  • Reporting the firmware version: The device reports its version when it gets connected to EnOS. EnOS stores the device’s version number.

  • Receiving the upgrade request pushed by EnOS: The device receives the OTA upgrade request pushed by EnOS and downloads the firmware file.

  • Sending upgrade requests: The device can send upgrade requests to EnOS and check whether there are any new versions available.

  • Reporting upgrade progress and the causes of upgrade failure: The device can report its upgrade progress or the causes of upgrade failure during its upgrade process to EnOS for upgrade management.

Note

The upgrade depends on whether the flash on the device has enough physical space. EnOS only provides message channels and file download services for OTA upgrade, and SDKs for developers to call. The developers will need to ensure the device switches over to the new firmware to boot up after the upgrading process is finished.

Installing Device SDK

The upgrade request supports both MQTT-based message transmission and subscription and HTTP/HTTPS for message push and acquisition. For the respective steps and sample code, refer to the below.

Firmware Upgrade Protocol

EnOS provides the following message topics/endpoints for firmware upgrade.

Reporting the Firmware Version

The device can send its current firmware version to EnOS for you to create an upgrade job for the device. The device reports its current firmware version after it connects to EnOS through this topic/endpoint.


Upstream Topic/Message

  • Request: /sys/${productkey}/${devicekey}/ota/device/inform

  • Response: /sys/${productkey}/${devicekey}/ota/device/inform_reply


Request data format:

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.inform",
    "params": {
        "version":"xxxxxxxx"
    }
}

Response data format:

{
    "id": "123",
    "code": 200,
    "data": {}
}
Parameter Description

Parameters

Type

Mandatory/Optional

Description

id

String

Optional

The message ID. It is a reserved parameter that is reserved for future use.

version

String

Mandatory

The version of the protocol. The current version is 1.0.

method

String

Mandatory

The request method, which is “ota.device.inform”.

params

Object

Mandatory

The parameters used for reporting the version number.

version

String

Mandatory

The reported version number.

code

Integer

Mandatory

The return code. “200” indicates that the requested operation is executed successfully.

Receiving Upgrade Request From EnOS

After the firmware upgrade job is created in the console, qualified online devices will receive the firmware information pushed from EnOS, including the firmware version, MD5, and download URL. Offline devices will receive the upgrade request when they are online.


Downstream Topic (MQTT):

  • Request: /sys/${productkey}/${devicekey}/ota/device/upgrade

  • Response: /sys/${productkey}/${devicekey}/ota/device/upgrade_reply


Downstream Message (HTTP):

When there is an OTA command in the cloud, the command is included in the cloud device login or measurement point upload response.

  • Request command-payload: /ota/device/upgrade


Request data format:

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.upgrade",
    "params": {
        "version":"v1.0",
        "sign":"xxxxxxx",
        "signMethod":"md5",
        "fileUrl":"/1b30e0ea83002000/ota/kadak13",
        "fileSize":1024
    }
}

Response data format (MQTT):

{
    "id": "123",
    "code": 200,
    "data": {}
}
Parameter Description

Parameters

Type

Mandatory/Optional

Description

id

String

Optional

The message ID. It is a reserved parameter that is reserved for future use.

version

String

Mandatory

The version of the protocol. The current version is 1.0.

method

String

Mandatory

The request method, which is “ota.device.getversion”.

params

Struct

Optional

The parameters of the firmware details.

version

String

Mandatory

The firmware version.

sign

String

Mandatory

The firmware signature.

signMethod

String

Mandatory

The firmware signature algorithm.

fileUrl

String

Mandatory

The firmware file url.

fileSize

Long

Mandatory

The firmware file size in bytes.

code

Integer

Mandatory

The return code. “200” indicates that the requested operation is executed successfully.

data

Struct

Optional

The detailed returned information in JSON format.

Reporting Upgrade Progress

After the device starts to download the firmware, it reports its upgrade progress or causes of the upgrade failure through this topic/message. You can view the upgrade progress in the console.


Upstream Topic/Message:

  • Request: /sys/${productkey}/${devicekey}/ota/device/progress

  • Response: /sys/${productkey}/${devicekey}/ota/device/progress_reply


Request data format:

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.progress",
    "params": {
        "step":"1",
        "desc":"desc"
    }
}

Response data format:

{
    "id": "123",
    "code": 200,
    "data": {}
}
Parameter Description

Parameters

Type

Mandatory/Optional

Description

id

String

Optional

The message ID. It is a reserved parameter that is reserved for future use.

version

String

Mandatory

The version of the protocol. The current version is 1.0.

method

String

Mandatory

The request method, which is “ota.device.process”.

params

Struct

Mandatory

The parameters of the upgrade progress.

step

String

Mandatory

The upgrade progress. Its normal range is [0, 100], where:

-1 indicates failure -2 indicates download failure -3 indicates verification failure -4 indicates burning failure -5 indicates the device ignoring this firmware.

desc

String

Optional

The description of the current step, which may contain error information when exceptions occur.

code

Integer

Mandatory

The return code. “200” indicates that the requested operation is executed successfully.


Return Code

Error Message

Explanation

764

Device job not found

The OTA job of this device is not found.

765

Device job not start

The device has not started OTA upgrade yet.

Requesting Upgrade

Devices can request for an upgrade to obtain the upgradeable version information. EnOS creates the OTA upgrade policy as “Upon device request”. The device sends the upgrade request and receives the available versions returned from EnOS. If there are multiple versions available in the cloud, a list of the upgradeable versions will be returned and the device or its owner may select a suitable one from the list to upgrade.


Upstream Topic/Message:

  • Request: /sys/${productkey}/${devicekey}/ota/device/getversion

  • Response: /sys/${productkey}/${devicekey}/ota/device/getversion_reply


Request data format

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.getversion",
    "params": {
    }
}

Response data format:

{
    "id":"123",
    "code":200,
    "data": [
         {
            "version":"v1.0",
            "sign":"xxxxxxx",
            "signMethod":"md5",
            "fileUrl":"/1b30e0ea83002000/ota/kadak13",
            "fileSize":1024
        }
    ]
}
Parameter Description

Parameters

Type

Mandatory/Optional

Description

id

String

Optional

The message ID. It is a reserved parameter that is reserved for future use.

version

String

Mandatory

The version of the protocol. The current version is 1.0.

method

String

Mandatory

The request method, which is “ota.device.getversion”.

params

Struct

Optional

None

code

Integer

Mandatory

The return code. “200” indicates that the requested operation is executed successfully.

data

Array

Optional

The detailed returned information in JSON format. If there are multiple available versions for this device, the information for multiple versions will be returned.

version

String

Mandatory

The firmware version.

sign

String

Mandatory

The firmware signature.

signMethod

String

Mandatory

The firmware signature algorithm.

fileUrl

String

Mandatory

The firmware file URL.

fileSize

Long

Mandatory

The firmware file size in bytes.

Exception Handling

The exceptions that occur during a firmware upgrade is indicated by step and desc when the device reports the firmware upgrade progress. A step less than 0 indicates an exception. desc contains the description of this exception.

Upgrade Exceptions

Step Value

Description

-1

Undefined exception.

-2

Download failure.

-3

Verification failure.

-4

Burning failure.

For other customized exceptions, set step less than -4 and desc as the description to that exception.