Perform OTA updates - IoT Platform - Alibaba Cloud Documentation Center

IoT Platform supports the over-the-air (OTA) feature. You can use the OTA feature to update devices. This topic describes how to use the OTA feature to update devices when Message Queuing Telemetry Transport (MQTT) is used to connect the devices to IoT Platform. This topic also describes the topics and data formats that are used during data forwarding in OTA updates.

Process

The following figure shows the process of performing an OTA update over MQTT.

Notes

To perform a differential update, the device must submit the version number of an OTA module. To perform a full update, the device does not need to submit the version number of an OTA module. If the version number is not submitted, you cannot specify a source version when you configure a batch update. For more information, see Initiate a batch update.
A device needs to submit the version number only once during the startup before the first update. After the update is installed on the device, the device must immediately submit the current version number.
When you start to update multiple devices in the IoT Platform console, each device is in the Pending Update state.
When IoT Platform receives the update progress that is submitted by a device, the status of the device changes to Updating.
Note After a device receives an update notification from IoT Platform, the device can download the update package and perform an update immediately or during off-peak business hours.
IoT Platform checks whether an OTA update is successful based on the version number that is submitted by the device.
An offline device cannot receive an update notification from IoT Platform.
After the device goes online, IoT Platform checks whether the device needs to be updated. If an update is required, IoT Platform sends an update notification to the device. Otherwise, no notification is sent.

Message formats

For more information about how to use language-specific SDKs to implement OTA updates on devices, see the Link SDK documentation.

The following steps describe the process of performing an OTA update.

Optional. Connect a device to the OTA service of IoT Platform and submit the version number.

The version number is pushed to the following topic over MQTT: /ota/device/inform/${productKey}/${deviceName}. Sample message:

{
    "id": "123",
    "params": {
        "version": "1.0.1",
        "module": "MCU"
    }
}

Table 1. Parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the OTA module.
module	String	The name of the OTA module. Note If the device submits the version of the default module, the module parameter is optional. The version of the default module indicates the version of the device firmware.

In the IoT Platform console, add an update package, check the update package, and then start a batch update.
For more information, see Overview.

After you start an update in the IoT Platform console, the device receives the URL of the update package from a topic.

The message that includes the URL is sent from the OTA service of IoT Platform to the following topic: /ota/device/upgrade/${productKey}/${deviceName}. After IoT Platform sends an OTA update request to the device, the device receives the URL of the update package from the topic.

Sample message:

Sample information about an OTA update package that contains a single file:

Download the OTA update package over HTTPS:

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the camera driver to prevent blurry videos. \"}"
        }
    }
}

Download the OTA update package over MQTT:

{
    "id": "123",
    "code": 200,
    "data":{
        "size":432945,
        "digestsign":"A4WOP***SYHJ6DDDJD9***",
        "version":"2.0.0",
        "isDiff":1,
        "signMethod":"MD5",
        "dProtocol":"mqtt",
        "streamId":1397345,
        "streamFileId":1,
        "md5":"93230c3bde***",
        "sign":"93230c3bde42***",
        "module":"MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2"
        }
    }
}

You can download an OTA update package that contains multiple files only over HTTP. Sample information:

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the camera driver to prevent blurry videos. \"}"
        }
    }
}

Table 2. Parameters
Parameter	Type	Description
id	Long	The ID of the message. Each message ID is unique for the device.
message	String	The response message.
code	String	The HTTP status code.
version	String	The version of the OTA update package.
size	Long	The size of the update package. Unit: bytes. This parameter is available if the OTA update package contains a single file.
url	String	The Object Storage Service (OSS) URL of the OTA update package. This parameter is available if the OTA update package contains a single file and the download protocol is HTTPS.
dProtocol	String	The protocol that is used to download the OTA update package. This parameter is available if the download protocol is MQTT.
streamId	Long	The unique ID generated when you download the OTA update package over MQTT. This parameter is available if the download protocol is MQTT.
streamFileId	Integer	The unique ID of the OTA update package that contains a single file. This parameter is available if the download protocol is MQTT.
isDiff	Long	This parameter is available if an update package is a delta update package. Set the value to 1. This value specifies that the update package contains only the differences between the new version and the previous version. In this case, a delta update is performed.
digestsign	String	The signature of the OTA update package after a secure update is performed. This parameter is available if the secure update feature is enabled for an OTA update package. For more information about how to enable the secure update feature, see Add an update package.
sign	String	The signature of the OTA update package. This parameter is available if the OTA update package contains a single file.
signMethod	String	The signature algorithm. Valid values: `SHA256` `MD5` Delta update packages for Android support only the MD5 algorithm.
md5	String	If the signature algorithm is MD5, IoT Platform specifies values for the sign and md5 parameters. This parameter is available if the OTA update package contains a single file.
module	String	The name of the module to which the OTA update package is applied. Note If the OTA update package is applied to the default module, IoT Platform does not send the module parameter.
extData	Object	The tags of the update batch and the custom information that you want IoT Platform to push to the device. _package_udi specifies the custom information. Format of each tag: `"key":"value"`.
files	Array	The information about files in an update package. This parameter is available if the OTA update package contains multiple files. Information about a single file: fileSize: the size of the file. fileName: the name of the file. fileUrl, fileMd5, and fileSign: These parameters correspond to the url, md5, and sign parameters in this table.

