Last Updated on : 2023-03-09 08:17:39
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.
Starting from v4.0.0, 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.
API description
Initializes firmware for devices, such as Wi-Fi devices, Zigbee gateways, cameras, Bluetooth, and mesh devices.
ITuyaOTAService newOTAServiceInstance(String devId);
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
Example
ITuyaDevicePlugin deviceService = PluginManager.service(ITuyaDevicePlugin.class);
if (mDeviceService == null) return null;
ITuyaOTAService iTuyaOTAService= deviceService.newOTAServiceInstance(devId);
Returns the device update information. The firmware update model TuyaSmartFirmwareUpgradeModel
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 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 UpgradeInfoBean
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 getFirmwareUpgradeInfo(IGetOtaInfoCallback callback);
// (Deprecated) Returns only the firmware information required by generic update.
ITuyaOta iTuyaOta = TuyaOSDevice.newOTAInstance("devId");
iTuyaOta.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 |
|
version | String | The target firmware version. |
currentVersion | String | The current firmware version. |
devType | int |
|
upgradeType | int |
|
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. |
md5 | String | The MD5 (Message-Digest algorithm 5) hash value of the firmware. |
controlType | boolean |
|
waitingDesc | String | The description of waiting for the device to wake up. |
upgradingDesc | String | The description of the firmware update in progress. |
canUpgrade | boolean |
|
remind | String | The description of a failed pre-validation. |
upgradeMode | UpgradeModeEnum | The type of firmware update
|
Example
iTuyaOTAService.getDeviceLocalFirmwareInfo(new IGetOtaInfoCallback() {
@Override
public void onSuccess(List<UpgradeInfoBean> upgradeInfoBeans) {
}
@Override
public void onFailure(String code, String error) {
}
});
Returns the 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 TuyaDevUpgradeStatusBean
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:
|
upgradeModeEnum | UpgradeModeEnum |
|
errorMsg | String | The error message. |
Example
iTuyaOTAService.getUpgradeProgress(new IOtaProgressCallback() {
@Override
public void onSuccess(TuyaDevUpgradeStatusBean progress) {
}
@Override
public void onFailure(String code, String error) {
}
});
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.
iTuyaOta.startOta();
Parameters
Field | Type | Description |
---|---|---|
upgradeInfoBeans | List |
You can call getFirmwareUpgradeInfo to get a list of firmware version. |
The list returned by getFirmwareUpgradeInfo
includes the following status information:
upgradeStatus: 0
)upgradeStatus: 1
)upgradeStatus: 2
)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
iTuyaOTAService.startFirmwareUpgrade(upgradeInfoBeans);
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.
iTuyaOTAService.confirmWarningUpgradeTask(devId",isContinue);
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 waiting the device to wake up. upgradeStatus
is 5
to indicate this status.
Example
iTuyaOTAService.cancelFirmwareUpgrade(otaType, new IResultCallback() {
@Override
public void onError(String code, String error) {
}
@Override
public void onSuccess() {
}
});
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 cancelUpgradeFirmware(int type, IResultCallback callback);
Parameters
Parameter | Description |
---|---|
type | The type of device to be updated. For more information, see the type field of UpgradeInfoBean . |
callback | The callback. |
This API method applies only in the status of waiting the device to wake up. upgradeStatus
is 5
to indicate this status.
Example
final ITuyaOta mTuyaOta = TuyaOSDevice.newOTAInstance(devId);
public void cancelDeviceWakeup(int type, final IResultCallback callback) {
mTuyaOta.cancelUpgradeFirmware(type, 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();
}
}
});
}
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
iTuyaOTAService.registerDevOTAListener(new IDevOTAListener() {
@Override
public void firmwareUpgradeStatus(TuyaDevUpgradeStatusBean upgradeStatusBean) {
}
});
Certain devices support 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(ITuyaDataCallback<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:
|
callback | The callback. |
Example
public void getAutoUpgradeStatus(final ITuyaDataCallback<Integer> callback) {
iTuyaOTAService.getAutoUpgradeSwitchState(new ITuyaDataCallback<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) {
iTuyaOTAService.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();
}
}
});
}
The error codes in TuyaDevUpgradeStatusBean
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. | |
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 the 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 pre-validation prior to the update is not passed. | |
5014 | The Bluetooth feature is not enabled on the mobile phone. | |
5015 | Failed to get the list of available firmware updates. | |
5099 | A global error code. |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback