Create an update batch

Procedure

1. Log on to the IoT Platform console.

2. On the Overview page, find the instance that you want to manage and click the instance ID or instance name.

3. 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.

4. In the update package list, find the package that you want to deploy, click Batch Update in the Actions column, configure the update scope, and then click Next.

   Parameter	Description
   Update method	Select an update method. Options: Static update: For a selected update scope, only devices that currently meet the update conditions are updated. Dynamic update: For a selected upgrade scope, this feature updates devices that currently meet the upgrade conditions. The IoT Platform also continuously monitors devices within this scope and automatically pushes an update to any device that meets the upgrade conditions. This includes, but is not limited to, the following devices: Newly activated devices that meet the update criteria. Devices that initially report a non-matching OTA module version but later report a version that meets the criteria. Note Only one dynamic update batch can be active for each update package. If a dynamic update batch already exists for a package, you cannot create a new one. To create a new dynamic update batch, you must first cancel the existing one. A device can be matched for an update a maximum of 10 times within a version-based dynamic update batch. After 10 matches, IoT Platform will no longer trigger an update for the device, even if it subsequently meets the dynamic update conditions.
   Update scope	Select the scope of the update. Options: All Devices: Updates all devices under the product that meet the update criteria. Targeted update: Updates only the selected devices. If you choose this option, you can select devices in one of two ways: Select manually: Select the devices to update from the device list. For an Enterprise Edition instance in the China (Shanghai), China (Beijing), or China (Shenzhen) region, you can use the Advanced Search feature to find devices and download a CSV file of the search results. Upload file: Download a CSV template, fill it with device names, and upload the file. You can include up to 1,000,000 records in a single file. If the file contains invalid device names, an error message appears. Click Download invalid list, correct the invalid names in your file, and then re-upload it. Regional update: Updates devices located in a specific geographical area. If you choose this option, you must select the target province and city. Phased update: Performs a partial update. This option is available only for a static update. You must specify at least one device for a phased update. If you choose this option, you must set a percentage of the selected devices to update. IoT Platform calculates the number of devices to update based on this percentage and rounds the result down. Group update: If the Update method is static update, the group list displays all static groups in the current instance, including all parent groups and their subgroups. If the Update method is dynamic update, this parameter is displayed only for instances in the China (Shanghai) region. For more information, see View and configure instance endpoints. The group list displays all dynamic groups in the current instance. For details, see Workflow for group-based dynamic updates. To learn how to create static and dynamic device groups, see Manage device groups.
   Source versions	The device firmware version to upgrade from. This parameter is optional for a full static update but required for a full dynamic update. This parameter is not available if you set the Update scope to Targeted update. The drop-down list displays all device versions under the current product except for the target version. You can select one or more versions to upgrade from. If you do not select a version, no restrictions are placed on the current version of the device OTA module. For a differential update, this parameter defaults to the source version specified when you added the update package. Note After an update batch is created, you can modify the source version if the Update method is dynamic update and the batch status is Updating.

5. Configure the update policy and click Complete. IoT Platform will then push update notifications to the specified devices.

   Parameter	Description
   Update time	Specify when to run the OTA update. Upgrade Now: Starts an OTA update immediately. Scheduled upgrade: You can set a start time and an end time for the upgrade. The start time must be at least 5 minutes and at most 7 days from the current time. The end time must be at least 1 hour and at most 30 days after the start time. The end time is optional. If you do not specify an end time, the upgrade is not forcibly terminated. Note Scheduled updates are supported only for a static update.
   Proactive push by cloud	Specifies whether IoT Platform actively pushes the update task to devices. Yes (Default): After the update batch is created, IoT Platform actively pushes the OTA update task to online devices within the specified scope. Devices can also request OTA update information from IoT Platform in this mode. No: Devices must request OTA update information from IoT Platform.
   Push rate	The number of devices per minute that receive the update package download URL. You can select Constant rate or Variable rate. Important This parameter is not required if you set Proactive push by cloud to No. Currently, only Enterprise Edition instances support the Variable rate option. The following table describes the parameters. Constant rate: Set the constant push rate. The value must be an integer from 10 to 10,000. After you set the rate, it remains constant. For example, to fix a critical bug, you might want to push an update package to all devices as quickly as possible. In this case, a constant rate is suitable. The maximum rate is 10,000 devices per minute, ensuring the fastest possible delivery to all targeted devices. Variable rate: In some scenarios, you may want to start with a low push rate (for example, 1 device per minute) and increase it after certain conditions are met. You can use the variable rate option. For example, when introducing a new feature, you might want to roll it out slowly at first to monitor device performance. You can then gradually increase the push rate. This approach is similar to a phased update followed by a full rollout. If you select Variable rate, you must configure the following parameters: Base push rate: The push rate in devices per minute before the threshold specified in Condition to increase push rate is met. The value must be an integer from 1 to 10,000 and must be less than or equal to the maximum push rate. Incremental factor: The factor by which the push rate increases after the threshold specified in Condition to increase push rate is met. The value can range from 1.20 to 5.00, with up to two decimal places. Maximum push rate: The maximum push rate in devices per minute. The value must be an integer from 10 to 10,000. Once the push rate reaches this value, it will not increase further. Condition to increase push rate: The threshold for either Pushed devices or Succeeded devices. The value must be an integer from 1 to 100,000. When the number of pushed or succeeded devices reaches this threshold, the push rate increases based on the incremental factor. Example: Variable rate settings: Base push rate is 50, incremental factor is 2, Maximum push rate is 10,000, and the threshold for Pushed devices under Condition to increase push rate is 1,000. Update process: The OTA update task starts by pushing update notifications at a rate of 50 devices per minute. This rate is maintained until 1,000 devices have received the notification. After that, the push rate increases according to the incremental factor. The rate increase trend is as follows: The system pushes notifications at 50 devices/min until 1,000 devices are reached. Because the incremental factor is 2, the rate increases from 50 to 100 devices/min. The system pushes notifications at 100 devices/min until another 1,000 devices are reached (total pushed: 2,000). The rate then increases from 100 to 200 devices/min. The system pushes notifications at 200 devices/min until another 1,000 devices are reached (total pushed: 3,000). The rate then increases from 200 to 400 devices/min. The system pushes notifications at 400 devices/min until another 1,000 devices are reached (total pushed: 4,000). The rate then increases from 400 to 800 devices/min. This trend continues, with the rate increasing to 1,600, 3,200, and 6,400 devices/min. After a total of 8,000 devices have received notifications, the next rate based on the incremental factor would be 12,800. This exceeds the maximum push rate of 10,000, so the rate is capped at 10,000 devices/min and remains there for the rest of the update. After the update batch is created, if its status is Updating, you can modify the push rate settings. However, you cannot change the rate type between Constant rate and Variable rate. For more information, see Manage update batches.
   Retry interval on failure	The time to wait before retrying a failed update. Options: Do not retry Retry immediately Retry after 10 minutes Retry after 30 minutes Retry after 1 hour Retry after 24 hours Important The retry interval on failure must be less than the device update timeout. For example: The Device Upgrade Timeout is 60 minutes, and the Upgrade Failure Retry Interval can be set to a maximum of Retry after 30 minutes. The Device upgrade timeout is 1440 minutes, and the Upgrade failure retry interval can be set to a maximum of Retry after 1 hour. The system will not trigger a retry after the timeout period expires. If you need to set the retry interval on failure to Retry after 24 hours, we recommend that you do not set the device update timeout.
   Maximum retries	The maximum number of retries after an update fails. Options: 1 2 5
   Device update timeout (minutes)	The timeout period for a single device update. If the update is not completed within this period, the update times out. The value can range from 1 to 1,440 minutes. Note The timer starts when the device first reports its update progress. If a device goes online and offline multiple times during the update, causing IoT Platform to push the update package repeatedly, the timer still starts from the device's first progress report. After the update batch is created, if the Update method is dynamic update and the batch status is Updating, you can modify the timeout period. For more information, see Manage update batches.
   Allow simultaneous multi-module updates	Specifies whether a device can update multiple modules at the same time. Yes: The device can run multiple update tasks for different modules simultaneously. In this mode, a new update task for a specific module will override a previous pending task for the same module, but it will not override a task that is already in progress. No (Default): The device cannot update multiple modules at the same time. Limitations Regions: China (Shanghai), China (Beijing), China (Shenzhen), Singapore, and Japan (Tokyo). Supported instances: Enterprise Edition instances and new public instances. Device-side Link SDK: Link SDK for C 4.x. A single device can run a maximum of five update tasks for different modules simultaneously. For the same product: The Allow concurrent multi-module updates and Overwrite previous update tasks on the device options cannot both be set to Yes. For example, you initiate an update batch for one or more update packages of a product and set Allow concurrent multi-module updates to Yes. Subsequently, you initiate another update batch and set Overwrite previous update tasks on the device to Yes. Do not use this scenario. Within update batches for the same module under a product, if Allow simultaneous multi-module updates is set to Yes, you cannot mix version-based dynamic updates and group-based dynamic updates for the same source version. For the same dynamic group: The settings for Allow simultaneous multi-module updates and Override previous update tasks must be consistent across all dynamic update batches for that group. For example, if Support concurrent multi-module upgrades is set to Yes for a group's existing dynamic batches, then for new dynamic batches created from that group, Support concurrent multi-module upgrades must be set to Yes. In a dynamic update batch where Allow simultaneous multi-module updates is set to Yes, when a device reports a module version: If the device matches multiple dynamic update tasks (for example, a version-based and a group-based update), the most recently created group-based dynamic batch takes precedence. If there is no group-based dynamic update, the most recently created dynamic batch for that device takes precedence.
   Override previous update tasks	If a device is included in multiple update batches simultaneously (with a status of To Be Confirmed, To Be Pushed, or Pushed), specifies whether the new task overrides previous ones. Yes: The device executes only the new update task. Previous tasks are canceled. No (Default): If the device already has an update task, it executes only that existing task. Note Tasks that are already in progress will not be overridden. The device continues the in-progress task and does not start the new one.
   Apply to newly reported versions only	This parameter is available when the Update method is dynamic update. Options: Yes: Updates only devices that report a matching version after the batch is created. No (Default): Updates existing devices that meet the criteria and any new devices that subsequently meet the criteria.
   App confirmation required	Use this parameter to control device OTA updates through a mobile app that you develop. Yes: The device cannot retrieve OTA update tasks directly. Your app must confirm tasks in the To Be Confirmed state by calling the ConfirmOTATask API. After confirmation, the device can obtain update information based on the Proactive push by cloud setting. No (Default): The device obtains update information directly based on the Proactive push by cloud setting. Workflow for app-confirmed updates: You develop a mobile app. In this mode, IoT Platform does not actively push notifications to devices. Your app must poll for tasks. The app calls the ListOTAUnfinishedTaskByDevice API to query for unfinished update tasks for a device. The app calls the ConfirmOTATask API to confirm the update.
   Download protocol	Select a protocol (HTTPS or MQTT). After the device receives download information from IoT Platform, it uses the selected protocol to download the update package. HTTPS: Supports single-file and multi-file package downloads. The URL for the update package is valid for 24 hours. If it expires, the device must request a new one. The maximum size for a single file is 1,000 MB. The following file formats are supported: .bin, .dav, .tar, .gz, .zip, .gzip, .apk, .tar.gz, .tar.xz, and .pack. MQTT: Supports single-file and segmented single-file downloads. The MQTT protocol provides a package ID that does not expire. The package must contain only one file, and its size cannot exceed 16 MB. Downloading over MQTT is supported only in the China (Shanghai), China (Beijing), and China (Shenzhen) regions. You must use the Link SDK for C provided by IoT Platform to develop the MQTT download capability. For more information, see Sample code description.
   Batch tags	Click Add tag and enter a tag key and tag value. After the update batch is created, if its status is Updating, you can modify or add tags. For more information, see Manage update batches. Batch tags are sent to the device along with the update notification. Click the Help icon to view the tag configuration rules.

