Developing OTA Capabilities on Devices¶

Device-side OTA upgrades largely depend on the device’s physical space and functional implementation. The EnOS cloud provides developers with a Device SDK that includes OTA capabilities, supporting the following features:

Device reports firmware version: When the device establishes a connection with the cloud, it reports the current version information, which is recorded by the cloud.
Device receives cloud-initiated upgrade push request: The device receives an upgrade request pushed by the cloud and downloads the firmware file.
Device proactively requests available firmware versions: The device can query the cloud and retrieve information about available upgradeable versions.
Device reports upgrade progress and failure reasons: During the upgrade process, the device reports progress or the reasons for failure, facilitating remote management.

Note

Device OTA upgrades require corresponding physical conditions. The EnOS cloud provides message channels and file download services, encapsulating interface capabilities through the SDK. The device side must independently implement firmware switching, booting, and restarting logic after downloading, ensuring sufficient Flash space.

Installing Device SDK¶

Upgrade requests support message sending and subscription via MQTT, as well as message pushing and retrieval via HTTP. For detailed steps and example code, refer to the following:

Firmware Upgrade Protocol Specification¶

EnOS provides the following message topics and endpoints for firmware upgrades.

Device Reports Version¶

The device side can send the current firmware version number to the cloud. Only devices that have reported the firmware version number can create upgrade tasks in Application Portal. After each successful connection between the device and the cloud, the device will report the current version number information through this topic/endpoint.

Upstream Topic¶

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	Required	Description
id	Long	Optional	Message ID, reserved value
version	String	Required	Protocol version number, currently 1.0
method	String	Required	Request method, fixed to `ota.device.inform`
params	Object	Required	Reported version number parameter
version	String	Required	Reported firmware version number
code	Integer	Required	Return code, 200 means success

Receive Cloud Upgrade Request¶

After creating a cloud-pushed firmware upgrade task in Application Portal, eligible online devices will receive firmware information including version number, MD5 and download URL. Offline devices will receive the request the next time they go online.

Downstream Topic (MQTT)¶

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

Downstream Information (HTTP)¶

Request endpoint: /ota/device/upgrade (included in the response of device login or measurement point upload)

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¶

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

Parameter Description¶

Parameter	Type	Required or not	Description
id	Long	Optional	Message ID, reserved value
version	String	Required	Protocol version number, currently 1.0
method	String	Required	Request method, fixed to `ota.device.upgrade`
params	Object	Required	Firmware information parameters
version	String	Required	Firmware version number
sign	String	Required	Firmware signature
signMethod	String	Required	Signature algorithm (such as md5)
fileUrl	String	Required	Firmware file download URL
fileSize	Long	Required	Firmware size (bytes)
code	Integer	Required	Return code, 200 means success

Report Firmware Upgrade Progress¶

After the device downloads the firmware, you can report the upgrade progress or failure reason through the following Topic, and the operation and maintenance personnel can view it in Application Portal.

Upstream Topic¶

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": "xxxxxxxx"
    }
}

Response Data Format¶

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

Parameter Description¶

Parameters	Type	Required	Description
id	Long	Optional	Message ID, reserved value
version	String	Required	Protocol version number, currently 1.0
method	String	Required	Request method, fixed to `ota.device.progress`
params	Object	Required	Report progress parameters
step	String	Required	Upgrade progress (0-100 represents percentage, negative number represents failure, see the table below for details)
desc	String	Optional	Progress description or error message
code	Integer	Required	Return code, 200 represents success

Step Value Description¶

Step value	Meaning
-1	Failed to upgrade the firmware version
-2	Failed to download the firmware
-3	Failed to verify the firmware
-4	Failed to burn the firmware
-5	Device actively ignores

Return Code Description¶

Return code	Error message	Explanation
764	Device task not found	No relevant OTA upgrade task was found
765	Device task not start	The device has not started the OTA upgrade task

Actively Request an Upgrade¶

The device can actively request to obtain the upgradeable version information. If the cloud is configured with the “Device Request Upgrade” policy, a list of available firmware will be returned, and the device or owner will select the upgrade version.

Upstream Topic¶

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¶

:widths: auto :header-rows: 1¶
Parameter	Type	Required or not	Description
id	Long	Optional	Message ID, reserved value
version	String	Required	Protocol version number, currently protocol version 1.0
method	String	Required	Request method, fixed to `ota.device.getversion`
params	Object	Optional	None
code	Integer	Required	Result return code, 200 Indicates that the request was successfully executed
data	List	Optional	Detailed information returned in JSON format. If the device has multiple upgradeable versions in the cloud, multiple version information will be returned
version	String	Required	Firmware version number
sign	String	Required	Firmware signature
signMethod	String	Required	Firmware signature algorithm
fileUrl	String	Required	Firmware file url
fileSize	Long	Required	Firmware file size, unit: bytes

Exceptions Handling¶

Exceptions during the upgrade process can be indicated by reporting progress parameters step and desc. step less than 0 indicates exception, and desc provides a detailed description.

System Defined Exceptions¶

step value	meaning
-1	Undefined exception
-2	Download failed
-3	Verification failed
-4	Program failed
-5	Device actively ignored

Custom Exceptions¶

If you need to define other exceptions, set step to a value less than -5 and describe the specific situation in desc.