Firmware Upgrade

Add firmware

1. On the project homepage, click Operations Hub.
2. Select .
3. (Optional) If your device uses an AliOS Things chip, you can enable secure upgrade.

   Secure upgrade ensures the integrity and confidentiality of the firmware. We recommend that you enable this feature. To use this feature, the device must verify both the firmware and its signature. For more information, see AliOS Things technical documentation.

   1. On the Firmware Upgrade page, click Secure Upgrade.
   2. OnIn the dialog box, turn on the toggle for your product.

      When secure upgrade is On, click the corresponding Copy button to copy the public key for signature verification on the device.

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

   Parameter	Description
   Firmware type	Products under your own brand Full: Upload a complete firmware file. The full package will be pushed to devices for upgrade. Delta: Upload only the differences between the new version and a previous version. Only the delta is sent to the device, which reconstructs the full package locally. Delta upgrades reduce resource usage on devices and minimize traffic consumption. If your device uses an AliOS Things chip, Alibaba Cloud provides tools and algorithms for generating and applying delta packages. See OTA Delta Tools User Guide. You can also generate delta packages and implement your own reconstruction algorithm. Products in the Tmall Genie ecosystem Only support full uploads. You must upload a complete firmware file.
   Firmware name	Set a firmware name. Supported characters include Chinese, English, Japanese, digits, underscores (_), hyphens (-), and parentheses (). The name must start with a Chinese character, English letter, or digit and cannot exceed 40 characters.
   Product	Select the product this firmware belongs to. Note You can close the dialog to select a product.
   Firmware version number	Set the firmware version number. Use only English letters, digits, periods (.), hyphens (-), and underscores (_). Length must be 1–64 characters. This parameter is required when Full is selected as the firmware type.
   Target Version	Select one or more source firmware versions to upgrade from. The dropdown lists all firmware versions currently used by devices under this product. This parameter is required when Firmware type is set to Delta. Note Products in the Tmall Genie ecosystem only support Firmware type as Full and do not require this parameter.
   Target version number	Set the firmware version after upgrade. This parameter is required when Delta is selected as the firmware type. Note Products in the Tmall Genie ecosystem only support Firmware type as Full and do not require this parameter.
   Firmware module	Firmware modules distinguish upgrades for different components of the same product. Select module: Choose from existing firmware modules. Add module: Define a new module name. Use only English letters, digits, periods (.), hyphens (-), and underscores (_). Length must be 1–64 characters. Default value is default. Note Modules are not supported for products in the Tmall Genie ecosystem.
   Signature algorithm	Products in the Tmall Genie ecosystem with Bluetooth network access: Only MD5 is supported. Products under your own brand using Alibaba Cloud’s Android SDK with Delta firmware type: Must use MD5. Other cases: Support MD5 and SHA256.
   Upload firmware	Upload the firmware file. File size must not exceed 1,000 MB. Supported formats: BIN, TAR, GZ, TAR.GZ, ZIP, GZIP, and APK.
   Firmware description	Describe the firmware’s features or other information. Maximum length is 100 characters. Each Chinese character counts as one character.

Verify firmware

Before you perform a batch upgrade, you must verify the firmware on a small number of devices to confirm that all features work as expected. This process prevents widespread device failures that can be caused by firmware bugs. After a firmware version is verified, you cannot verify it again.

1. Select the firmware that you want to verify and click Verify Firmware in the Actions
   Note After you upload firmware to the IoT Platform, you must verify it on a small number of devices. You can proceed with batch upgrades only after you confirm that the upgrades on the test devices are successful.
2. Configure the verification parameters.

   Parameter	Description
   Target Version	The dropdown lists all firmware versions currently used by devices under this product. Select one or more source versions. Devices running these versions appear in the Devices to Verify list.
   Devices to verify	Select devices for this test.
   Device upgrade timeout	Set the maximum time allowed for a single device to complete the upgrade. Timeout starts when the device first reports upgrade progress. Range: 1 to 1,440 minutes.

   Set the App confirmation required

   • Yes: Push a notification to the app to inform the user about the upgrade.
   • No: Perform a silent upgrade without notifying the user.
3. Click OK.
   • If the verification fails

     The status is displayed as Verification Failed. You can verify the firmware again.

   • If the verification succeeds

     The status is displayed as Verified. You cannot verify this firmware again, but you can proceed with a batch upgrade.

Batch upgrade

You should deploy the firmware to many devices only after successful verification and functional validation. A batch upgrade sends targeted upgrade notifications to multiple devices.

Review the following information before you start a batch upgrade:

• Batch upgrades are not available for test devices.
• Never perform batch upgrades with unverified firmware.
• The upgrade process takes time, from the moment the notification is received to the completion of the upgrade. Please wait for the results.
• Some devices may fail to upgrade if they are still processing a previous upgrade (status: pending or upgrading).
• If a device encounters an error during the upgrade, such as a download failure, checksum failure, or decompression failure, and reports the error to the OTA system, the system marks the upgrade as complete even though it failed.
• On the firmware details page, you can view the upgrade status of each device. The Failed Upgrades tab shows brief reasons for the failures.