6. Optional: In the batch management list on the Update Package Details page, find the dynamic update batch and click Edit in the Actions column to modify the Version Number to Be Updated in the Update Scope Configuration section and the Device Update Timeout in the Update Policy Configuration section (you can also cancel the timeout setting).

   Important

   • After you modify dynamic update settings:

     • Source versions: If you add a version number, this triggers an update for existing devices with that version and for new devices that match the dynamic policy. If you remove a version number, existing updates are not affected.

     • Device update timeout (minutes): The change affects only new dynamic OTA updates. Existing updates are not affected.

   • For a group-based dynamic update, you cannot modify the Source versions.

Results

After you submit the update batch, IoT Platform pushes update notifications to devices based on your settings. You can monitor the update status, package information, and other details in the console. For more information, see View update status.

Workflow for group-based dynamic updates

Limitations

• Group-based dynamic updates are available only for Enterprise Edition instances and new public instances in the China (Shanghai) region. For more information about public instances, see Instance overview.

• Only one group-based dynamic update batch can be created per update package. You can use different update packages to initiate multiple dynamic update batches for the same source version, but the device matches only the most recent batch.

• You can use a maximum of five different update packages to initiate dynamic update batches for the same dynamic group. The update packages can belong to the same product or different products.

• If a device matches multiple update batches for a dynamic group, IoT Platform prioritizes the most recent dynamic update batch for that device.

  Note

  We recommend that you avoid configuring duplicate or similar rules for different dynamic groups. This prevents a device from joining multiple dynamic groups at the same time, which could cause it to fail to match the most recent dynamic batch.

Procedure

1. Create and use a dynamic group.

   • If the dynamic group uses OTA module data to search for devices, you must use both ota_module.name and ota_module.version in the search criteria.

   • If the dynamic group does not use OTA module data to search for devices, you do not need to specify ota_module.name or ota_module.version.

2. Initiate an OTA update batch.

   • In the IoT Platform console, navigate to the Monitoring & O&M > OTA Updates page for your instance. Find the update package and open the Update Package Details page. The Total targeted devices count may not immediately match the Total devices count on the dynamic Group Details page. The counts will eventually synchronize.

3. The behavior depends on the state of the devices in the group.

   • New devices are added to the dynamic group after the OTA update is initiated: A new device receives an update only if it meets the OTA update criteria. For example, in a differential update, if a device is added to the dynamic group but its firmware version does not match the source version of the differential package, the system does not trigger an update.

   • Devices are already in the dynamic group when the OTA update is initiated: If a device in the group fails to update, then leaves and rejoins the group, the system re-triggers the OTA update because the status of its last update task was Failed.

4. Optional: You can delete a dynamic group. This action does not affect existing OTA update tasks. However, new devices will no longer be triggered for OTA updates based on that group.

API reference

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