OTA updates-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

IoT Platform provides over-the-air (OTA) update and management services. This topic describes the topics and data formats for OTA update messages. These messages include device reports of OTA module versions, upgrade package information pushed by IoT Platform, device reports of upgrade progress, and device requests for the latest upgrade package information.

For the complete OTA update procedure, see OTA update steps.

Device reports for OTA module versions

Uplink data.

Topic: /ota/device/inform/${productKey}/${deviceName}.

A device uses this topic to report its current OTA module version.

Important This topic supports reporting the version of only one module per message. If a device has multiple modules, you must report the version of each module in a separate message.

Request data format:

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

Table 1. Parameter descriptions
Parameter	Type	Description
id	String	The message ID. A string-type number. The value must be unique for the device. The value can range from 0 to 4294967295.
version	String	The version of the OTA module.
module	String	The name of the OTA module. Note The module parameter is optional when you report the version number of the default module. The version number of the default module represents the firmware version number of the entire device.

IoT Platform pushes OTA upgrade package information

Downlink data.

Topic: /ota/device/upgrade/${productKey}/${deviceName}.

IoT Platform uses this topic to push OTA upgrade package information. A device can subscribe to this topic to receive the information.

For an OTA upgrade package that contains a single file:

If the download protocol for the upgrade package is HTTPS:

{
    "code": "1000",
    "data": {
        "size": 432945,
        "version": "2.0.0",
        "isDiff": 1,
        "url": "https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P6DW***qAKU%3D&security-token=***Tz2IHtIf3***",
        "md5": "93230c3bde425a9d***",
        "digestsign":"A4WOP***SYHJ6DDDJD9***",
        "sign": "93230c3bde425a9d***",
        "signMethod": "MD5",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

If the download protocol for the upgrade package is MQTT:

{
    "code":"1000",
    "data":{
        "size":432945,
        "version":"2.0.0",
        "isDiff":1,
        "signMethod":"MD5",
        "dProtocol":"mqtt",
        "streamId":1397345,
        "streamFileId":1,
        "md5":"93230c3bde425***",
        "digestsign":"A4WOP***SYHJ6DDDJD9***",
        "sign":"93230c3bde425***",
        "module":"MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2"
        }
    },
    "id":1507707025,
    "message":"success"
}

OTA upgrade packages that contain multiple files support only the HTTP download protocol. The data format is as follows:

{
    "code": "1000",
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d***",
                "fileSign":"93230c3bde425a9d****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://***/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***qAKU%3D&security-token=***q6Ft5B2y***",
                "fileMd5":"93230c3bde425a92***",
                "fileSign":"93230c3bde425a92****"
            }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

Table 2. Parameter descriptions
Parameter	Type	Description
id	Long	The message ID. The ID must be unique for the device.
message	String	The result information.
code	String	The status code.
version	String	The version of the device upgrade package.
size	Long	The size of the upgrade package file in bytes. This parameter is included only when the OTA upgrade package contains a single file.
url	String	The storage address of the upgrade package in Object Storage Service (OSS). This parameter is included only when the OTA upgrade package contains a single file and the download protocol is HTTPS.
dProtocol	String	The download protocol for the upgrade package. This parameter is included only when the download protocol is MQTT.
streamId	Long	The unique identifier for downloading the OTA upgrade package over MQTT. This parameter is included only when the download protocol is MQTT.
streamFileId	Integer	The unique identifier for a single upgrade package file. This parameter is included only when the download protocol is MQTT.
isDiff	Long	This parameter is included only when the package type is delta update. A value of 1 indicates that the package contains only the differences between the new version and the previous version. The device must perform a delta revert.
digestsign	String	The signature of the OTA upgrade package file after a secure upgrade. This parameter is included only if the secure upgrade feature is enabled for the OTA upgrade package. To enable the secure upgrade feature for an OTA upgrade package, see Secure upgrade.
sign	String	The signature of the OTA upgrade package file. This parameter is included only when the OTA upgrade package contains a single file.
signMethod	String	The signature method. Valid values: `SHA256` `MD5` For Android delta upgrade packages, only the MD5 signature method is supported.
md5	String	If the signature method is MD5, a value is assigned to both the sign and md5 parameters. This parameter is included only when the OTA upgrade package contains a single file.
module	String	The name of the module to which the upgrade package belongs. Note If the module name is default, IoT Platform does not send the module parameter.
extData	Object	A list of tags for the upgrade batch and custom information pushed to the device. The _package_udi field indicates custom information. The format for a single tag is `"key":"value"`.
files	Array	A list of information for multiple upgrade package files. This parameter is included when the OTA upgrade package contains multiple files. The information for each file is as follows: fileSize: The size of the upgrade package file. fileName: The name of the upgrade package file. fileUrl, fileMd5, and fileSign have the same meanings as url, md5, and sign.

Device reports for upgrade progress

Uplink data.

Topic: /ota/device/progress/${productKey}/${deviceName}.

During an OTA upgrade, a device can use this topic to report the upgrade progress as a percentage.

Note Set the progress reporting frequency on the device to a maximum of once every 3 seconds. If the device reports progress too frequently, you may not be able to view all progress reports on the Batch Details page for the OTA upgrade package in the IoT Platform console.

Request data format:

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "OTA upgrade failed. Could not request the upgrade package information.",
        "module": "MCU"
    }
}

