OTA firmware updates

Add new firmware

1. Log on to the IoT Platform console.
2. On the home page of the console, click OTA Firmware Updates.

   Alternatively, in the Operation Center, click OTA Firmware Updates.

3. (Optional) If your device uses an AliOS Things chip, enable the secure update feature.

   Secure updates help ensure firmware integrity and confidentiality. To use the secure update feature, the device must verify the firmware and its signature. For more information, see the AliOS Things technical documentation.

   1. On the Firmware Updates page, click Secure Update.
   2. In the dialog box, enable secure updates for the product you want to update.

      When the secure update feature is On, click the corresponding Copy button to copy the public key. The device uses this key to verify the signature.

4. On the Firmware Updates page, click Add Firmware.
5. In the Add Firmware dialog box, enter the firmware information, and then click Confirm to upload the firmware file.

   Parameter	Description
   Firmware Type	Full: The file you upload is a complete firmware package. The full package is pushed to the device for the update. Delta: The update package you upload contains only the differences between the new version and the previous version. Only the differences are pushed to the device. The device then reverts the delta to create a full update package. Delta updates reduce resource usage on the device and consume less traffic. If the device uses an AliOS-Things chip, Alibaba Cloud provides a method to generate delta packages and a delta revert algorithm. For more information, see OTA Delta Tool User Guide. You can also generate your own delta packages and develop your own delta revert algorithm.
   Firmware Name	The name of the firmware. The name can contain Chinese characters, English letters, Japanese characters, digits, underscores (_), hyphens (-), and parentheses (). It must start with a Chinese character, an English letter, or a digit. The name can be up to 40 characters long.
   Product	The product that the firmware belongs to. Note Exit the pop-up window to select a product.
   Firmware Version	The version number of the firmware. It can contain only English letters, digits, periods (.), hyphens (-), and underscores (_). The length must be 1 to 64 characters. This parameter is required when Firmware Type is set to Full.
   Source Version	The firmware version to be updated. The drop-down list displays all firmware versions of the devices under the current product. Select one or more source versions. This parameter is required when Firmware Type is set to Delta.
   Target Version	The firmware version after the update. This parameter is required when Firmware Type is set to Delta.
   Firmware Module	The firmware module is used to distinguish updates for different modules of devices under the same product. Select module: Select from existing firmware modules. Add module: Create a custom module. The name can contain only English letters, digits, periods (.), hyphens (-), and underscores (_). The length must be 1 to 64 characters. The default value is default.
   Signature Algorithm	If the product's network connection type is Bluetooth, only the MD5 algorithm is supported. If the device uses the Android SDK provided by Alibaba Cloud and Firmware Type is set to Delta, you must select the MD5 algorithm. Other cases: The MD5 and SHA256 algorithms are supported.
   Upload Firmware	The firmware file to upload. The file size cannot exceed 1,000 MB. Only files of the following types are supported: BIN, TAR, GZ, TAR.GZ, ZIP, GZIP, and APK.
   Firmware Description	A description of the firmware's features. The description can be up to 100 characters long. A Chinese character is counted as one character.

Verify firmware

Before you start a batch update, you must verify the firmware to confirm that all its features work correctly. This step helps prevent widespread device malfunctions caused by firmware bugs. Firmware verification is essentially a firmware update for a small number of specified devices. After firmware is successfully verified, it cannot be verified again.

1. Select the firmware to verify. In the Actions column, click Verify Firmware.
   Note After you upload the firmware to the IoT Platform, you must use a small number of devices to verify it. You can start a batch update only after you confirm that the test devices have been successfully updated.
2. Configure the parameters for firmware verification.

   Parameter	Description
   Target Version	The drop-down list displays all firmware versions of the devices under the current product. Select one or more source versions. After you select the source versions, the devices that use these firmware versions are displayed in the Devices to be Verified list.
   Devices to be Verified	The devices to use for this test.
   Device Update Timeout	The timeout period for a single device update. If the update is not complete within this period, it times out. The time is calculated from when the device first reports its update progress. The value can range from 1 minute to 1,440 minutes.

   Configure App Confirmation for Update

   • Yes: When the firmware is updated, a message is pushed to the app to notify the user of the update.
   • No: The app user is not notified when the firmware is updated. This is a silent update.
3. Click OK.
   • If the firmware verification fails:

     The status changes to Verification Failed. You can then verify the firmware again.

   • If the firmware verification succeeds:

     The status changes to Verified. You cannot verify the firmware again, but you can proceed with a batch update.

Batch updates

After the firmware is verified and all its features are confirmed to be working, you can deploy it to many devices. A batch update is essentially a targeted push of an update notification to many devices.

Before you perform a batch update, note the following:

• Test devices cannot be included in a batch update.
• Do not use unverified firmware for batch updates.
• The update process is gradual, starting from when the device receives the notification until the update is complete. You must wait for the update to finish.
• Some devices in a batch update may fail to update. This can occur if a previous update for those devices has not finished (the device is pending an update or is updating).
• If an error, such as a download, verification, or decompression failure, occurs during the update process and the device reports it to the OTA system, the system may mark the update task as complete. However, the actual update result for the device is 'failed'.
• On the firmware details page, you can view the update status of devices in the batch. The list of failed updates provides a brief reason for each failure.

