Manage Firmware

Background information

To enhance the self-service development capability of customers, Tuya Developer Platform has introduced firmware management. You can manage firmware uploaded by yourself during product development. With deployment scope setting, you can manage available firmware developed by OEM, copy, or transfer.

Application scope

The function mainly applies to those who develop products by copy or OEM.

Term

Term	Definition
Custom firmware	This kind of firmware is uploaded, maintained, and updated by you.
Tuya firmware	This kind of firmware is developed and updated by Tuya. You can select and use the firmware.
Manufacturer firmware	This kind of firmware is obtained when you develop products by copy or OEM. It is maintained and updated by the manufacturer.
Firmware type	It is divided into production firmware, user area firmware, and update firmware. Production firmware and user area firmware are mainly used during the flashing by Tuya’s plant, and they are required only when the product is produced by Tuya. Update firmware is mainly used for device remote OTA updates. It is available for all products.
Firmware owner	The account that can manage the firmware. It is divided into the following two cases. Case 1: If the firmware is created in product development, the firmware owner is the account that creates the current PID. If the firmware is created in My Products, the firmware owner is the current login account. If the firmware is created in Customer Products, the firmware owner is the account space that creates the current PID and firmware. Customer products are mainly developed by OEM, copy, or authorized by other enterprises. Case 2: If the firmware is created in firmware management, the firmware owner is the current login account space.

Operating procedure

Firmware management is mainly used to manage My Custom Firmware. You can add, edit, delete, enable, and deactivate the firmware.
By enabling and deactivating the firmware, you can set the availability of the firmware version. For example, if you want to remotely update your devices via OTA, you need to add a firmware version and enable it in Firmware Version Management, and then go to Update Firmware > New Update Deployment to add a new firmware version. Then, you can send update notifications to devices.

Prerequisites

You have created at least one product. See Create Products for details.

Scenario 1: Custom firmware management

Choose Product > Development in the left-side navigation bar, find a product, and click Continue to Develop. On the page that appears, click Hardware Development > Add Custom Firmware.

You can add custom firmware in Development or in Firmware Management in 3 steps.

Step 1: Add firmware (generate firmware key)

1. Complete the basic information of firmware, and confirm to generate the firmware key. You can see the firmware in Firmware Management. The key is mainly applied to firmware updates and maintenance in the future.
2. (Optional) If you select Tuya chips for the product, you need to complete Production Configuration.
   Tuya will flash the firmware and arrange the production as per the production configuration. If the chip is not flashed by Tuya, Production Configuration is not supported.
   

Step 2: Upload production firmware (add firmware version)

With the firmware key generated, you are required to develop the firmware. After development, add a new firmware version and upload a valid firmware file, which mainly refers to production firmware.

Note: Generally, in product development, you upload production firmware and user area firmware. Every firmware file you upload (new firmware version) will be maintained as a version.

Step 3: Enable the firmware version and set the deployment scope

By default, once the firmware version is added, it will have a status—enabled or not enabled.

• Not Enabled (default): The firmware version is not available now. You cannot receive or purchase licenses in product development.
• Enabled: The firmware version is available for products.
  • If production firmware and user area firmware are enabled, they can be selected during product development.
  • If update firmware is enabled, it can be selected during firmware updates.

Firmware enabling process

Firmware enabling is for managing products with the same firmware key. You can specify whether an account or a PID can receive update notifications for firmware updates or product development.

Service process (see the diagram above)

1. With PID 1 including firmware key 1 under its account, Account A copies a product to or creates an OEM product in Account B and Account C.
2. Account B and Account C can receive a copy or OEM link to create PID 2 and PID 3. These two products have firmware key 1 v1.0.0 by default.
3. If Account A iterates the firmware key 1, it generates a new firmware version v1.0.1.
4. If you want Account B and Account C to use the firmware version, you should select General availability when enabling firmware. In this way, both Account B and Account C can receive the new version v1.0.1.
5. If you only want Account B to use the firmware version, you should select Limited scope and add Account B to the whitelist when enabling firmware. In this way, only Account B can receive the new version v1.0.1.
6. If firmware key 1 is applied to PIDs of N customers, you can also set the deployment scope.

Whitelist of limited scope
A whitelist refers to the account/PID and organizations that can use the enabled firmware version during update and development. The organizations get firmware keys by copying a product or creating an OEM product.

Impact scope of enabling

• If you have uploaded production firmware, after you enable the firmware, the product in the whitelist can receive update notifications. You can copy it or develop it by OEM.
• If you have uploaded update firmware, after you enable the firmware, the product in the whitelist can receive update notifications.
• After being enabled, the firmware file cannot be modified. If you want to modify it, you must deactivate it first.
• During product development, you must enable the new firmware version (upload the production firmware) for customers to place an order.

Note: After you enable the firmware, OEM customers can use its versions if the product is published. To avoid troubles like misusing faulty firmware, it is recommended to set the deployment scope limited during debugging stage.

Step 4: View firmware management

After you complete product development, you can enter Device > Firmware Management > My Firmware to view the firmware information.

Note: Only firmware owners can add a new version of firmware (see Term).

Scenario 2: Remotely update devices with new firmware versions (firmware OTA update)

In practice, you can go to Firmware Management to add a new firmware version. Notice that only the firmware owner can do it.

Process

Step 1: Add a new firmware version

Note: Only the firmware owner can add a new version. If the button Add Firmware Version is invalid, it indicates that you are not the firmware owner. Contact the product owner to get authorized.

Add a firmware version
Entry 1 (recommended): In the left-side navigation bar, go to Product > Device > Firmware Management, select a firmware, and click Create Version.

Entry 2: In the left-side navigation bar, go to Product > Device > Firmware Management > Details, select a firmware, and click Add Firmware Version.

Entry 3: In the left-side navigation bar, go to Product > Device > Firmware Update, select a firmware, and click Add Firmware Version.

Complete the information of the firmware version, and upload the firmware file.

Step 2: Enable the firmware version

When you enable the firmware, you need to select the firmware type and its deployment scope.

• If you select Firmware Updates, customers who use the firmware can receive update notifications in Firmware Update.

• If you upload Production Firmware, customers who use the firmware can update it in the third step of Hardware Development.

  

Step 3: Deploy new updates

After you enable the new firmware version with update files, go to Firmware Update, and you can see update notifications for the firmware. Click New Update Deployment, and complete the setting.

After the setting, the new version will be displayed below My Updates. You can continue the process to verify and publish the version.

Scenario 3: Set the latest version as factory firmware

In practice, if you want to set the latest version as factory firmware, go to product development to change it.

Process

Step 1: Same as Step 1 for Scenario 2.

You need to upload both production firmware and user area firmware.

Step 2: Same as Step 2 for Scenario 2.

You must enable the production firmware first.

Step 3: Change version

After enabling the new firmware version, you will receive update notifications in your product list. You can enter Product > Development > Continue to Develop > Hardware Development, and click Update to change the version.

Product list

Hardware development

Update firmware version

Updated successfully