OTA update overview

Limits

Devices that use OTA must connect to IoT Platform over MQTT. Devices can download update packages over MQTT or HTTPS.

• Each Alibaba Cloud account supports up to 500 update packages. All RAM users under the account share this quota.

• The following limits apply to the number, size, format, and region of update packages.

  • HTTPS download: An update can include one or more files. A single file can be up to 1,000 MB in size. Only files in the following formats are supported: .bin, .dav, .tar, .gz, .zip, .gzip, .apk, .tar.gz, .tar.xz, and .pack.

  • MQTT download: Only single files up to 16 MB are supported, and only in the China (Shanghai), China (Beijing), and China (Shenzhen) regions. Use the C Link SDK to develop MQTT file downloads. Sample code.

How it works

Prerequisites

• Devices that use IoT SIM cards or C Link SDK V2.x or earlier must obtain OTA update domain names.

  Since September 1, 2023, the OTA update package download domain names have changed. If your devices (such as cellular IoT devices) use an endpoint whitelist, this change may block new package downloads. Submit a ticket to get the latest OTA domain list. Notice on the Adjustment of Service Domain Names for the IoT Platform OTA Update Feature.

• Connect your device to IoT Platform. Link SDK users: Obtain C Link SDK and Device connection guide. AliOS Things chip users: AliOS Things documentation.

OTA update procedure

Step 1: Report the version number

1. Configure the OTA feature.

   1. Connect the device to IoT Platform. In the IoT Platform console, select the target instance, then choose Device Management > Devices. Verify that the device status is Online.

   2. Initialize the OTA feature.

   3. Configure the OTA feature.

2. Report the current version number. The device must report its version before the first update. Report the version once at startup, not periodically. Only one module version can be reported per call. Topic and message format: Message formats at the end of this topic.

Step 2: Push update package information

1. Purchase and view OTA updates: View the number of available OTA updates for the current instance. If the number is insufficient, purchase a plan.

   • For new public instances, a free quota of 10 updates per calendar month is provided.

   • For Enterprise instances, a free quota of 1,000 updates per calendar month is provided.

2. Add an update package: Add an OTA module and an update package for the product.

   • Module: A user-defined updatable module for devices of the same product, such as firmware, software, or a driver. The default module represents the firmware of the entire device.

   • Full package: A complete update file. You can add one or more packages. Adding multiple sample packages requires the C Link SDK. The device does not need to report the OTA module version before a full update, but without a reported version, you cannot target a specific version in a batch update. Create a batch update job.

   • Delta package: Contains only the differences between the current and target versions. The device performs a local delta restore to reconstruct the full package before updating. Delta updates reduce consumed OTA update quota and download traffic. The device must report the OTA module version before a delta update.

     • For AliOS Things chips, Alibaba Cloud provides delta package generation and a delta restore algorithm. OTA Diff Tools User Guide.

     • For other devices, you must generate the delta package and develop the delta restore algorithm yourself.

3. Optional: Verify the update package: If you set Verify update package to Yes when adding a package, you must test on selected devices before batch deployment. The package becomes available only after test devices update successfully.

   You can require application confirmation before an OTA update proceeds:

   1. Develop the application yourself. The platform does not push update messages to the device — the application must query for them.

   2. The application calls ListOTAUnfinishedTaskByDevice to query for unfinished device update jobs.

   3. The application calls ConfirmOTATask to confirm the update job. The platform pushes the update message to the device only after confirmation.

4. Create a batch update job: IoT Platform sends update information (package URL, version, size) to devices in batches. The device status changes to To Be Updated or To Be Confirmed, then to Updating when the device reports progress.

Step 3: Download the update package

1. Obtain update package information. Offline devices cannot receive update messages. When a device comes online, IoT Platform checks for pending updates and pushes the message if needed.

   • IoT Platform pushes update package information. The device subscribes to: /ota/device/upgrade/${YourProductKey}/${YourDeviceName}. The device receives update information on this topic in two scenarios:

     • Device is online when the job is created: IoT Platform pushes update information immediately.

     • Device is offline when the job is created: IoT Platform pushes update information once the device comes online.

   • The device actively pulls update package information. The device publishes a request to a topic, and IoT Platform returns the update package information on the response topic. Topics and message formats: Message formats at the end of this topic.

   • HTTPS and MQTT download message formats: Message formats at the end of this topic.

2. The device downloads the update package using the HTTPS or MQTT protocol.

   • Download a single file over HTTPS.

   • Download multiple files over HTTPS.

   • Download a single file over MQTT.

3. Report the update progress. Topic and message format: Message formats at the end of this topic.

   Important

   If the device reports progress more frequently than every 3 seconds, some progress entries may not appear on the Batch Details tab in the console.

4. Report the new version number. Restart the device immediately after the update. Report the new version within 2 seconds of coming online.

   Important

   IoT Platform considers the update successful only when the reported version matches the target version. Even if reported progress reaches 100%, the update fails if the new version number is not reported before the Device update timeout period expires.

   • Topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}

   • Message format

     {
       "id": 1,
       "params": {
         "version": "2.0.0"
       }
     }

Step 4: View the update result

1. View the update status: View the update status of the target device, update package information, and more.