Table 3. Parameter descriptions
Parameter	Type	Description
id	String	The message ID. A string-type number. The value must be unique for the device. The value can range from 0 to 4294967295.
step	String	The OTA upgrade progress. Valid values: An integer from 1 to 100: The upgrade progress percentage. `-1`: The upgrade failed. `-2`: The download failed. `-3`: The verification failed. `-4`: The flashing failed. Configure the progress values and their descriptions on the device based on the actual upgrade scenario. For information about how to configure them on the device, see OTA upgrades for Link SDK on devices.
desc	String	A description of the current step. The description can be up to 128 characters long. If an error occurs, this field can contain the error message.
module	String	The name of the module to which the upgrade package belongs. For more information about modules, see Add an upgrade package. Note The module parameter is optional when you report the OTA upgrade progress of the default module.

Device requests for OTA upgrade package information

Uplink data.

Request topic: /sys/${productKey}/${deviceName}/thing/ota/firmware/get.

Response topic: /sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply.

Request data format:

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

Table 4. Parameter descriptions
Parameter	Type	Description
id	String	The message ID. A string-type number. The value must be unique for the device. The value can range from 0 to 4294967295.
version	String	The protocol version. The value is fixed at 1.0.
params	Object	The request parameters.
module	String	The name of the module to which the upgrade package belongs. Note If this parameter is not specified, the device requests the upgrade package information for the default module.
method	String	The request method. The value is `thing.ota.firmware.get`.

After IoT Platform receives a request from the device, it sends a response.

The response contains the upgrade package information. The format of the returned data is as follows:

For an OTA upgrade package that contains a single file:

If the download protocol for the upgrade package is 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\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    }
}

If the download protocol for the upgrade package is 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"
        }
    }
}

OTA upgrade packages that contain multiple files support only the HTTP download protocol. The data format is as follows:

{
    "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\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    }
}

Table 5. Parameter descriptions
Parameter	Type	Description
id	String	The message ID. A string-type number. The value can range from 0 to 4294967295. The value must be unique for the device. This is the message ID from the device request. It is the value of the id parameter in the data of the request topic `/sys/${productKey}/${deviceName}/thing/ota/firmware/get`.
code	Integer	The status code. A value of 200 indicates success.
data	Object	The upgrade package information. For parameter descriptions, see the parameter table in IoT Platform pushes OTA upgrade package information.

