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.