IoT Platform provides the over-the-air (OTA) update and management feature. To update devices, make sure that your devices support the OTA service. Then, you can upload an update package to the IoT Platform console and push OTA update notifications to the devices. This article describes how to add an update package, verify the update package, and push the update package to multiple devices by using the IoT Platform console.

Prerequisites

Before you use the OTA update feature, make sure that your devices support the OTA service.

Background information

Take note of the following limits of OTA updates:

  • Each Alibaba Cloud account can have a maximum of 500 update packages.
  • The maximum size of an update package file is 1,000 MB. The file format can only be .bin, .tar, .gz, .tar.gz, .zip, or .gzip.
  • Take note of the following limits of update batches:

    Update batches: IoT Platform shows created update tasks as different update batches. You can go to the Update Package Details page and view the update batch of the update package on the Batch Management tab.

    • You can use an update package to create one or more update batches for different firmware versions to be updated.
    • You can use an update package to create only one dynamic update batch for a firmware version to be updated.
    • You can use different update packages to create multiple dynamic update batches for a firmware version to be updated.
    • Each device can have only one ongoing update batch. A device that has an ongoing update batch is in the To Be Pushed, Pushed, or In Upgrade state.
  • Only devices that are connected to IoT Platform by using the Message Queuing Telemetry Transport (MQTT) protocol support the OTA update feature.
  • If devices are online, these devices can immediately receive update notifications. If devices are offline, IoT Platform pushes update notifications when devices go online.

