Firmware Update

Last Updated on : 2024-07-04 06:04:04download

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, a firmware update is also required.

  • Starting from v4.0.0, you can update firmware that matches a specified product ID (PID). The new API method for starting firmware update supports Bluetooth devices, and multiple firmware versions can be selected in the same update task.
  • Only home creators and home administrators are authorized to update firmware. Common home members can only get information about the firmware update based on the API method memberCheckFirmwareStatus.

Update process

Query device
update information
Send command
to update module
Module updated successfully
Send command to
update device control module
Device control module
updated successfully

Initialize firmware information

API description

Initializes firmware for devices, such as Wi-Fi devices, Zigbee gateways, cameras, Bluetooth devices, and Bluetooth mesh devices.

IThingOTAService iThingOTAService = ThingHomeSdk.newOTAServiceInstance(devId);

Parameters

Parameter Description
devId The device ID.

Get firmware update information

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

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

Firmware update modes

  • Generic firmware update: This is the traditional mode to update device firmware.

  • Update PID-specific firmware: 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

For the generic firmware update mode, when you query a list of firmware updates, the type field of UpgradeInfoBean indicates the type of firmware update channel and typeDesc describes each 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 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 getFirmwareUpgradeInfo(IGetOtaInfoCallback callback);

// (Deprecated) Returns only the firmware information required by generic update.
IThingOta iThingOta = ThingOSDevice.newOTAInstance("devId");
iThingOta.getOtaInfo(IGetOtaInfoCallback callback);

Parameters

Parameter Description
IGetOtaInfoCallback The callback for firmware update information.

Data model of UpgradeInfoBean

Field Type Description
desc String The description of the update.
type NSInteger The type of firmware update channel. The value is used for a generic firmware update.
typeDesc NSString The description of the firmware update channel.
upgradeStatus int
  • 0: no update available
  • 1: update available
  • 2: updating
  • 5: wait for the device to wake up
version String The target firmware version.
currentVersion String The current firmware version.
devType int
  • 0: generic type of device
  • 1: low-power device
upgradeType int
  • 0: app notification of update
  • 2: forced app update
  • 3: check for update
url String The URL at which the firmware update package of the Bluetooth device can be downloaded.
fileSize String The size of the firmware update package. Unit: bytes. FileSize only supports Bluetooth devices.
md5 String The MD5 (Message-Digest algorithm 5) hash value of the firmware.
controlType boolean
  • YES: controllable during the update
  • NO: non-controllable 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
  • null: Run the update task without a pre-validation.
  • false: 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.
  • true: Pre-validation is passed and update is allowed.
remind String The description of a failed pre-validation.
upgradeMode UpgradeModeEnum The type of firmware update. Valid values:
  • 0: generic firmware update
  • 1: PID-specific firmware update, available starting from v4.0.0

Example

iThingOTAService.getFirmwareUpgradeInfo(new IGetOtaInfoCallback() {
            @Override
            public void onSuccess(List<UpgradeInfoBean> upgradeInfoBeans) {

            }

            @Override
            public void onFailure(String code, String error) {

            }
        });

Query status of firmware being updated

Returns information about the firmware being updated.

API description

void getUpgradeProgress(IOtaProgressCallback callback);

Parameters

Parameter Description
IOtaProgressCallback The callback for the update progress.

Data model of ThingDevUpgradeStatusBean

Field Type Description
devId String The device ID.
firmwareType int The type of firmware.
statusText String The description of the firmware status.
statusTitle String The title of the firmware status.
progress int The update progress. In certain conditions, the value might be less than 0. If any, ignore this type of value.
status DevUpgradeStatusEnum 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
upgradeModeEnum UpgradeModeEnum
  • 0: generic firmware update
  • 1: PID-specific firmware update, available starting from v4.0.0
errorMsg String The error message.

Example

 iThingOTAService.getUpgradeProgress(new IOtaProgressCallback() {
            @Override
            public void onSuccess(ThingDevUpgradeStatusBean progress) {

            }

            @Override
            public void onFailure(String code, String error) {

            }
        });

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(List<UpgradeInfoBean> upgradeInfoBeans);

// 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.
iThingOta.startOta();

Parameters

Field Type Description
upgradeInfoBeans List You can call getFirmwareUpgradeInfo to get a list of firmware versions.
  • 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.

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

    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.

Example

iThingOTAService.startFirmwareUpgrade(upgradeInfoBeans);

