English
English
简体中文
Contact Us
Register
Log In

Firmware Updates

Last Updated on : 2022-10-31 12:19:40download

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

  1. Query device update information.
  2. Send a command to update the module.
  3. The module is updated.
  4. Send a command to update the device control module.
  5. The device control module is updated.

Starting from v3.35.5, you can update firmware that matches a specified product ID (PID). This new update feature supports Bluetooth devices, and multiple firmware versions can be selected in the same update task.

Get firmware update information

Returns the device update information. The firmware update model TuyaSmartFirmwareUpgradeModel provides the following properties:

  • 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 TuyaSmartFirmwareUpgradeModel include the following valid values:

  • Generic firmware update: The field value is 0. This is the traditional mode to update device firmware.

  • Update PID-specific firmware: The field value is 1. 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.

    The new API methods are required to trigger and implement PID-specific firmware update.

Firmware update channel types

For the generic firmware update mode, when you query a list of firmware updates, the type field of TuyaSmartFirmwareUpgradeModel indicates the type of firmware update channel and typeDesc provides the description of each channel.

The following table lists descriptions of type for 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 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

// Returns firmware information required by generic update and PID-specific update.
- (void)checkFirmwareUpgrade:(void (^)(NSArray<TuyaSmartFirmwareUpgradeModel *> *firmwares))success failure:(nullable TYFailureError)failure;

// (Deprecated) Returns only the firmware information required by generic update.
- (void)getFirmwareUpgradeInfo:(nullable void (^)(NSArray <TuyaSmartFirmwareUpgradeModel *> *upgradeModelList))success failure:(nullable TYFailureError)failure;

Parameters

Parameter Description
success The success callback. A list of firmware update information is returned.
failure The failure callback.

Data model of TuyaSmartFirmwareUpgradeModel

Field Type Description
desc NSString The description of the update.
type NSInteger The description of the device type.
typeDesc NSString The description of a firmeware update channel.
upgradeStatus NSInteger
  • 0: no update available
  • 1: update available
  • 2: updating
  • 5: wait for the device to wake up
version NSString The target firmware version.
currentVersion NSString The current firmware version.
devType NSInteger
  • 0: generic type of device
  • 1: low-power device
upgradeType NSInteger
  • 0: app notification of update
  • 2: forced app update
  • 3: check for update
url NSString The URL at which the firmware update package of the Bluetooth device can be downloaded.
fileSize NSString The size of the firmware update package. Unit: bytes.
md5 NSString The MD5 (Message-Digest algorithm 5) hash value of the firmware.
controlType BOOL
  • YES: controllable during the update
  • NO: non-controllable during the update
waitingDesc NSString The description of waiting for the device to wake up.
upgradingDesc NSString The description of the firmware update in progress.
canUpgrade NSNumber
  • nil: runs the update task without a pre-validation.
  • 0: pre-validation failed and update is not allowed.
  • 1: pre-validation is passed and update is allowed.
remind NSString The description of a failed pre-validation.
upgradeMode TuyaSmartDeviceUpgradeMode
  • 0: generic firmware update
  • 1: PID-specific firmware update

Example

ObjC:

- (void)getFirmwareUpgradeInfo {
	// self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];

	[self.device checkFirmwareUpgrade:^(NSArray<TuyaSmartFirmwareUpgradeModel *> *upgradeModelList) {
		NSLog(@"getFirmwareUpgradeInfo success");
	} failure:^(NSError *error) {
		NSLog(@"getFirmwareUpgradeInfo failure: %@", error);
	}];
}

Swift:

func getFirmwareUpgradeInfo() {
    device?.checkFirmwareUpgrade({ (upgradeModelList) in
        print("getFirmwareUpgradeInfo success")
    }, failure: { (error) in
        if let e = error {
            print("getFirmwareUpgradeInfo failure: \(e)")
        }
    })
}

Query status of firmware being updated

Returns the information about the firmware being updated. If no firmware is being updated, a failure is returned.

API description

- (void)getFirmwareUpgradingStatus:(void (^)(TuyaSmartFirmwareUpgradeStatusModel *status))success failure:(nullable TYFailureError)failure

