Update Firmware

This topic describes how to update firmware.

Background information

If your product is developed based on MCU SDK or TuyaOS, to update the firmware of the devices that have been delivered, you can remotely update their firmware on the Tuya IoT Development Platform. In this process, firmware flashing is not required.

Application scope

This topic applies if you want to update firmware on the Tuya IoT Development Platform.

Terms

Prerequisites

At least one product is created. For more information, see Create Products.

Procedure

Depending on the source of firmware, the following firmware update scenarios are supported:

• Scenario 1: update Tuya’s firmware or third-party firmware that has been released
• Scenario 2: Update custom firmware that has been uploaded

Process

Type 1: Update released firmware provided by Tuya or third party

1. Log in to the Tuya IoT Development Platform.

2. In the left-side navigation pane, click Product > Device > Firmware Update.

   During product development, the firmware can be provided by Tuya or by a third-party manufacturer on an OEM basis. This type of firmware can be updated only after a new firmware version is released on the Tuya IoT Development Platform or by the manufacturer.

   

3. Choose the target product from the Change Product drop-down list and select its firmware to be updated.

   

4. Click New Update Deployment to set update rules.

   

   Classification	Parameter	Description
   Basic Information	Target Product	The product that uses the specified firmware.
   	Firmware Name	The name of the specified firmware.
   	Firmware Version	The target version to which the firmware is expected to be updated. Only the version to which no update is performed can be selected.
   	Critical Version	Indicates whether the specified version is a critical version. Yes: This version is required. No: This version is optional.
   Update Information	Update Method	Update Notification: Users receive a firmware update notification on the app and choose whether to install updates. Forced Update: Users receive a firmware update notification on the app and have no option but to update the firmware. Check for Updates: Users can tap the top right corner on the device panel and check for updates.
   	Auto Update	Whether auto update is enabled depends on the setting of this Auto Update switch and the auto update setting on the app. Note: A product might use multiple types of firmware. You need to select the target firmware and its version to be updated. Disable: If you disable Auto Update, the specified update method will be implemented. Enable: If you enable Auto Update, the firmware will be updated by any of the methods, including Update Notification, Forced Update, and Check for Updates.
   	Description	Enter the description in Chinese and English. This content will appear on the app.
   	Remarks	The remarks on the current update.
   Publishing Scope settings	Update Version	Select one or more earlier versions to be updated. By default, all versions earlier than the version specified in Basic Information are selected.
   	Update Region	Select one or more regions to which the current update applies. If China is selected, one or more provinces or cities can be further selected. If other countries or regions are selected, no further options are available. By default, all regions are selected for the update.

5. After the rules are set, click OK. An update record is generated on the list.

   

6. Click Common verification equipment to add a device for regular verification. In the next step, this device can be easily selected to verify firmware.

   

   • You can select multiple device IDs that are associated with your app account. These devices must be the allowlisted devices.

   • Select the data center to which the devices belong, including China Data Center, Western America Data Center, Central Europe Data Center, India Data Center, Eastern America Data Center, and Western Europe Data Center.

   • Set the app account to add an allowlisted device. After the app account is entered and verified, all devices with the product ID (PID) for the app account will be added to the whitelist.

     

     For security purposes, the app account must pass the verification before the associated devices can be added to the whitelist.

7. Push and verify firmware.

   1). Click Verify in the Firmware Update column for the target firmware. The following data centers for the devices to be verified are supported: China Data Center, Western America Data Center, Central Europe Data Center, India Data Center, Eastern America Data Center, and Western Europe Data Center.

   

   2). You can add devices from common verification devices or by device ID. If you click Add by Device ID, the firmware will be pushed to the specified list of devices.

   

   3). Click Verify Update to verify the OTA update.

   

8. Release the OTA update.

   If the test device passes the verification, the OTA update qualifies for the bulk update. Click Release to start the release process. Due to the platform iterations, the release process is also updated, but the earlier release process is still available along with the new one.

   New OTA update process

   1). Click Release to release a new version.
   2). In the Publishing rule Settings section, select Gray released from the Release mode drop-down list. You can select a target data center (not device locations) and set the release proportion.

   You can also switch to the earlier release process. This earlier process will be deprecated later. The deprecation will be announced in advance.

   • The devices that belong to a data center are isolated from those of other data centers. You can switch between data centers and select the respective devices for the OTA update.

   • Grayscale by proportion: You can submit a proportion of devices to be updated. During the first several releases, a small proportion such as 5% is recommended. The visualized release data helps you determine the proportion of devices to be updated, until 100% of the target devices are updated.

   • Pause: During the release process, if any problems are found, you can pause the release to minimize the impact that might be caused by the problems. After the problems are fixed, you can resume the release.

   • Upgrades publish core data: Multiple metrics are collected, including

     • Total number of devices available for update
     • Specified number of devices to be updated
     • Number of devices triggered for update
     • Number of devices updated successfully

     

   • Data Analytics: Distribution of Update Status and Distribution of Update Times are included.

   • Data Trend: View the trend chart of the number of devices triggered for update and the number of devices updated successfully.

     

   • Details of Updated Devices: Query the details of updated devices by device ID.

   Old OTA update process

   1. Click Release to release a new version.

   2. Click Switch to Old Process.

      

   3. After you select Full amount released or Gray released from the Release mode drop-down list, the system automatically submits a release request. Tuya will review the firmware. If the firmware passes the review, Tuya will push the new firmware version to the devices within the specified regions.

      
      • After the test device passes the verification, the firmware can be updated over the air.
      • Each OTA update can be released to multiple data centers in the same update.
      • Canary Release and All Release are supported, and release time can be set. For canary release, one or more regions and versions can be selected, and the quantity can be defined.
      • After the release is confirmed, 24 hours are required by Tuya to finish reviewing the firmware if it is not reviewed. If the firmware has passed the review, this 24-hour period for review is not required.

