English
English
简体中文
Contact Us
Register
Log In
layoutIndex

Update Firmware

Last Updated on : 2022-08-02 08:30:21download

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.

The control board must support the firmware update feature.

Application scope

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

Terms

Term Description
Custom firmware The firmware that you customize and upload on the Tuya IoT Development Platform. It is updated with your own efforts.
Tuya firmware The firmware that is developed by Tuya and provided for you to select during the development on the Tuya IoT Development Platform. It is updated by Tuya.
Manufacturer’s firmware The firmware that you get from an OEM product or after you copy a product on the Tuya IoT Development Platform. It is updated by the manufacturer that provides the firmware.
Firmware type Classified into production firmware, user area firmware, and update firmware.
  • Production firmware and user area firmware: This type of firmware is uploaded during the production and firmware flashing for ‘Powered by Tuya’ products.
  • Update firmware: This type of firmware is updated over the air for all products.
Firmware owner The account that is granted permissions to manage certain firmware. Firmware owners are used in the following scenarios:
  • Scenario 1: If certain firmware is created during product development, the firmware belongs to the account space that is associated with the respective product ID (PID).
    • The firmware created for the products listed on the My Products tab belongs to the space of the current account.
    • The firmware created for the products listed on the Customer Products tab belongs to the space that is associated with the respective PID and that is owned by the firmware creator. These products are usually the OEM products or obtained after they are copied or authorized between organizations.
  • Scenario 2: The firmware created on the Firmware Management page belongs to the space of the current account.
Tuya standard chip This is used for the label of a chip. For the chip that has been used by Tuya, Tuya’s host program can be reused for firmware flashing.
Channel ID Only used for firmware update. If a product has multiple firmware versions to be updated, these versions are distinguished by channel ID during the update in the cloud and on the device.
Firmware canary release This release method is used to update the device firmware version progressively to the target version. Before a newly developed firmware version is released, it needs to pass the A/B testing. During this testing, certain testers use the earlier firmware version A and the other testers use the new version B. For version B, if no feedback is provided or no faults are found, this version can be progressively released to more testers until the firmware version of all target devices is updated to version B.

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

Update Firmware

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.

    Update Firmware

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

    Update Firmware

  4. Click New Update Deployment to set update rules.

    Update Firmware

    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.

    Update Firmware

  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.

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

      Update Firmware

      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.

    Update Firmware

    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.

    Update Firmware

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

    Update Firmware

  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

      Update Firmware

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

      Update Firmware

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

      Update Firmware

    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.

      Update Firmware
      • 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.

    Update Firmware

  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.
      Update Firmware
  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.

    Update Firmware

  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.

      Update Firmware

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

      Update Firmware
  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

Term Description
Target version The target version to which the firmware is expected to be updated.
Earlier version The earlier firmware version to be updated.
File to build incremental package The file used to compare against the earlier version based on the incremental algorithm and generate an incremental package.
Incremental package An incremental update package that is built after the comparison between the earlier version (the one you want to update from) and target version (the one you want to update to). This package is pushed for OTA updates. The target version applies to the target devices and updates their firmware based on the incremental package.

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.

Update Firmware

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.

Update Firmware

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.

    Update Firmware

  2. Click Build Incremental Package.

    Update Firmware

  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.

    Update Firmware

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.

Update Firmware

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.

    Update Firmware

  3. Check the available incremental package for update.

    Update Firmware
  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.