Parameters

Parameter Description
success The success callback. An update status model is returned.
failure The failure callback. An error message is returned to indicate that the device is not being updated or the API request failed.

Data model of TuyaSmartFirmwareUpgradeStatusModel

Field Type Description
upgradeStatus TuyaSmartDeviceUpgradeStatus The update status. Valid values:
  • 2: updating
  • 3: updated successfully
  • 4: update failed
  • 5: wait for the device to wake up
  • 6: firmware downloaded to the device
  • 7: update timeout
  • 100: the app is preparing, for example, connecting to a Bluetooth device, or downloading the firmware package
statusText NSString The description of the firmware status.
statusTitle NSString The title of the firmware status.
progress NSInteger The update progress. In certain conditions, the value might be less than 0. If any, ignore this type of value.
type NSInteger The type of firmware update channel. The value is used when users confirm the update.
upgradeMode TuyaSmartDeviceUpgradeMode
  • 0: generic firmware update
  • 1: PID-specific firmware update, available starting from v3.35.5
error NSError The error message.

Example

ObjC:

- (void)getFirmwareUpgradeInfo {
	// self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];

	[self.device getFirmwareUpgradingStatus:^(TuyaSmartFirmwareUpgradeStatusModel *status) {
		NSLog(@"getFirmwareUpgradingStatus success");
	} failure:^(NSError *error) {
		NSLog(@"getFirmwareUpgradingStatus failure: %@", error);
	}];
}

Swift:

func getFirmwareUpgradeInfo() {
    device?.getFirmwareUpgradingStatus({ (status) in
        print("getFirmwareUpgradingStatus success")
    }, failure: { (error) in
        if let e = error {
            print("getFirmwareUpgradingStatus failure: \(e)")
        }
    })
}

Start update

API description

// Both generic update and PID-specific update are supported.
// Based on the original update capabilities, Bluetooth LE devices and Bluetooth mesh dynamic gateways are also supported.
// Multiple firmware versions can be sequentially updated for the same device.
- (void)startFirmwareUpgrade:(NSArray<TuyaSmartFirmwareUpgradeModel *> *)firmwares
  
// Deprecated. `- startFirmwareUpgrade:` is recommended to initiate an update.
// Only generic firmware update is supported. Only Wi-Fi devices and Zigbee sub-devices are supported. Bluetooth LE devices are not supported.
// Only a single firmware update task can be initiated.
// `type`: the type of update. You can call `getFirmwareUpgradeInfo` to get the value.
- (void)upgradeFirmware:(NSInteger)type success:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

Parameters

  • -startFirmwareUpgrade:
Parameter Description
firmwares You can call getFirmwareUpgradeInfo to get a list of firmware versions.
success The success callback.
failure The failure callback.
  • -upgradeFirmware:success:failure:
Parameter Description
type The type of update. You can call getFirmwareUpgradeInfo to get the value.
success The success callback.
failure The failure callback.
  1. The list returned by getFirmwareUpgradeInfo includes the following status information:

    • No new version (upgradeStatus: 0)
    • New version available (upgradeStatus: 1)
    • Updating (upgradeStatus: 2)
    • Wait for the device to wake up (upgradeStatus: 5)

    The status information is displayed to indicate the update status. An update can be initiated only when a new version is available (upgradeStatus: 1). You need to implement the features to filter and display the status information on your own.

  2. Certain devices require a pre-validation before an update. Call getFirmwareUpgradeInfo to get a list of firmware information. Check the value of canUpgrade in the object of the update information model TuyaSmartFirmwareUpgradeModel.

    Value result Value
    Pre-validation is not required and update is allowed. canUpgrade == nil
    Pre-validation is required and failed, so update is not allowed. canUpgrade ! = nil && canUpgrade.integerValue == 0
    Pre-validation is required and passed, so update is allowed. canUpgrade ! = nil && canUpgrade.integerValue == 1

    If a pre-validation is required but not passed, an update is not allowed. Therefore, remind can be used to return the description that an update is not allowed.

Example

ObjC:

- (void)upgradeFirmwareNew {
	// self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
	
	// `firmwares`: the list of firmware information returned by `getFirmwareUpgradeInfo`.
  // Note that the firmware versions that do not meet the preceding rules must be filtered out.
	[self.device startFirmwareUpgrade:firmwares];
}

Swift:

func upgradeFirmware() {
	  // `firmwares`: the list of firmware information returned by `getFirmwareUpgradeInfo`.
	  // Note that the firmware versions that do not meet the preceding rules must be filtered out.
    device?.startFirmwareUpgrade(firmwares);
}

Continue with update

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

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 = TYOTAErrorCodeSignalStrengthNotSatisfy. 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

- (void)confirmWarningUpgradeTask:(BOOL)isContinue;

Parameters

Parameter Description
isContinue Indicates whether to continue the update task.

This process applies to only the update that is initiated by -startFirmwareUpgrade:.

Example

ObjC:

- (void)continueFirmware {
	// `isContinue`: asks users whether to continue the update.
	[self.device confirmWarningUpgradeTask:isContinue];
}

Swift:

func continueFirmware() {
    // `isContinue`: asks users whether to continue the update.
    device?.confirmWarningUpgradeTask(isContinue)
}

Cancel update

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


API description

// Currently, an update task can be canceled only for low-power devices.
- (void)cancelFirmwareUpgrade:(TYSuccessHandler)success
                      failure:(nullable TYFailureError)failure;

// Deprecated. `-cancelFirmwareUpgrade:failure:` is recommended.
// `type`: the type of update. You can call `getFirmwareUpgradeInfo` to get the value.
- (void)cancelUpgradeFirmware:(NSInteger)type success:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

Parameters

Parameter Description
success The success callback.
failure The failure callback.

This API method applies only in the status of waiting the device to wake up. upgradeStatus is 5 to indicate this status.

Example

ObjC:

- (void)cancelFirmware {
	// self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
	// `type`: the type of update. You can call `getFirmwareUpgradeInfo` to get the value.
	// TuyaSmartFirmwareUpgradeModel - type
    // This API method applies only in the status of waiting the device to wake up. `upgradeStatus` is `5` to indicate this status.

	[self.device cancelFirmwareUpgrade:^{
		NSLog(@"cancel success");
	} failure:^(NSError *error) {
		NSLog(@"cancel failure: %@", error);
	}];
}

Swift:

func cancelFirmware() {
    // This API method applies only in the status of waiting the device to wake up. `upgradeStatus` is `5` to indicate this status.
    device?.cancelFirmwareUpgrade(success: {
        print("cancel success")
    }, failure: { (error) in
        if let e = error {
            print("cancel failure: \(e)")
        }
    })
}

Listen for callback

For the update initiated by -startFirmwareUpgrade:, we recommend that you use -device:otaUpdateStatusChanged: to register the callback. This callback includes the status changes, progress, and failure reason. Other deprecated callback methods can still be executed. To prevent repeated callback listeners, we recommend that you port respective logic to this callback.

Example

ObjC:

- (void)device:(TuyaSmartDevice *)device otaUpdateStatusChanged:(TuyaSmartFirmwareUpgradeStatusModel *)statusModel {
		// The progress of the firmware update.
		// Recommended for use with `-startFirmwareUpgrade:`
}

- (void)device:(TuyaSmartDevice *)device firmwareUpgradeStatusModel:(TuyaSmartFirmwareUpgradeStatusModel *)upgradeStatusModel {
    // The callback for the device update status.
    // Recommended for use with `-upgradeFirmware:success:failure:`.
}

- (void)deviceFirmwareUpgradeSuccess:(TuyaSmartDevice *)device type:(NSInteger)type {
    // The firmware is updated. Deprecated. `- device:firmwareUpgradeStatusModel:` is recommended.
}

- (void)deviceFirmwareUpgradeFailure:(TuyaSmartDevice *)device type:(NSInteger)type {
    // Failed to update the firmware. Deprecated. `- device:firmwareUpgradeStatusModel:` is recommended.
}

- (void)device:(TuyaSmartDevice *)device firmwareUpgradeProgress:(NSInteger)type progress:(double)progress {
    // The progress of the firmware update.
    // Recommended for use with `-upgradeFirmware:success:failure:`.
}

