Firmware Update

Firmware update is the process to flash new firmware to a chip and update the earlier firmware. Tuya supports regular firmware updates to meet your development and market requirements. Tuya also deactivates certain legacy firmware versions in line with chip iterations of the manufacturers. In the case of device feature updates, firmware updates are also required.

Update process

API description

Get firmware update information

This method returns the firmware update model ThingSmartFirmwareUpgradeModel. The following settings are applied:

• upgradeMode: Indicates the firmware update mode.
• type: Indicates the firmware update channel type.
• typeDesc: Describes the firmware type.

Firmware update modes

When you query the list of firmware updates, the upgradeMode field of ThingSmartFirmwareUpgradeModel includes the following valid values:

• 0: Generic firmware update. This is an ordinary update mode, used to update the firmware on the device.
• 1: PID-specific firmware update. This update mode applies the philosophy of products. Update versions can be differentiated by functional modules, such as product schema, panel settings, multilingual settings, and shortcut control.

Firmware update channel types

When querying the list of firmware updates, the type field of ThingSmartFirmwareUpgradeModel indicates the update channel type for generic firmware, with typeDesc describing the channel.

The following table lists descriptions of type for a generic firmware update. We recommend that you describe the firmware by using the value of typeDesc that is actually returned by the model.

Channel type of generic firmware update	Description of firmware update channel
0	Main network module, Wi-Fi module, and Bluetooth module
1	Bluetooth module
2	GPRS module
3	Zigbee module
5	433 MHz module
6	NB-IoT module
9	MCU module
10 to 19	Extension module

API description

export class TSmartDevice {
  // Returns firmware information required by generic update and PID-specific update.
  public async checkFirmwareUpgrade(): Promise<ThingSmartFirmwareUpgradeModel[] | undefined>
  // Returns only the firmware information required by generic update.
  public async getFirmwareUpgradeInfo(): Promise<ThingSmartFirmwareUpgradeModel[] | void>
}

ThingSmartFirmwareUpgradeModel

Data model

Field	Type	Description
desc	string	The description of the update.
type	number	The type of firmware update channel, applying to generic firmware.
typeDesc	string	The description of the firmware update channel.
upgradeStatus	ThingSmartDeviceUpgradeStatus	0: No update available 1: An update available 2: Updating 5: Wait for the device to wake up
version	string	The new version of the firmware.
currentVersion	string	The current firmware version.
devType	number	0: Ordinary device 1: Low power device
upgradeType	number	0: Update notification 2: Forced update 3: Check for update
url	string	The URL to download a Bluetooth firmware update.
fileSize	string	The size of the firmware update, in bytes. This fileSize field applies to Bluetooth devices only.
md5	string	The MD5 (Message-Digest algorithm 5) hash value of the firmware.
controlType	boolean	YES: The device can be controlled during the update. NO: The device cannot be controlled during the update.
waitingDesc	string	The description of waiting for the device to wake up.
upgradingDesc	string	The description of the firmware update in progress.
canUpgrade	boolean	true: The update verification succeeds, with the update being accepted. false: The update verification fails, with the update being denied. You can show the remind field to inform the user about the failure.
remind	string	The description of a failed pre-validation.
upgradeMode	ThingSmartDeviceUpgradeMode	The type of firmware update, available starting from v3.35.5. 0: Generic firmware update 1: PID-specific firmware update

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

async getFirmwareUpgradeInfo() {
    let res = await this.device?.checkFirmwareUpgrade()
}

Query status of firmware being updated

Returns information about the firmware being updated.

API description

export class TSmartDevice {
	public async getFirmwareUpgradingStatus(): Promise<ThingSmartFirmwareUpgradeStatusModel | undefined>
}

ThingSmartFirmwareUpgradeStatusModel

Data model

Field	Type	Description
upgradeStatus	ThingSmartDeviceUpgradeStatus	The update status. Valid values: 2: Updating 3: Update succeeded 4: Update failed 5: Wait for the device to wake up 6: The update has been downloaded 7: Update timeout 13: Queuing in the cloud 14: The cloud is preparing 100: The app is preparing, for example, connecting to a Bluetooth device, or downloading the update
statusText	string	The description of status.
statusTitle	string	The title of the status.
progress	number	The progress of the firmware update. In some cases, the value might be -1 (usually when upgradeStatus changes). Please ignore this and maintain the previous progress. The change in upgradeStatus still needs to be handled.
type	number	The type of firmware update channel. The value is used when users confirm the update.
upgradeMode	ThingSmartDeviceUpgradeMode	0: Generic firmware update 1: PID-specific firmware update, available starting from v3.35.5
error	TSmartOTAError	The error message.

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

async getFirmwareUpgradeInfo() {
    let res = await this.device?.getFirmwareUpgradingStatus()
}

Start update

API description

export class TSmartDevice {
	public startFirmwareUpgrade(firmwares: ThingSmartFirmwareUpgradeModel[])
}

Parameters

firmwares: The list of firmware obtained from the device update information interface checkFirmwareUpgrade or getFirmwareUpgradeInfo.

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

upgradeFirmware() {
    this.device?.startFirmwareUpgrade(firmwares)
}

Continue update

Currently, this API method applies only when the callback for the update progress is returned and when error.code is 5005.

For Wi-Fi devices and combo devices, to ensure a successful update, the minimum signal strength level is specified. When an update is triggered, the system checks whether the device signal strength is within an acceptable range. If not, the callback for the update progress is returned, including error.code = 5005. Then, you can implement a UI interaction for users to make decisions. For example, a dialog box appears, saying The device signal is weak, and the update might fail. Continue to update?

