This article describes how to push an update package to multiple devices at a time in the IoT Platform console for an over-the-air (OTA) update.


The following operations are performed:
  1. Add an update package.
  2. Verify an update package (Optional).


  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 and adds statistics on update package versions. 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 update packages with products, see the instructions in the console.
  3. On the Update Packages tab, find the update package that you want to use and click Batch Update in the Actions column. Set the parameters as required and click Next.
    Parameter Description
    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 Upgrade range parameter to Selected Devices, do not set this parameter.

      The drop-down list displays the OTA module versions of all devices in the current product, except for the version to be updated to. 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 updated.

    • 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 existing devices that meet the required conditions.
    • Dynamic Update: constantly updates the devices that meet the required conditions. Dynamic updates can be applied to the following scenarios:
      • The devices that are subsequently activated meet the required conditions.
      • The current OTA module versions that devices submit do not meet the required conditions. However, the devices subsequently submit the OTA module versions that meet the required conditions.
      • 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.
      • A device can be updated at most 10 times in a dynamic update batch. If the device has been updated 10 times, no update can be initiated on the device even if the required conditions are subsequently met for a dynamic update.
    Upgrade range
    • All Devices: updates all eligible devices in the specified product.
    • Selected Devices: updates only the specified devices. If you select 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.
      • Choose File: 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 contains one or more invalid device names, an error occurs. You can click Download Invalid Device Name List to download a TXT file. The file contains invalid device names. Then, you must modify and re-upload the template file.

    • Phased Update: updates a percentage of the eligible devices. This option is displayed only if you set the Update Method parameter to Static Update.

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

  4. Configure the update policy and click Complete. Then, IoT Platform pushes update notifications to devices.
    Parameter Description
    Upgrade 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 an 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 supported only if you set the Update Method 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.
    Upgrade failed retry interval The interval between an update failure and a retry after the failure. Valid values:
    • Do Not Retry
    • Retry Immediately
    • Retry in 10 Minutes
    • Retry in 30 Minutes
    • Retry in 1 Hour
    • Retry in 24 Hours
    Note The retry interval that is specified by the Upgrade failed retry interval parameter must be shorter than the timeout period that is specified by the Device upgrade time-out (minutes) parameter. Examples:
    • If you set the timeout period to 60 minutes, the maximum retry interval that you can specify is 30 minutes.
    • If you set the timeout period to 1,440 minutes, the maximum retry interval that you can specify is 1 hour.

    If you need to set the Upgrade failed retry interval parameter to Retry in 24 Hours, we recommend that you do not set the Device upgrade time-out (minutes) parameter. Otherwise, the retry fails because the update times out.

    Max. Retry Times The maximum number of retries that can be performed after the update fails. Valid values:
    • 1
    • 2
    • 5
    Device upgrade time-out (minutes) The timeout period of the update. If a specified device has not been updated within this period, the update times out. Valid values: 1 to 1440. Unit: minutes.
    Note The update period starts from the first time the specified device submits the update progress.

    During the update, the update package may be repeatedly pushed to the specified device because the device goes online and offline multiple times. However, the start time of the update period does not change.

    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 update task is canceled.
    • If you select No and an update task exists for the device, only this previous 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 displayed only if you set the Update Method parameter to Dynamic Update.

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

    • If you select Yes, only the devices that subsequently submit OTA module versions are updated.
    • If you select No, the existing devices that meet the required conditions are updated. In addition, IoT Platform constantly checks the devices. If the devices that subsequently submit OTA module versions meet the required conditions, these devices are also updated.
    Batch label Click Add Tag. In the fields that appear, enter the tag key and tag value. You can add one or more tags. After an update batch is created, you cannot modify the tags that are added to the update batch.

    The tags of an update batch are sent to devices when IoT Platform pushes update notifications to these devices.

    You can click the Help icon to view the rules on how to configure tags.


View update status.

Related API operations

Operation Description
CreateOTAStaticUpgradeJob Creates a static update batch.
CreateOTADynamicUpgradeJob Creates a dynamic update batch.
CancelOTAStrategyByJob Cancels an update policy that is associated with a dynamic update batch.
CancelOTATaskByDevice Cancels the pending device update tasks of an update package.
CancelOTATaskByJob Cancels the device update tasks of an update batch.

For more information about API operations related to the OTA update feature, see API operations for OTA updates.