Device firmware update is an important part of the IoT Hub service. When a device has new features available or vulnerabilities that need to be fixed, firmware update can be quickly performed for it through the device firmware update feature.
During the firmware update process, the device needs to subscribe to the following two topics to communicate with the cloud:
Below is a sample:
$ota/report/${productID}/${deviceName}
This topic is used to publish (upstream) messages, through which the device reports the version number and the download/update progress to the cloud.
$ota/update/${productID}/${deviceName}
This topic is used to subscribe to (downstream) messages, through which the device receives the update message from the cloud.
Taking MQTT as an example, the update process of the device is as follows:
The device reports its current version number. It publishes a message in JSON format with the following content to the $ota/report/${productID/${deviceName}
topic over the MQTT protocol to report its version number:
{
"type": "report_version",
"report":{
"version": "0.1"
}
}
// type: message type
// version: the reported version number
Log in to the IoT Hub console, upload the firmware, and update the specified device to the specified version.
After the firmware update operation is triggered, the device will receive a firmware update message with the following content through the subscribed $ota/update/${productID}/${deviceName}
topic:
{
"file_size": 708482,
"md5sum": "36eb5951179db14a63****a37a9322a2",
"type": "update_firmware",
"url": "https://ota-1255858890.cos.ap-guangzhou.myqcloud.com",
"version": "0.2"
}
// type: the message type is `update_firmware`
// version: updated version
// url: URL of the downloaded firmware
// md5asum: MD5 value of the firmware
// file_size: firmware size in bytes
After receiving the firmware update message, the device will download the firmware from the URL. During the download process, the device SDK keeps reporting the download progress with the following content through the $ota/report/${productID}/${deviceName}
topic:
{
"type": "report_progress",
"report":{
"progress":{
"state":"downloading",
"percent":"10",
"result_code":"0",
"result_msg":""
},
"version": "0.2"
}
}
// type: message type
// state: the status is "downloading"
// percent: the current download progress in percentages
After downloading the firmware, the device needs to report an update start message with the following content through the $ota/report/${productID}/${deviceName}
topic:
{
"type": "report_progress",
"report":{
"progress":{
"state":"burning",
"result_code":"0",
"result_msg":""
},
"version": "0.2"
}
}
// type: message type
// state: the status is "burning"
After the device firmware update is completed, the device will report an update success message with the following content to the $ota/report/${productID}/${deviceName}
topic:
{
"type": "report_progress",
"report":{
"progress":{
"state":"done",
"result_code":"0",
"result_msg":""
},
"version": "0.2"
}
}
// type: message type
// state: the status is "completed"
In the process of downloading or updating the firmware, if a failure occurs, an update failure message with the following content will be reported through the $ota/report/${productID}/${deviceName}
topic:
{
"type": "report_progress",
"report":{
"progress":{
"state":"fail",
"result_code":"-1",
"result_msg":"time_out"
},
"version": "0.2"
}
}
// state: the status is "failed"
// result_code: error code. -1: download timed out; -2: the file does not exist; -3: the signature expired; -4: MD5 mismatch; -5: firmware update failed
// result_msg: error message
IoT devices sometimes may be in weak network environments. In this case, the connection may be unstable, firmware download may be interrupted, and if the firmware is downloaded from offset 0 every time, it may never complete. Therefore, the checkpoint restart feature of firmware download is particularly necessary as detailed below:
The checkpoint restart process for OTA update is as follows:
Note:
- Steps 3–6 may be performed multiple times in a weak network environment, and step 7 will be performed only after they succeed.
- After step 3 is performed, the device will receive the message that step 4 needs to be performed.
Was this page helpful?