1. Select the firmware for the batch upgrade and click Batch Upgrade in the Actions
2. Configure the batch upgrade parameters.
   Set the App confirmation required parameter as needed:

   • Yes: Push a notification to the app to inform the user about the upgrade.
   • No (default): Perform a silent upgrade without notifying the user.

   Parameter	Description
   Target Version	The dropdown lists all current firmware versions used by devices under this product. Select the versions to upgrade from. Required for full upgrades.
   Upgrade strategy	Static upgrade: Upgrade only devices that currently meet the conditions. Dynamic upgrade: Upgrade current eligible devices and continuously check for newly eligible devices, including the following: Newly activated devices that meet upgrade conditions. Devices that initially reported an ineligible version but later report an eligible one. Note Only one dynamic upgrade batch is allowed per firmware. To create a new dynamic batch, cancel any existing one first.
   Upgrade scope	All devices: Upgrade all devices under the product. Targeted upgrade: After selecting this option, a device selection box appears. Click it and choose specific devices in the dialog on the right. Only selected devices are upgraded. Note Multiple source versions can be selected for targeted upgrades. Previously entered source versions are selected by default. Regional upgrade: Upgrade devices located in specified geographic regions. After selection, province and city options appear below. Grayscale upgrade: Partial rollout. Available only with static upgrade strategy. After selection, enter a grayscale percentage for the selected devices. The IoT Platform calculates the number of devices (rounded down). At least one device must be included.
   Upgrade time	Set when devices should start upgrading. Upgrade Now: Starts the firmware upgrade immediately. Scheduled upgrade: Set a start and end time. Start time must be 10 minutes to 7 days from now. End time must be at least 1 hour after start time and up to 30 days later. You can omit the end time, meaning no forced cutoff. Note Scheduled upgrade is only available with static upgrade strategy.
   Firmware push rate	Set how many devices per minute receive the firmware download URL. Range: 10–1,000.
   Retry interval after failure	When to retry if an upgrade fails. Options: No retry Retry immediately Retry after 10 minutes Retry after 30 minutes Retry after 1 hour Retry after 24 hours
   Maximum retry attempts	Set the maximum number of retries after failure. Options: 1 attempt 2 attempts 5 attempts
   Device upgrade timeout	Set the maximum time allowed for a single device to complete the upgrade. Timeout starts when the device first reports upgrade progress. Range: 5 to 1,440 minutes.
   Overwrite previous upgrade tasks	If a device is part of multiple upgrade batches (status: pending confirmation, pending push, or pushed), decide whether to overwrite prior tasks. Yes: Execute only the new task. Cancel previous tasks. No (default): If a device already has an upgrade task, execute only that task. Note If overwrite is disabled, ongoing upgrades continue and new tasks are ignored.
   Apply only to devices reporting new versions	This parameter applies only when Dynamic upgrade is selected. Choose whether to apply the upgrade only to devices that report new firmware versions after the batch starts. The source version is based on the newly reported version. Yes: Upgrade only devices that report new versions after the batch starts. No (default): Upgrade currently eligible devices and continue checking newly reported versions.

3. After you submit the batch upgrade, click View for the firmware. Then, on the Batch Management tab, click the Device List tab to check the upgrade status.

   Status	Description
   Pending Confirmation	Waiting for user confirmation in the mobile app before OTA upgrade begins. This status appears only if App confirmation required was set to Yes when creating the batch.
   Pending Push	Firmware upgrade notification has not yet been sent to the device. Reasons for this status include device offline, scheduled push, or rate limiting. The status displays as: Pending Push (Device Offline) Pending Push (Scheduled: 2020/XX/XX XX:XX:XX) Pending Push
   Pushed	Firmware upgrade notification has been sent. The device has not yet reported progress.
   Upgrading	Device received the upgrade notification and has started reporting progress.
   Upgrade Successful	Device reported 100% progress and the correct post-upgrade version number. Note After a successful upgrade, the device should report the new version immediately. Otherwise, the upgrade may be marked as failed due to timeout.
   Upgrade Failed	Possible causes of failure include the following: A new batch upgrade was initiated while a previous upgrade was still active, and overwrite was disabled. The new task fails. You can: Wait for the previous upgrade to finish before starting a new one. Enable overwrite when initiating the upgrade. Note Tasks in Upgrading status cannot be overwritten. Device reported -1, -2, -3, or -4 via the upgrade progress topic, indicating failure: -1: Upgrade failed. -2: Download failed. -3: Checksum failed. -4: Flash write failed. Device did not report the target version within the configured timeout period after first reporting progress. Device reported a version other than the source or target version while in Upgrading status. If you specified source versions and enabled retries, automatic retries occur in these cases: Failure due to reporting an unexpected version during Upgrading status. The device reports an upgrade failure with an error code of -1, -2, -3, or -4 to the upgrade progress topic. During an automatic retry, the device's upgrade status in the cloud remains unchanged. For example, when a retry is performed in the Pushed state, the status remains Pushed. When a retry is performed in the Upgrading state, the status remains Upgrading. Note The cloud does not trigger automatic retries in these cases: The upgrade failed due to a timeout error. Manually canceled upgrades.
   Canceled	The upgrade for this device was canceled.