API description

export class TSmartDevice {
	public confirmWarningUpgradeTask(isContinue: boolean)
}

Parameters

isContinue: Indicates whether to continue the update task.

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

continueFirmware() {
    this.device?.confirmWarningUpgradeTask(isContinue)
}

Cancel update

Currently, only low power devices can cancel an update. After an update is initiated for this type of device, the update task might get into the status of waiting for the device to wake up (upgradeStatus: 5). This API method can be called to cancel the update task.

API description

export class TSmartDevice {
	public async cancelFirmwareUpgrade(): Promise<void>
}

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

async cancelFirmware() {
 cancelFirmwareUpgrade() {
    this.device?.cancelFirmwareUpgrade().then(() => {
      console.log("cancel success")
    }).catch((e:Error) => {
      console.log("cancel failure")
    })
  }
}

Listen for callback

API description

export interface TSmartDeviceOTAListener {
  onOTAUpdateStatusChanged: (device:TSmartDevice, status: ThingSmartFirmwareUpgradeStatusModel) => void;
}

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

this.device.registerOTAListener({
        onOTAUpdateStatusChanged: (device: TSmartDevice, status: ThingSmartFirmwareUpgradeStatusModel) => {
          const upgradeStatus = status.upgradeStatus
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Failure) {
            // OTA update failed.
            AlertDialog.show({ message: 'device ' + devId + ' OTA Fail' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Timeout) {
            AlertDialog.show({ message: 'device ' + devId + ' OTA Timeout' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Prepare || upgradeStatus === ThingSmartDeviceUpgradeStatus.LocalPrepare) {
            // AlertDialog.show({ message: 'device ' + devId + ' OTA Prepare' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.InQueue) {
            AlertDialog.show({ message: 'device ' + devId + ' OTA InQueue' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.WaitingExecute) {
            this.output = "Preparing to start the OTA update."
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Upgrading) {
            if (status && status.progress && status.progress >= 0) {
              this.output = "Update progress - " + status.progress + "%"
            } else {
              this.output = "Are you ready? The OTA update is about to begin!"
            }
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Success) {
            AlertDialog.show({ message: "Updated successfully!" })
            this.output = "Updated successfully!"
            return
          }
        }
      })

Automatically update to the latest version

Certain devices support an automatic update to the latest version. You can use TSmartDeviceModel - supportAuto to check whether a device supports this feature.

API description

export class TSmartDevice {
	// Checks whether this feature is enabled.
	public async getAutoUpgradeSwitchInfo(): Promise<Record<string, Object> | undefined>
    // Saves the enabling states.
	public async saveUpgradeInfoWithSwitchValue(switchValue: number): Promise<boolean | undefined>
}

Parameters

switchValue: The status of the feature.

• 0: disabled 
• 1: enabled

Sample code

public device: TSmartDevice = TSmartDevice.create(devId)

  async getAutoUpgradeSwitchInfo() {
     let flag = await this.device?.getAutoUpgradeSwitchInfo() as Record<string, Object>
     console.log("Check support for automatic OTA updates: " + flag.value)
  }

  saveAutoUpgradeSwitchInfo() {
    const status = 0
    this.device?.saveUpgradeInfoWithSwitchValue(status).then(() => {
      console.log("Saved auto switch status successfully.")
    }).catch(() => {
      console.log("Failed to save auto switch status.")
    })
  }

Error codes

The error codes in ThingSmartFirmwareUpgradeStatusModel only apply to the new API methods for OTA updates.

Error code	Description	Remarks
5000	All device firmware versions are up to date.	-
5001	No firmware update found.	-
5002	For Bluetooth devices, only one device can be updated in the same task.	In most cases, this error code applies to Bluetooth LE devices, Tuya mesh sub-devices, and Bluetooth mesh sub-devices.
5003	Failed to download the firmware package by using the app.	-
5004	Failed to check whether signal strength detection is required.	-
5005	The signal strength level of the device does not meet firmware update requirements.	We recommend that you implement a UI interaction to ask users whether to continue the update. The update might fail if it is continued. You can call - confirmWarningUpgradeTask: to continue or cancel the update.
5006	Failed to connect to the device.	In most cases, this error code applies to Bluetooth LE devices, Tuya mesh sub-devices, and Bluetooth mesh sub-devices.
5007	A timeout error has occurred while unbinding the Bluetooth LE device from the gateway.	-
5009	The MD5 check failed while downloading firmware by using the app.	-
5010	Failed to send the firmware by using the app.	In most cases, this error code applies to Bluetooth LE devices, Tuya mesh sub-devices, and Bluetooth mesh sub-devices.
5012	The device is offline.	-
5013	The verification before the update failed.	-
5014	The Bluetooth feature is not enabled on the mobile phone.	-
5015	Failed to get the list of available firmware updates.	-
5016	The device update timed out.	-
5017	Failed to call the API to initiate the OTA update.	The server returned an error when calling the API. A detailed error code can be obtained through error.localizedFailureReason. A detailed description can be obtained through error.localizedDescription.
5018	The device update failed, and the device reported the reason for the failure.	A detailed description can be obtained through error.localizedDescription.
5019	Bulk update detection timed out.	The call to the interface -batchCheckFirmwareWithDevId:success:failure: failed.
5020	The combo device is disconnected from the cloud.	-
5021	Bluetooth LE devices can only be updated via a gateway.	Some Bluetooth LE devices, due to their specific tagging, do not allow direct firmware updates via mobile phones.
5099	A global error code.	-