Continue with 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

void confirmWarningUpgradeTask(String devId, boolean isContinue);

Parameters

Parameter Description
devId The device ID.
isContinue Indicates whether to continue the update task.

Things to note

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

Example

// isContinue: asks users whether to continue the update.
iThingOTAService.confirmWarningUpgradeTask(devId",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(int otaType, IResultCallback callback);

Parameters

Parameter Description
otaType The type of firmware.
callback The callback.

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

Example

iThingOTAService.cancelFirmwareUpgrade(otaType, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

Cancel update when waiting for device to wake up

API description

For low-power devices, after an update is initiated, 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.

void cancelFirmwareUpgrade(IResultCallback callback);

Parameters

Parameter Description
callback The callback.

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

Example

public void cancelDeviceWakeup(final IResultCallback callback) {
    iThingOTAService.cancelFirmwareUpgrade(new IResultCallback() {
        @Override
        public void onError(String code, String error) {
            if (callback != null) {
                callback.onError(code, error);
            }
        }

        @Override
        public void onSuccess() {
            if (callback != null) {
                callback.onSuccess();
            }
        }
    });
}

Listen for callback

For the update initiated by startFirmwareUpgrade:, we recommend that you use void registerDevOTAListener(IDevOTAListener listener); 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

iThingOTAService.registerDevOTAListener(new IDevOTAListener() {
    @Override
    public void firmwareUpgradeStatus(ThingDevUpgradeStatusBean upgradeStatusBean) {

    }
});

Automatically update to the latest version

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

API description

// Checks whether this feature is enabled.
void getAutoUpgradeSwitchState(IThingDataCallback<Integer> callback);
// Switches between the enabled or disabled states.
void changeAutoUpgradeSwitchState(int state, IResultCallback callback);

Parameters

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

Example

public void getAutoUpgradeStatus(final IThingDataCallback<Integer> callback) {
    iThingOTAService.getAutoUpgradeSwitchState(new IThingDataCallback<Integer>() {
        @Override
        public void onSuccess(Integer result) {
            if (callback != null) {
                callback.onSuccess(result);
            }
        }

        @Override
        public void onError(String errorCode, String errorMessage) {
            if (callback != null) {
                callback.onError(errorCode, errorMessage);
            }
        }
    });
}

public void switchAutoUpgradeStatus(int value, final IResultCallback callback) {
    iThingOTAService.changeAutoUpgradeSwitchState(value, new IResultCallback() {
        @Override
        public void onError(String code, String error) {
            if (callback != null) {
                callback.onError(code, error);
            }
        }

        @Override
        public void onSuccess() {
            if (callback != null) {
                callback.onSuccess();
            }
        }
    });
}

Common home members get information about firmware update

This API method is only applicable to apps developed based on App SDK v5.1.0 or later.

API description

void memberCheckFirmwareStatus(IFirmwareInfoCallback callback);

Parameters

Parameter Description
callback The callback.

Data model of DeviceFirmwareInfo

Field Type Description
type int The type of firmware update channel.
upgradeStatus int
  • 0: no update available
  • 1: update available
  • 2: updating
  • 5: wait for the device to wake up
version String The target firmware version.
upgradeText String The information about firmware update.

Example

public void memberCheckFirmwareStatus(int value, final IResultCallback callback) {
    iThingOTAService.memberCheckFirmwareStatus( new IFirmwareInfoCallback() {
        @Override
        public void onError(String code, String error) {
            if (callback != null) {
                callback.onFailure(code, error);
            }
        }

        @Override
        public void onSuccess(List<DeviceFirmwareInfo> firmwareInfo) {
            if (callback != null) {
                callback.onSuccess();
            }
        }
    });
}

Error codes

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

Error code Description Remarks
5000 All device firmware versions are up to date and do not need to be updated. None.
5001 No firmware update found. None.
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. None.
5004 Failed to check whether the signal strength detection is required. None.
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. None.
5009 The MD5 check failed while downloading firmware by using the app. None.
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. None.
5013 The pre-validation prior to the update is not passed. None.
5014 The Bluetooth feature is not enabled on the mobile phone. None.
5015 Failed to get the list of available firmware updates. None.
5018 Failed to update the device. The device reported the reason for the failure. You can get a detailed description through getErrorMsg().
5099 A global error code. None.
Other errors Failed to call the API to initiate an OTA update. The server returned an API call error. You can get a detailed description through getErrorMsg().