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": {}
}
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": {}
}
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": {}
}
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:
|
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
}
]
}
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.
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.