Update Firmware

This topic describes how to deploy full or incremental updates to devices, which is used to deploy firmware updates to end devices via OTA.

Background

For the MCU SDK or TuyaOS based devices that have been delivered, you can deploy firmware updates to them over the air (OTA) without flashing firmware.

Terms

Term	Explanation
Custom firmware	The custom firmware that a developer uploads to the Tuya Developer Platform. It is maintained by the developer.
Tuya firmware	The firmware officially provided and maintained by Tuya.
Manufacturer firmware	The firmware that a developer of the Tuya Developer Platform obtains through OEM Product or Copy Product. It is maintained by the firmware manufacturer.
Firmware type	There are three types of firmware: production firmware, user area firmware, and firmware updates. Production firmware and user area firmware: Used by Tuya’s manufacturer to flash the firmware. If you choose firmware flashing by Tuya, these two types of firmware must be uploaded to the Tuya Developer Platform. Firmware updates: Used to deploy OTA firmware updates, applying to all products.
Firmware owner	The developer account that has permission to manage the firmware. Case 1: For firmware created during product creation, the account space to which the current product (PID) belongs owns the firmware. Firmware created under My Products is owned by the space that is currently logged in. Firmware created under Customer Products is owned by the space to which the creator of the current product and firmware belongs. The customer products can be obtained through OEM Product, Copy Product, or Space Authorization. Case 2: For firmware created in Firmware Management, the space that is currently logged in owns the firmware.
Tuya standard chip	The chips that are adapted to Tuya’s host program. You can use Tuya’s host to flash firmware to Tuya standard chips.
Channel ID	Used for firmware updates only. The channel ID is used to identify types of firmware to perform updates on different firmware.
Canary release	Canary release is a development strategy in which a new version of firmware is deployed to a small subset of users first, and the base version remains deployed for normal operations on the same stage. Once the new version is accepted, the update is rolled out to the rest of the users.

Prerequisites

You have created at least one product. For more information, see Create Products.

Full updates

There are three types of firmware that can be updated via OTA.

• Type 1: The released Tuya firmware or manufacturer firmware.
• Type 2: Custom firmware.
• Type 3: Firmware on TuyaLink-based devices.

Procedure

Type 1: The released Tuya firmware or manufacturer firmware

1. Log in to the Tuya Developer Platform.

2. In the left navigation bar, choose Product > Device > Firmware Update.

   For Tuya firmware or manufacturer firmware, an update can be deployed only when a new firmware version is provided by Tuya or the manufacturer.

3. Change to the target product and select the firmware.

   

4. Click New Update Deployment and complete the required settings.

   

   Parameter classification	Parameter	Description
   Basic Information	Target Product	The product that the current firmware is associated with.
   	Firmware Name	The name of the current firmware.
   	Firmware Version	The firmware version to update to. Only the firmware version that has not been deployed for an update can be selected.
   	Critical Version	Specify whether the current firmware version is a critical version. Yes: A firmware version that users must update to. No: A firmware version that users can skip.
   Upgrade 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 will not receive a firmware update notification on the app, but need to manually check for new updates.
   	Auto Update	Automatic update is determined by the auto update setting on the Tuya Developer Platform and on the app together. Note: One product may have different firmware, so make sure to select the correct firmware and firmware version. Off: Turn off automatic update. The update method you selected will be performed. On: Turn on automatic update. The update will be installed in either of three methods, namely update notification, forced update, and check for updates.
   	Description	Enter the description of the update in Chinese and English. The description will be displayed on the app.
   	Remarks	Enter the remarks about the update.
   Publishing Scope Settings	Update Version	Enter one or more firmware versions to update from. All versions earlier than the firmware version set in Basic Information are selected by default.
   	Update Region	The countries or regions where the firmware update will be rolled out. For China, you can select a specific city. All regions are selected by default.

5. After the configuration is set, click OK. A record will be generated.

   

6. Click Common Verification Device to add devices under test (DUTs). This allows you to add a bunch of devices used for test purposes. Each time you perform a test, you can quickly select DUTs from the list.

   

   • You can select the data center where the device is deployed in the top right corner of the page.

   • You can add devices by using the app account. After your app account is verified, under your account, all the devices associated with the PID will be added to the allowlist.

     
     For security purposes, your app account must be verified first.

7. Verify firmware update deployment.

   1. Click Verify in the Firmware Update column. You can verify deployment to different data centers by changing the data center in the top right corner of the page.

      

   2. You can add a DUT by selecting a device from the allowlist or by entering a device ID. If you choose Add by Device ID, the firmware update will be delivered to the specified device.

      

   3. Click Verify Update to check the result.

      

8. Deploy an OTA firmware update.

   After successful verification, you can click Release to deploy an OTA firmware update to devices. Due to the iteration of the firmware update feature, the legacy release process is also available.

   The new process of releasing OTA updates appears by default. You can click Switch to Old Process to use the legacy release process. The legacy process will be retired in the future. Tuya will notify developers of such changes beforehand.

   New OTA firmware update release

   1. Click Release to enter the deployment process.

   2. In Release Rule Settings, you can choose Grey Released to roll out the firmware update to a specified percentage of devices in a specific data center.

      • Data centers are isolated from each other. You can switch to another data center and deliver the firmware update to that data center.

      • Grayscale by proportion: Allows you to specify the percentage allocation of devices that will be exposed to the update. In the first rounds of deployment, it is recommended to set a small proportion, such as 5%. You can then examine the results, and if things go smoothly, gradually increase deployment to 100% of devices.

      • Pause: You can pause and resume the deployment as needed.

      • Key Metrics: Give you an overview of the deployment.

        • Total Number of Upgradable Devices

        • Number of Specified Devices to Update

        • Number of Devices Performing Updates

        • Number of Successfully Updated Devices

          

      • Data Analytics: Shows the distribution of update status and update installation.

      • Data Trend: Shows the number of devices that initiate the update as well as those that install the update successfully.

      • Details of Updated Devices: Allows you to check the update details by device ID.

   Legacy OTA firmware update release

   1. Click Release to enter the deployment process.

   2. Click Switch to Old Process.

      

   3. After you click Gray released or Full amount released, a request for releasing an update will be submitted. Tuya will verify firmware security. If your firmware is verified, Tuya will deliver the firmware update to the target devices as you requested.

      
      • After the firmware update is verified on the DUT, you can deploy an OTA firmware update.
      • You can deploy the update to different data centers.
      • 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 you submit a deployment request, your firmware will be reviewed within 24 hours. Consider the review time when you schedule the deployment. If your firmware has been reviewed, there is no review process any more.

Type 2: Custom firmware

Only the owner of the custom firmware can create a firmware version.

1. Log in to the Tuya Developer Platform.

2. In the left navigation bar, choose 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.
   • Add Firmware Version: Click this button to create a firmware version if no firmware version is available or a firmware version has been deployed.
   For more information, see the configurations of Type 1.

   Parameter	Description
   Basic Information	You can upload a firmware version to update to. 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 and authorization. Run Mode: According to the SPI Flash mode, you can select QIO for the Tuya modules by default. This option only applies to firmware flashed by Tuya. Country Code: It is supported by default. FFS Capability: It is supported by default.

5. Click Only Save or Save & Enable.

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

   You can set the Update Deployment Scope to specify which product this firmware update applies to.

6. Deploy a firmware update.

   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 Type 1 above to deploy an OTA firmware update.

Type 3: Firmware on TuyaLink-based devices

This section applies to products that are developed with the TuyaLink solution and the Open Protocol.

1. Log in to the Tuya Developer Platform.

2. In the left navigation bar, choose Product > Development.

3. Find the target product and click Develop.

4. Under the Device Development tab, choose Firmware Management and click Add Firmware. Complete the required configuration and upload a firmware version.

5. Save and enable the firmware version.

   

6. The next steps are the same as Type 1 and Type 2.

   TuyaLink-based devices do not support incremental updates.

Incremental updates

OTA firmware update allows you to update a device remotely. Typically, a full update package is sent to the target device for installation. A large package requires more bandwidth for transmission and more memory for storage. For resource-constrained devices, such as NB-IoT and Cat.1, the smaller incremental updates make OTA firmware updates more feasible.

Applicability

This feature applies to firmware that integrates with Tuya’s incremental update SDK. NB-IoT and Cat.1 devices are the typical use cases. Matter-certified devices also apply.

Terms

Term	Explanation
Target Version	The firmware version to update to.
Earlier Version	The firmware version to update from.
File to Build Incremental Package	The file used for incremental calculation. This file can be recognized by the incremental algorithm to compare it with another firmware version.
Incremental Package	The incremental update package is generated based on the target version as well as the File to Build Incremental Package. It is the update package delivered to devices for installation.

Prerequisites

Before performing an incremental update, make sure:

• The firmware supports incremental updates.
• The File to Build Incremental Package is available.

Step 1: Add a firmware version

1. Log in to the Tuya Developer Platform.

2. In the left navigation bar, choose Product > Device > Firmware Management.

3. Find the target firmware and click Details in the Operation column, and then click Add Firmware Version on the page that appears.

   

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

   

Step 2: Build an incremental package

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

   

2. Click Build Incremental Package.

   

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

   

Step 3: Build the firmware

In the Firmware Version Management section, click Enable. Then, the firmware version becomes Enabled.

Step 4: 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 download the incremental package.

   

3. Check the available incremental package.

   

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

Step 5: Verify the update

The steps are the same as Type 1 and Type 2.

Step 6: Deploy the update

The steps are the same as Type 1 and Type 2.

FAQs

Why can’t I add a version for my custom firmware?

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

Why can’t I find the firmware key in firmware management?

Check whether the firmware key was created with the current account. If not, the account does not have permission to view the firmware key.

Can devices that have no location information receive an OTA firmware update?

• For devices in mainland China: If the app is not allowed to access the location, the device connected to this app may not receive OTA firmware updates.

• For devices outside mainland China: The country code of a user’s app account is used as the endpoint to receive OTA firmware updates. If the country code does not fall within the specified target regions, the device may not receive OTA firmware updates.

Reference

For more information, see Manage Custom Firmware.