2. View update package versions and success rates: View statistics on the distribution of versions and success rates after the update. Analyze the causes of OTA update failures to improve the success rate.

References

• Troubleshoot failed updates: How do I troubleshoot a failed device OTA update?.

• Query IoT Platform logs to view communication records between IoT Platform, devices, and applications.

• Device-side error codes: Error codes for devices.

• Forward device update information to your server: Configure a server-side subscription using AMQP. OTA topic data formats after forwarding: Data formats.

Message formats

Report the version number

• Topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}

• Message format

  {
    "id": 1,
    "params": {
      "version": "1.0.0",
      "module":"mcu"      // If this parameter is not specified, the default version number is used.
    }
  }

  Parameter	Type	Description
  id	String	The message ID. Can be a string or long integer. Value range: 0 to 4294967295. Must be unique per device.
  version	String	The version of the OTA module.
  module	String	The OTA module name. Leave empty when reporting the default module version. The default module represents the overall device firmware.

Actively pull an update package

1. The device publishes a message to the topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get.

   • Message format

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

   • Parameter description

     Parameter	Type	Description
     id	String	The message ID. The value must be a string that contains a number from 0 to 4294967295 and must be unique for the current device.
     version	String	The protocol version. The value is fixed to 1.0.
     params	Object	The request parameters.
     module	String	The name of the module to which the update package belongs. If you do not specify this parameter, the information of the update package for the default module is requested.
     method	String	The request method. The value is thing.ota.firmware.get.

2. After IoT Platform receives the request, it returns the update package information to the device on the response topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply.

Download over HTTPS

Download a single-file package

{
    "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 underlying camera driver to resolve the issue of blurry video images.\"}"
        }
    }
}

Download a multi-file package

{
    "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\":\"Update the underlying camera driver to resolve the issue of blurry video images.\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

MQTT protocol download

When you download an update package over MQTT, only single-file packages are supported. After the device obtains the OTA update package information, the device can choose to perform a full download or a sharded download.

1. Full download

   • Message format

     {
         "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"
             }
         }
     }

   • Parameter description

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

2. Optional: Sharded download. After obtaining the preceding update package information, the device downloads the OTA update package file in shards using the following topics.

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

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

   • Request message format

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

   • Request message parameter description

     Parameter	Type	Description
     id	String	The message ID. The value must be a string that contains a number from 0 to 4294967295 and must be unique for the current device.
     version	String	The protocol version. The value is fixed to 1.0.
     params	Object	The request parameters.
     fileToken	String	The unique token of the file. This parameter is not required. It supports digits, letters, underscores (_), and periods (.). The value can be up to 16 characters in length. Usage notes: If you specify this parameter, IoT Platform returns it in the response to the device request. This helps you confirm the corresponding downloaded file in the response message in multi-file download scenarios. If the device does not need to initiate download requests for other files during the request and response cycle for the current file, you can leave this parameter empty.
     fileInfo	Object	The OTA update package file information.
     streamId	Long	The unique identifier for downloading the OTA update package over MQTT.
     fileId	Integer	The unique identifier of a single update package file.
     fileBlock	Object	The file shard information.
     size	Integer	The size of the requested file shard to download, in bytes. The value must be in the range of 256 to 131072. For the last file shard, the value must be in the range of 1 to 131072.
     offset	Integer	The start address of the byte that corresponds to the file shard. The value must be in the range of 0 to 16777216.

   • Response message structure

     

     Structure item	Description
     JSON Bytes Length	The length of the byte array that corresponds to the JSON string in the response data. It must occupy 2 bytes, with the high-order byte first (big-endian). For example, if the length of the byte array converted from the response JSON string using UTF-8 encoding is 87 in decimal (57 in hexadecimal), the high-order byte is 0x00 and the low-order byte is 0x57.
     JSON String Bytes	The UTF-8 byte array of the JSON string in the response data. Format details: "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. It must occupy 2 bytes, 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.

   • Response message format

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

   • Response message parameter description

     Parameter	Type	Description
     id	String	The message ID. The value must be a string that contains a number from 0 to 4294967295 and must be unique for the current device. The returned message ID is the message ID from the device request, which is the id in the data for 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 of the file. This parameter is returned if the fileToken value is passed 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 start address of the byte that corresponds to the current file shard. This value is the same as the offset value in the request data. The unit is byte.

Report the update progress

• The device publishes a message to the topic: /ota/device/progress/${YourProductKey}/${YourDeviceName}.

• Message format

  {
      "id": "123",
      "params": {
          "step": "-1",
          "desc": "OTA update failed. Failed to request the update package information.",
          "module": "MCU"
      }
  }

• Format

  Parameter	Type	Description
  id	String	The message ID. The value must be a string that contains a number from 0 to 4294967295 and must be unique for the current device.
  step	String	The OTA update progress. Configure progress values and descriptions based on your update scenario. Device-side configuration: Sample code. An integer from 1 to 100: The update progress percentage. -1: The update failed. -2: The download failed. -3: The verification failed. -4: The programming failed.
  desc	String	The description of the current step. The value can be up to 128 characters in length. If an exception occurs, this field can contain the error message.
  module	String	The module name for the OTA update package. Module details: Add an update package. When you report the OTA update progress for the default module, you can leave the module parameter empty.