Firmware Update

Firmware update is the process of writing new firmware to a chip to replace the current 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, a firmware update is also required.

Update process

Get firmware update information

This method returns the firmware update model ThingSmartFirmwareUpgradeModel. Valid values:

• upgradeMode: indicates the firmware update mode.
• type: indicates the firmware update channel type.
• typeDesc: indicates the description of the firmware type.

Firmware update modes

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

• Generic firmware update: Its value is 0. This is an ordinary update mode, used to update the firmware on the device.

• 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 get the firmware list and trigger a PID-specific firmware updates.

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	Meaning
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

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

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

Parameters

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

Data model of ThingSmartFirmwareUpgradeModel

Field	Type	Description
desc	NSString	The description of the update.
type	NSInteger	The type of firmware update channel, applying to generic firmware.
typeDesc	NSString	The description of the firmware update channel.
upgradeStatus	NSInteger	0: No update available 1: An 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: Ordinary device 1: Low power device
upgradeType	NSInteger	0: Update notification 2: Forced update 3: Check for update
url	NSString	The URL to download a Bluetooth firmware update.
fileSize	NSString	The size of the firmware update, in bytes. This fileSize field applies to Bluetooth devices only.
md5	NSString	The MD5 (Message-Digest algorithm 5) hash value of the firmware.
controlType	BOOL	YES: The device can be controlled during the update. NO: The device cannot be controlled 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: No verification is required to start an update. 0: The update verification fails, with the update being denied. You can show remind to inform the user about the failure. 1: The update verification succeeds, with the update being accepted.
remind	NSString	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

Objective-C:

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

    [self.device checkFirmwareUpgrade:^(NSArray<ThingSmartFirmwareUpgradeModel *> *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 information about the firmware being updated. If no firmware is being updated, a failure is returned.

API description

- (void)getFirmwareUpgradingStatus:(void (^)(ThingSmartFirmwareUpgradeStatusModel *status))success failure:(nullable ThingFailureError)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 ThingSmartFirmwareUpgradeStatusModel

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 100: The app is preparing, for example, connecting to a Bluetooth device, or downloading the update
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	ThingSmartDeviceUpgradeMode	0: Generic firmware update 1: PID-specific firmware update, available starting from v3.35.5
error	NSError	The error message.

Sample code

Objective-C:

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

    [self.device getFirmwareUpgradingStatus:^(ThingSmartFirmwareUpgradeStatusModel *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<ThingSmartFirmwareUpgradeModel *> *)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 ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

Parameters

• -startFirmwareUpgrade:

  Parameter	Description
  firmwares	Call getFirmwareUpgradeInfo to get the information about the firmware update.
  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.

  The list returned by getFirmwareUpgradeInfo includes the following status information:

  • No update available (upgradeStatus: 0)

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

  • Certain devices require a pre-validation before an update. Call getFirmwareUpgradeInfo to get the firmware information. The canUpgrade in the update information model ThingSmartFirmwareUpgradeModel indicates whether the update can be installed.

    Verification result	Value
    No verification is required to start an update.	canUpgrade == nil
    Pre-validation is required and failed, so update is not allowed.	canUpgrade != nil && canUpgrade.integerValue == 0
    The update verification succeeds, with the update being accepted.	canUpgrade != nil && canUpgrade.integerValue == 1

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

Sample code

Objective-C:

- (void)upgradeFirmwareNew {
    // self.device = [ThingSmartDevice 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 error.code of ThingOTAErrorCodeSignalStrengthNotSatisfy is returned in the update progress callback.

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, error.code of ThingOTAErrorCodeSignalStrengthNotSatisfy will be returned in the callback. 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.

Sample code

Objective-C:

- (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 can cancel an update. After an update is initiated, a low power device may be in sleep mode (upgradeStatus: 5). This API method can be called to cancel the update task.

API description

// Currently, an update task can be canceled only for low-power devices.
- (void)cancelFirmwareUpgrade:(ThingSuccessHandler)success
                      failure:(nullable ThingFailureError)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 ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

- (void)cancelFirmware {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    // type: the type of update. You can call getFirmwareUpgradeInfo to get the value.
    // ThingSmartFirmwareUpgradeModel - type
    // This API method applies only in the status of waiting for 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 for 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

Sample code

Objective-C:

- (void)device:(ThingSmartDevice *)device otaUpdateStatusChanged:(ThingSmartFirmwareUpgradeStatusModel *)statusModel {
        // The callback for the status and progress of the firmware update.
        // Recommended for use with -startFirmwareUpgrade:
}

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

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

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

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

Swift:

func device(_ device: ThingSmartDevice, firmwareUpgradeStatusModel upgradeStatusModel: ThingSmartFirmwareUpgradeStatusModel) {
    // The callback for the device update status.
}
func deviceFirmwareUpgradeSuccess(_ device: ThingSmartDevice!, type: Int) {
    // The firmware is updated. This API method will be deprecated soon. device(_:, firmwareUpgradeStatusModel:) is recommended.
}
func deviceFirmwareUpgradeFailure(_ device: ThingSmartDevice!, type: Int) {
    / Failed to update the firmware. This API method will be deprecated soon. device(_:, firmwareUpgradeStatusModel:) is recommended.
}
func device(_ device: ThingSmartDevice!, firmwareUpgradeProgress type: Int, progress: Double) {
    // The progress of the firmware update.
}

Automatically update to the latest version

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

API description

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

// Saves the enabling states.
 - (void)saveUpgradeInfoWithSwitchValue:(NSInteger)switchValue
                               success:(nullable ThingSuccessHandler)success
                               failure:(nullable ThingFailureError)failure;

Parameters

Parameter	Description
switchValue	The status of the feature. Valid values: 0: Disable 1: Enable
success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

- (void)getAutoUpgradeSwitchInfo {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    // Note that ThingSmartDeviceModel - 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 = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    // Note that ThingSmartDeviceModel - 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 ThingSmartDeviceModel - 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 ThingSmartDeviceModel - 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)")
        }
    })
}

Common home members get update information

API description

- (void)memberCheckFirmwareStatus:(void (^)(NSArray<ThingSmartMemberCheckFirmwareInfo *> *infos))success
                          failure:(ThingFailureError)failure;

Parameters

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

Data model of ThingSmartMemberCheckFirmwareInfo

Field	Type	Description
type	NSInteger	Firmware update channel types
upgradeStatus	NSInteger	0: No update available 1: An update available 2: Updating 5: Wait for the device to wake up
version	NSString	The target firmware version.
upgradeText	NSString	The information about firmware update.

Sample code

Objective-C:

- (void)getAutoUpgradeSwitchInfo {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    [self.device memberCheckFirmwareStatus:^(NSArray<ThingSmartMemberCheckFirmwareInfo *> * _Nonnull infos) {
        NSLog(@"member check success");
    } failure:^(NSError *error) {
        NSLog(@"member check failure");
    }];
}

Swift:

func getAutoUpgradeSwitchInfo() {
    device?.memberCheckFirmwareStatus(success: { infos in
            print("member check success: \(infos)")
    }, failure: { error in
        if let e = error {
            print("member check failure: \(e)")
        }
    })
}

Error code

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

Error code	Description	Notes
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.	-
5099	Global error codes.	-