If no upgrade package is available, the following data is returned:
```
{
    "id": "123",
    "code": 200,
    "data": {
    }
}
```

Device requests to download file shards

If the download protocol is MQTT, a device can use the following topics to download the OTA upgrade package file in shards after it obtains the package information.

Important The size of a single file that a device downloads over MQTT cannot exceed 16 MB.

Request topic: /sys/${productKey}/${deviceName}/thing/file/download
Response topic: /sys/${productKey}/${deviceName}/thing/file/download_reply

Request data format:

{
    "id": "123456",
    "version": "1.0",
    "params": {
        "fileToken":"1bb8***",
        "fileInfo":{
            "streamId":1234565,
            "fileId":1
        },
        "fileBlock":{
            "size":256,
            "offset":2
        }
    }
}

Table 6. Parameter descriptions
Parameter	Type	Description
id	String	The message ID. A string-type number. The value must be unique for the device. The value can range from 0 to 4294967295.
version	String	The protocol version. The value is fixed at 1.0.
params	Object	The request parameters.
fileToken	String	The unique token that identifies the file. This parameter is optional. It supports digits, letters, underscores (_), and periods (.). It can be up to 16 characters long. Usage notes: If this parameter is included in the request, IoT Platform includes it in the response. This helps you confirm the corresponding file in the response message when you download multiple files on the device. If the device does not need to request other files during the request and response cycle for a file download, you can omit this parameter.
fileInfo	Object	Information about the OTA upgrade package file.
streamId	Long	The unique identifier for downloading the OTA upgrade package over MQTT.
fileId	Integer	The unique identifier for a single upgrade package file.
fileBlock	Object	Information about the file shard.
size	Integer	The size of the requested file shard in bytes. The value can range from 256 to 131072. For the last file shard, the value can range from 1 to 131072.
offset	Integer	The starting address of the file shard in bytes. The value can range from 0 to 16777216.

Response data format:

The structure is shown in the following figure: 结构图

Structure Item	Description
JSON Bytes Length	The length of the byte array that corresponds to the JSON string in the response data. This item must be 2 bytes long, with the high-order byte first (big-endian). For example, if the length of the byte array for the JSON string encoded in UTF-8 is 87 in decimal (57 in hexadecimal), the high-order byte is 0x00 and the low-order byte is 0x57.
JSON String Bytes	The byte array that corresponds to the JSON string in the response data. The encoding format is UTF-8. For details, see "Response JSON data format" below.
File Block Bytes	The byte array of the current file shard. The bytes are arranged in ascending order of their offset from the file header.
CRC16/IBM	The checksum of the file shard. Only CRC16/IBM is supported. This item is 2 bytes long, with the low-order byte first (little-endian). For example, if the checksum of the file shard is 0x0809, the low-order byte is 0x09 and the high-order byte is 0x08.

The response data is in the following JSON format:

{
    "id": "123456",
    "code":200,
    "msg":"file size has exceeded the limit 16 MB",
    "data": {
        "fileToken":"1bb8***",
        "fileLength":1238848,
        "bSize":1491,
        "bOffset":2
    }
}

Table 7. Parameter descriptions
Parameter	Type	Description
id	String	The message ID. A string-type number. The value must be unique for the device. The value can range from 0 to 4294967295. This is the message ID from the device request. It is the value of the id parameter in the data of the request topic `/sys/${productKey}/${deviceName}/thing/file/download`.
code	Integer	The status code. A value of 200 indicates success.
msg	String	The error message that is returned if the request fails.
data	Object	The data returned to the device.
fileToken	String	The unique token that identifies the file. This parameter is returned if the fileToken value is included in the request parameters.
fileLength	Integer	The total size of the file in bytes.
bSize	Integer	The size of the current file shard in bytes.
bOffset	Integer	The starting address of the current file shard in bytes. This value is the same as the offset value in the request data.

References

For error code descriptions and solutions, see Error codes received by devices.