Scenario 2: Update custom firmware uploaded

The custom firmware is usually uploaded during product development. Only the account of the Tuya IoT Development Platform that owns the firmware can be used to create a new firmware version.

1. Log in to the Tuya IoT Development Platform.

2. In the left-side navigation pane, click Product > Device > Firmware Update.

3. Select firmware with My Custom Firmware in the Firmware Source column.

   

4. Click New Update Deployment to set update rules.

   • Firmware Version: Select an existing firmware version to be updated.

   • Add Firmware Version: Click this button to create a firmware version if no firmware version exists, or if the options in Critical Version have been updated and do not support a secondary release.

     Parameter	Description
     Basic Information	Upload the update firmware as the new version. If this new version is planned for production, both production firmware and user area firmware can be uploaded.
     Production	This configuration is used for production authorization. Run mode: According to the SPI Flash mode, QIO is selected for the Tuya modules by default. The option only applies to firmware versions provided by Tuya. Country Code: It is supported by default. FFS Capability: It is supported by default.

     

5. Click Only save or Save & Enabled.

   After you complete the basic information and upload the firmware, the firmware is not enabled by default. To update the firmware over the air, click Save & Enabled.

   You can set the update deployment scope for the specified products.

   

6. Update new custom versions.

   1. Click Update on the Firmware Version Management page, or in the left-side navigation pane, choose Product > Device > Firmware Update and select the firmware.

      

   2. Select the target product, enter the parameters, and then click OK.

      

7. Follow Steps 6, 7, and 8 in Scenario 1 above to update the custom firmware over the air.

Additional feature: incremental update of firmware

Firmware updates rely on the over-the-air update technology and can be used to update devices remotely.

In the conventional method for a generic firmware update, a full firmware package is pushed for the update. This package must be downloaded on the target devices to be updated remotely. For a large firmware package, a large amount of data traffic might be consumed and the device storage space must be sufficient. Therefore, certain devices such as NB-IoT and Cat.1 devices cannot be remotely updated as expected in the conventional firmware update method.

In this case, a smaller update package is expected to update the firmware. This section provides an incremental update solution to fix the problem.

Application scope

This solution applies to the firmware that uses Tuya’s incremental update SDK. NB-IoT and Cat.1 devices are supported.

Terms

Procedure

Before the incremental update, make sure the target firmware supports this feature, and the file to build the incremental package is available for the earlier version to be updated.

Step 1: Add a firmware version

Select Product > Device > Firmware Management, find the target firmware and click Details in the Operation column, and then click Add Firmware Version on the page that appears.

Step 2: Upload the file to build an incremental package

Enter the required information and upload the file in the File to Build Incremental Package field.

Step 3: Build an incremental package

1. In the Firmware Version Management section, click Incremental Package in the Operation column to go to the Incremental Package page.

   

2. Click Build Incremental Package.

   

3. The system generates an incremental package. The File to Build Incremental Package is not uploaded for the earlier version, the incremental update is not supported.

   

Step 4: Build the firmware

In the Firmware Version Management section, click Enable in the Shelf status column. Then, this status becomes Enabled for the firmware version.

Step 5: Go to Firmware Update and add the update deployment

1. Select Product > Device > Firmware Update, and click New Update Deployment.

2. Enable Incremental Update to allow the target devices to get the incremental package.

   

3. Check the available incremental package for update.

   

4. Click OK to generate a firmware update record. This way, the target devices can get the incremental package. The specific process depends on the update method supported by the devices. The full firmware package can still be obtained for update.

Step 6: Verify the update

Repeat the steps in Scenarios 1 and 2.

Step 7: Release the update

Repeat the steps in Scenarios 1 and 2.

FAQs

Q1: Why did I fail to add new versions for my custom firmware?

Your account does not own the target firmware or your account is not authorized for the OTA update. After your account is authorized by the firmware owner, you can add new versions for the firmware.

Q2: Why did I fail to find the firmware key in the Firmware Management module?

First, check whether the firmware key is created with the current account. If not, this account cannot be used to view the firmware key.

Q3: Can devices receive push notifications for OTA updates when their location permissions are not granted to the app?

These devices might be located:

• Inside mainland China: If the app does not have access to the device location, this type of device might fail to receive the push notifications for OTA updates.

• Outside mainland China: Push notifications are sent to this type of device by country code. The account of the app that runs on a device is registered with a country code. If the country code does not fall within the specified target regions, the device might fail to receive the push notifications for OTA updates.

References

For more information, see Manage Custom Firmware.