1. Select the firmware for the batch update. In the Actions column, click Batch Update.
2. Configure the parameters for the batch update.
   Configure App Confirmation for Update as needed.

   • Yes: When the firmware is updated, a message is pushed to the app to notify the user of the update.
   • No (Default): The app user is not notified when the firmware is updated. This is a silent update.

   Parameter	Description
   Target Version	Select the firmware version that you want to update. The drop-down list displays all current firmware versions for devices of this product. This parameter is required for a full update.
   Update Policy	Static update: Updates only the devices that meet the update conditions at the time the task is created. Dynamic update: Updates devices that currently meet the update conditions. The system also continuously monitors for and updates other devices that meet the conditions later. This includes, but is not limited to, the following scenarios: Devices that are newly activated and meet the update conditions. Devices that previously reported a non-matching firmware version but later report a version that meets the update conditions. Note A firmware version can have only one active dynamic update batch at a time. If a dynamic update batch already exists for the firmware, you cannot create another one. You must cancel the existing dynamic update batch first.
   Update Scope	All devices: Updates all devices associated with the product. Targeted update: Updates only specific devices that you select. After you select this option, a device selection box appears. Click the box to open a dialog box and select the devices to update. Note For targeted updates, you can select multiple source versions. The source versions that you previously entered are selected by default. Area-based update: Updates devices located in a specified geographical area. After you select this option, selection boxes for province and city are displayed. Grayscale update: Updates a specified percentage of devices. This option is available only when the Update Policy is set to Static update. After you select this option, an input box appears where you can set the percentage of devices to update. The IoT Platform calculates the number of devices based on this percentage and rounds the result down. A grayscale update must include at least one device.
   Update Time	Specifies when to perform the firmware update. Update now: Starts the firmware update immediately. Scheduled update: Sets a start and end time for the update. The start time must be at least 10 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 set an end time, the update is not forcibly stopped. Note Scheduled updates are supported only when the Update Policy is set to Static update.
   Firmware Push Rate	The number of devices per minute to which the firmware download URL is pushed. The value can range from 10 to 1,000.
   Update Failure Retry Interval	The interval at which to retry a failed update. The options are: Do not retry Retry immediately Retry after 10 minutes Retry after 30 minutes Retry after 1 hour Retry after 24 hours
   Maximum Update Retries	The maximum number of times to retry a failed update. The options are: Once Twice Five times
   Device Update Timeout	The timeout period for a single device update. An update is considered to have timed out if it is not completed within this period. The time is calculated from when the device first reports its update progress. The value can range from 5 to 1,440 minutes.
   Overwrite previous update tasks for the device	Specifies whether to overwrite a previous update task if a device is included in multiple update batches at the same time. This applies to devices with a status of Pending Confirmation, Pending Push, or Pushed. Yes: The device executes only the new update task. Previous update tasks are canceled. No (Default): If the device already has an update task, it executes only the existing task. Note Tasks that are in the Updating state are not overwritten. The device continues to execute the ongoing task and does not start the new task.
   Apply only to devices that report a new version	This parameter is available when the Update Policy is set to Dynamic update. Specifies whether the update applies only to devices that subsequently report a new version number. The source version for the update is the newly reported version number. Yes: Updates only the devices that subsequently report a new version number. No (Default): Updates devices that currently meet the update conditions. The system also continuously checks for and updates other devices that subsequently report a version number that meets the conditions.

3. After you submit the batch update, click View for the firmware. On the Batch Management tab, click the Device List tab to view the update status.

   Status	Description
   Pending Confirmation	The OTA update has not been confirmed in the mobile app. The update task enters this state only if App Confirmation for Update was set to Yes when the batch task was created.
   Pending Push	The firmware update notification has not been pushed to the device. There are three reasons for the Pending Push status: the device is offline, the push is scheduled, or the rate is limited. The status is displayed as one of the following: Pending Push (Device Offline) Pending Push (Scheduled: YYYY/MM/DD HH:MM:SS) Pending Push
   Pushed	The firmware update notification has been pushed to the device, but the device has not yet reported its progress.
   Updating	The device has received the update notification and has reported its update progress.
   Update Succeeded	The device reported 100% update progress and reported the correct version number after the update. Note After a device is successfully updated, it should report the correct new version number as soon as possible. Otherwise, the update may time out and be marked as failed.
   Update Failed	An update can fail for the following reasons. A new batch update is initiated for a device before its previous update task is finished, and the option to overwrite the previous task is not selected. In this case, the new update task fails. You can: Wait for the device to complete the previous update before you initiate a new one. When you initiate the update, select the option to overwrite the device's previous update task. Note Update tasks with the Updating status are not overwritten. The device reports a value of -1, -2, -3, or -4 to the IoT Platform through the update progress topic. This indicates that the update failed. The values mean the following: -1: Update failed. -2: Download failed. -3: Verification failed. -4: Flashing failed. During the update, the time is calculated from when the device first reports its progress. If the device does not report the target version to complete the update before the timeout period ends, the update is considered failed. The device is in the Updating state and reports a version other than the source or target version. In this case, the update is considered failed. If you specified a source version and selected the retry option when you initiated the batch update, an automatic retry occurs in the following situations. The update failed because the device, while in the Updating state, reported a version other than the source or target version. The update failed because the device reported -1, -2, -3, or -4 through the update progress topic. During an automatic retry, the device's upgrade status in the cloud remains unchanged. For example, when a retry is performed while the status is Pushed, the status remains Pushed, and when a retry is performed while the status is Upgrading, the status remains Upgrading. Note The cloud does not trigger an automatic retry in the following cases: The update failed due to a timeout (failure reason: timeout). You manually canceled the update.
   Canceled	The update for this device has been canceled.