Procedure

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Maintenance > OTA Update.
    Note To provide better services, IoT Platform improves the OTA update feature. This feature allows you to manage update package versions based on products. When you use the new OTA update feature in the console for the first time, you must associate the uploaded update packages with products. You can associate an update package with only one product. For more information about how to associate firmware files with products, see the instructions in the console.
  3. Optional. If AliOS Things chips are installed on your devices, you can enable the secure update feature.

    We recommend that you enable this feature to ensure integrity and security of update packages. If you use the secure update feature, verify the update package and update package signatures of devices. For more information, see OTA Tutorial for AliOS Things.

    1. Go to the OTA Update page, and click Secure Update.
    2. In the dialog box that appears, turn on the Secure Update switch for the product to be updated.
      When the secure update feature is in the Activated state, click Copy in the Public Key column to copy the public key. You can use the public key to verify the signature of the device.
  4. Optional. Add a custom OTA module.
    An OTA module indicates the module of devices to be updated in a product. These OTA modules include the firmware, software, and driver. The default module is the firmware of a device. You can also add another module as an OTA module.

    On the Modules tab, click Add Module, set the required parameters, and then click OK.

    Parameter Description
    Product The product to which the module belongs.
    Module Name The module name. The module name must be unique in the product. The module name cannot be modified after the module is created. The module name must be 1 to 64 characters in length, and can contain letters, digits, periods(.), hyphens (-), and underscores (_).
    Module Alias The module alias. The module alias must be 4 to 64 characters in length, and can contain letters, digits, periods(.), hyphens (-), and underscores (_).
    Module Description The module description. The module description must be 1 to 100 characters in length.
  5. On the OTA Update page, click the Update Packages tab, and click Add Update Package.
  6. Set the required parameters, upload an update package file, and then click OK.
    Parameter Description
    Types of Update Packages
    • Full: If you select Full, you must upload a complete update package. The system pushes the complete update package to devices for update.
    • Differential: If you select Differential, you must upload a file that contains only the differences between the original update package version and the destination update package version. IoT Platform pushes the differences to devices for update. Then, the differences are merged into the original update packages. Differential updates optimize the usage of device resources and minimize the traffic that is consumed during update package pushing.
    Update Package Name The update package name. The update package name must be unique in the Alibaba Cloud account. The update package name cannot be modified after the update package is created. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), underscores (_), and parentheses (). The name must start with a letter or digit.
    Product The product to which the update package belongs.
    Update Package Module The OTA module to which the update package applies.

    You can click Add Module. In the dialog box that appears, set the required parameters and click OK to add a module.

    Update Package Version The update package version. The name must be 1 to 64 characters in length, and can contain letters, digits, periods (.), hyphens (-), and underscores (_).

    You must specify this parameter if you set the Types of Update Packages parameter to Full.

    Version number to be upgraded The version number for the OTA module of the device to be updated. The drop-down list shows the OTA module versions of all devices in the current product. You can enter a version number in the field, or select a version from the drop-down list.

    You must specify this parameter if you set the Types of Update Packages parameter to Differential.

    Post-upgrade version number The version number of the update package.

    You must specify this parameter if you set the Types of Update Packages parameter to Differential.

    Signature Algorithm The signature algorithm. Valid values: MD5 and SHA256.

    If you use the Link SDK for Android and set the Types of Update Packages parameter to Differential, select the MD5 algorithm.

    Select Update Package Select an update package file to upload. The maximum size of an update package file is 1,000 MB. The file format can only be .bin, .tar, .gz, .tar.gz, .zip, or .gzip.
    Note The file extension of an update package file to be uploaded must be lowercase, for example, test.zip.
    Verify Update Package Specifies whether you need to verify the update package on several devices before you perform a batch update.
    • Yes: You must verify the update package. You can perform a batch update after the update package is verified. For more information about how to perform a batch update, see the next step.
    • No: No verification is required. You can perform a batch update without the need to verify the update package.
    Update Package Description The update package description. The description must be 1 to 100 characters in length.
  7. If you select Yes in the Verify Update Package field, find the required update package, and click Verify next to the update package. In the Verify Update Package dialog box, set the required parameters, and click OK to verify the update package on one or more devices.
    Note After the preceding devices are updated and the status of the update package is displayed as Verified, you can perform a batch update.
    Parameter Description
    Version number to be upgraded
    • If you perform a full update, this parameter is optional.

      The drop-down list shows the versions of all devices in the current product, except for the version for the destination device. You can select one or more versions. After you select the required versions, the related devices are added to the Device to be verified list as candidate devices.

      If you do not set this parameter, no limit is set on the version number for the OTA module of the devices to be verified.

    • If you perform a differential update, the value of this parameter is the version number that you specify when you add the update package.
    Device to be verified Select one or more devices to be verified.
    Device upgrade time-out (minutes) The timeout period of the update. If the specified device has not been updated within this period, the update times out. Valid values: 1 to 1440. Unit: minutes.
    Note The period starts from the first time the specified device submits the update progress.
  8. On the Update Packages tab, find the required update package, and click Batch Update next to the update package. In the dialog box that appears, configure the required update scope and update policy, and click OK to push update notifications to devices in batches.
    Configuration Parameter Description
    Update scope Version number to be upgraded
    • If you perform a full static update, this parameter is optional. If you perform a full dynamic update, this parameter is required. If you set the Apply Update to parameter to Selected Devices, do not set this parameter.

      The drop-down list shows the versions of all devices in the current product, except for the version for the destination device. You can select one or more versions.

      If you do not set this parameter, no limit is set on the version number for the OTA module of the devices to be verified.

    • If you perform a differential update, the value of this parameter is the version number that you specify when you add the update package.
    Update Method
    • Static Update: updates only the current devices that meet the conditions.
    • Dynamic Update: constantly updates the devices that meet the conditions. Dynamic updates can be applied to the following scenarios:
      • The devices that are subsequently activated meet the conditions.
      • The current OTA module versions that devices submit do not meet the conditions. However, the devices subsequently submit the OTA module versions that meet the conditions.
      Note You can use an update package to create only one dynamic update batch. If you have created a dynamic update batch by using an update package, you must cancel this dynamic update batch before you create another one.
    Apply Update to
    • All Devices: updates all eligible devices in the specified product.
    • Selected Devices: updates only the specified devices. If you set Selected Devices, use one of the following methods to select the required devices:
      • Select: Select the required devices from the Device Range drop-down list.
      • Upload: Download a template file in the .csv format. Perform the steps that are provided in the template to enter the names of the required devices. Then, upload the template file. Each template file can contain a maximum of 10,000 records.

        If a template file includes one or more invalid device names, an error occurs. You can click Download Invalid Device Name List to download a TXT file. The file includes invalid device names.

    • Phased Update: updates the specified devices. This option appears if you select Static Update from the Update Policy drop-down list.

      After you select Phased Update, specify a range for devices in the Range (%) field that appears. IoT Platform calculates the number of devices to be updated based on the specified range. The calculation result is rounded down. You must specify at least one device for phased update.

    Update scope Update Time The time when the OTA update is performed.
    • Update: immediately performs the OTA update.
    • Scheduled Update: performs the OTA update during a specified time range. You can specify a start time and end time. The start time must be 5 minutes to 7 days later than the current time. The end time must be 1 hour to 30 days later than the start time. The end time is optional. If you do not specify an end time, the update is not forcibly stopped.
      Note Scheduled updates are available only if you set the Update Policy parameter to Static Update.
    Update Package Push Rate The number of devices to which you want to push the download URL of the update package per minute. Valid values: 10 to 1000.
    Retry Interval The interval after which a retry is performed if the update fails. Valid values:
    • Do Not Retry
    • Retry Immediately
    • Retry in 10 Minutes
    • Retry in 30 Minutes
    • Retry in 1 Hour
    • Retry in 24 Hours
    Maximum Retries The maximum number of retries after the update fails. Valid values:
    • 1
    • 2
    • 5
    Timeout (Minutes) The timeout period of the update. If the specified device has not been updated within this period, the update times out. Valid values: 1 to 1440. Unit: minutes.
    Note The period starts from the first time the specified device submits the update progress.
    Override Previous Device Update Tasks Specifies whether to overwrite the previous update task. Each device can be in only one ongoing update task at a time. The To Be Pushed, Pushed, or In Upgrade state is displayed if a device is in an ongoing update task.
    • If you select Yes, only the new update task is performed. The previous task is canceled.
    • If you select No and an update task exists for the device, only the update task is performed.
    Note The update task that is in progress is not overwritten.
    Take Effect for only Devices that Newly Report Versions This parameter is available only if you set the Update Policy parameter to Dynamic Update.

    This parameter specifies whether to update only the devices that submit firmware versions later. Make sure that the submitted firmware versions are used as the firmware versions to be updated

    • If you select Yes, only the devices that subsequently submit firmware versions are updated.
    • If you select No, the current devices that meet the conditions are updated. In addition, IoT Platform constantly checks the devices. If the devices that subsequently submit firmware versions meet the conditions, these devices are updated.
    Tag Click Add Tag. In the dialog box that appears, enter the key and value of the tag, and click OK. After an update batch is created, you cannot modify the tag that is added to the update batch.

    The tag of an update batch is sent to devices when IoT Platform pushes update notifications to these devices.