Swift:

func device(_ device: TuyaSmartDevice, firmwareUpgradeStatusModel upgradeStatusModel: TuyaSmartFirmwareUpgradeStatusModel) {
    // The callback of the device update status.
}

func deviceFirmwareUpgradeSuccess(_ device: TuyaSmartDevice!, type: Int) {
    // The firmware is updated. This API method will be deprecated soon. `device(_:, firmwareUpgradeStatusModel:)` is recommended.
}

func deviceFirmwareUpgradeFailure(_ device: TuyaSmartDevice!, type: Int) {
    // Failed to update the firmware. This API method will be deprecated soon. `device(_:, firmwareUpgradeStatusModel:)` is recommended.
}

func device(_ device: TuyaSmartDevice!, firmwareUpgradeProgress type: Int, progress: Double) {
    // The progress of the firmware update.
}

Automatically update to the latest version

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

API description

// Checks whether this feature is enabled.
- (void)getAutoUpgradeSwitchInfoWithSuccess:(nullable TYSuccessID)success
                                    failure:(nullable TYFailureError)failure;

// Saves the switch states.
- (void)saveUpgradeInfoWithSwitchValue:(NSInteger)switchValue
                               success:(nullable TYSuccessHandler)success
                               failure:(nullable TYFailureError)failure;

Parameters

Parameter Description
switchValue The status of the feature. Valid values:
  • 0: disabled
  • 1: enabled
success The success callback.
failure The failure callback.

Example

ObjC:

- (void)getAutoUpgradeSwitchInfo {
    // self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
		// Note that `TuyaSmartDeviceModel - supportAuto` must be used to check whether the device supports this feature first.

    [self.device getAutoUpgradeSwitchInfoWithSuccess:^(NSNumber *status) {
        // `0`: disabled. `1`: enabled. This feature is disabled in this example.
        NSLog(@"current switch status: %@", status);
    } failure:^(NSError *error) {
        NSLog(@"get current switch status fail. %@", error);
    }];
}

- (void)saveAutoUpgradeSwitchInfo {
		// self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
    // Note that `TuyaSmartDeviceModel - supportAuto` must be used to check whether the device supports this feature first.

		NSInteger status = 0; // `0`: disabled. `1`: enabled. This feature is disabled in this example.
		[self.device saveUpgradeInfoWithSwitchValue:status success:^{
        NSLog(@"save auto switch status success.");
    } failure:^(NSError *error) {
        NSLog(@"save auto switch status fail. %@", error);
    }];
}

Swift:

func getAutoUpgradeSwitchInfo() {
    // Note that `TuyaSmartDeviceModel - supportAuto` must be used to check whether the device supports this feature first.
    device?.getAutoUpgradeSwitchInfo(success: { status in
        // `0`: disabled. `1`: enabled.
        if let value = status {
            print("get current status: \(value)")
        }
    }, failure: { error in
        if let e = error {
            print("get status failure: \(e)")
        }
    })
}

func saveAutoUpgradeSwitchInfo() {
    // Note that `TuyaSmartDeviceModel - supportAuto` must be used to check whether the device supports this feature first.
    let status = 0 // `0`: disabled. `1`: enabled. This feature is disabled in this example.
    device?.saveUpgradeInfo(withSwitchValue: 0, success: {
        print("save success")
    }, failure: { error in
        if let e = error {
            print("success failure: \(e)")
        }
    })
}

Error codes

The error codes in TuyaSmartFirmwareUpgradeStatusModel only apply to the API methods for PID-specific firmware update.

Error code Description Remarks
5000 All device firmware versions are up to date and not need to be updated. N/A
5001 No firmware update found. N/A
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. N/A
5004 Failed to check whether the signal strength detection is required. N/A
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. N/A
5009 The MD5 check failed while downloading firmware by using the app. N/A
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. N/A
5013 The pre-validation prior to the update is not passed. N/A
5014 The Bluetooth feature is not enabled on the mobile phone. N/A
5015 Failed to get the list of available firmware updates. N/A
5099 A global error code. N/A