Optional. Download the update package within 24 hours after the device SDK receives the URL of the update package. Otherwise, the URL expires. The device can request a new update task from IoT Platform by sending a message to the following topic:

/sys/${productKey}/${deviceName}/thing/ota/firmware/get. Sample message:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "module": "MCU"
    },
    "method": "thing.ota.firmware.get"
}

Table 4. Parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Set the value to 1.0.
params	Object	The request parameters.
module	String	The name of the module to which the OTA update package is applied. Note If you do not configure this parameter, the update package information of the default module is requested.
method	String	The request method. Set the value to `thing.ota.firmware.get`.

After IoT Platform receives the request, IoT Platform sends the update package information to the following topic: /sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply.

IoT Platform sends the information about the latest update package to the device. Sample responses:

Sample information about an OTA update package that contains a single file:

Download the OTA update package over HTTPS:

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the camera driver to prevent blurry videos. \"}"
        }
    }
}

Download the OTA update package over MQTT:

{
    "id": "123",
    "code": 200,
    "data":{
        "size":432945,
        "digestsign":"A4WOP***SYHJ6DDDJD9***",
        "version":"2.0.0",
        "isDiff":1,
        "signMethod":"MD5",
        "dProtocol":"mqtt",
        "streamId":1397345,
        "streamFileId":1,
        "md5":"93230c3bde***",
        "sign":"93230c3bde42***",
        "module":"MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2"
        }
    }
}

You can download an OTA update package that contains multiple files only over HTTP. Sample information:

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the camera driver to prevent blurry videos. \"}"
        }
    }
}

Table 1. The following table describes the parameters.
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device. The message ID in the response is the same as the message ID in the request. You can view the `id` parameter in the data that is submitted to the /sys/${productKey}/${deviceName}/thing/ota/firmware/get topic.
code	Integer	The status code. A value of 200 indicates a successful request.
data	String	The information about the update package. For more information, see Push OTA update package information to a device.

IoT Platform sends a response if no update package information exists. Sample response:
```
{
    "id": "123",
    "code": 200,
    "data": {
    }
}
```

After the device SDK receives the URL of the update package, the device calls an API operation in the SDK to download the update package. For more information, see Overview.
Note The device cannot automatically download the update package. You must call the required operation in the SDK to download the update package. If the device fails to download the update package from the URL within 24 hours, the URL expires.
For more information about the logs that are generated when you download the update package, see the following topics:

During an update, the device sends the update progress to the following topic: /ota/device/progress/${productKey}/${deviceName}.

Note We recommend that you set the progress reporting frequency to a maximum of once every 3 seconds. If the actual frequency exceeds the limit, you may fail to view all the progress information on the Batch Details page of the OTA update package in the IoT Platform console.

Sample message:

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "OTA update failed because no update package information is found.",
        "module": "MCU"
    }
}

Table 3. Parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
step	String	The progress of the OTA update. Valid values: An integer from 1 to 100: indicates a percentage that represents the update progress. `-1`: indicates that the update failed. `-2`: indicates that the download failed. `-3`: indicates that the verification failed. `-4`: indicates that the firmware flashing failed. The progress value and description of OTA updates can be configured in the device based on actual requirements. For more information about how to develop the OTA update feature in a device, see Sample code.
desc	String	The description of the current step. The description cannot exceed 128 characters in length. If an exception occurs, this parameter contains the error message.
module	String	The name of the module to which the OTA update package is applied. For more information, see Add an update package. Note If the device submits the update progress of the default module, the module parameter is optional.

After the OTA update of a device is completed, the device sends the current firmware version to the following topic: /ota/device/inform/${productKey}/${deviceName}. If the submitted version is the same as the version that is sent by the OTA service to the topic, the OTA update is successful. Otherwise, the OTA update fails.
Note IoT Platform checks whether an OTA update is successful based on the submitted firmware version. For example, a device submits an update progress of 100%. However, if the current firmware version is not submitted within a specified timeout period, IoT Platform considers that the update fails.
We recommend that you immediately restart the device after the OTA update is completed. After the device goes online, submit the current version number. The interval between a request to connect the device to IoT Platform and a request to submit the current version number cannot exceed 2 seconds.

Common errors

The signature is invalid. If the URL of an update package is invalid or changed, this error occurs, as shown in the following figure.
The access is denied. The error occurred because the URL has expired. Each URL is valid for 24 hours.

API reference

OTA updates