Result

After you submit a batch update request, IoT Platform pushes an update notification to your devices based on your settings.

Find the required firmware and click View in the Actions column. On the Batch Management tab, you can perform the following operations:

  • View the status of an update batch.

    Click View next to the required update batch. On the Batch Details page, you can view devices in different update statuses on the Device List tab.

    State Description
    To Be Pushed The OTA update notification has not been pushed to the device.

    This state may appear due to the following three causes: 1. The device is offline. 2. The notification is scheduled to be pushed. 3. The pushing rate exceeds the limit. The following states that correspond to these three causes are displayed:

    • To Be Pushed (Device Offline)
    • To Be Pushed (Timing: 2020/XX/XX XX:XX:XX)
    • To Be Pushed
    Pushed The device has received the OTA update notification but has not submitted the progress.
    In Upgrade The device has received the OTA update notification and submitted the update progress.
    Updated The device has submitted a valid version number after the update.
    Note After a device is updated, make sure that the device submits a valid version number at the earliest opportunity. Otherwise, the update may fail due to a timeout issue.
    Updated Failed OTA updates may fail due to the following causes:
    • You initiate a new batch update for a device. However, you do not overwrite the previous update task that is not completed on the device.

      You can use one of the following methods to fix the issue:

      • After the previous update task is completed, you can initiate a new update.
      • Before you initiate a new update for a device, overwrite the previous task that is still running on the device.
        Note If the device is in the In Upgrade state, an update task that is running on the device cannot be overwritten.
    • During the update process, an update package may fail to be downloaded, extracted, or verified. The device submits one of the following values when using a specified topic to submit the update progress to IoT Platform: -1, -2, -3, and -4.
    • During a device update, the update period starts from the first time the device submits the update progress. The device fails to submit the destination version before the update reaches the end of the specified timeout period.
    • The device in the In Upgrade state submits a version that is not the source version or destination version.

    If you specify the number of a version to be updated and automatic update retries when you initiate a batch update, the retries are performed after the update fails. An update may fail due to one of the following causes:

    • The device in the In Upgrade state submits a version that is not the source version or destination version.
    • The device submits one of the following values when using a specified topic to submit the update progress to IoT Platform: -1, -2, -3, and -4.

    During automatic retries, the update status of a device in IoT Platform remains unchanged. For example, if a retry occurs on a device that is in the Pushed state, the device status is still displayed as Pushed in the IoT Platform console. If a retry occurs on a device that is in the In Upgrade state, the device status is still displayed as In Upgrade in the IoT Platform console.

    Note

    IoT Platform does not perform update retries if an update fails due to one of the following causes:

    • The update times out.
    • The update is canceled.
    Canceled The update for the device is canceled.
  • Cancel all update tasks of an update batch.

    Click Cancel next to the required update batch.

    • For a static update batch, only scheduled update tasks are canceled by default. You can cancel all ongoing update tasks that are in the To Be Pushed, Pushed, and In Upgrade states.
    • For a dynamic update batch, the dynamic update policy is canceled by default. You can cancel all ongoing update tasks that are in the To Be Pushed, Pushed, and In Upgrade states.