更新时间:2023-03-09 08:17:39
固件升级是指把新的固件写入芯片中,代替原有的固件的过程。随着市场变化、开发方案升级等原因,涂鸦会定期进行固件更新。同时,涂鸦会根据原厂芯片迭代等情况,对部分旧版本进行停用。另外,设备本身也可以进行功能更新迭代,从而升级固件。
从 v4.0.0 开始,新增 PID 版本升级固件。新的开始升级接口支持蓝牙设备的固件升级,并且可以选择多个固件升级。
接口说明
支持 Wi-Fi、Zigbee 网关、摄像头、蓝牙、Mesh 等设备。
ITuyaDevicePlugin deviceService = PluginManager.service(ITuyaDevicePlugin.class);
if (mDeviceService == null) return null;
ITuyaOTAService iTuyaOTAService= deviceService.newOTAServiceInstance(devId);
参数说明
参数 | 说明 |
---|---|
devId | 设备 ID |
实例代码
ITuyaDevicePlugin deviceService = PluginManager.service(ITuyaDevicePlugin.class);
if (mDeviceService == null) return null;
ITuyaOTAService iTuyaOTAService= deviceService.newOTAServiceInstance(devId);
使用查询设备升级信息接口,可以查询到 TuyaSmartFirmwareUpgradeModel
固件升级模型。其中:
type
属性表示固件通道类型。upgradeMode
属性表示固件类别。typeDesc
属性表示固件类型的描述。固件类别
普通固件:传统意义上的固件,用于升级设备内固件。
PID 版本升级固件:新引入产品版本的概念,不同版本间的数据能在指定功能模块范围内(即产品 schema 配置、面板配置、多语言配置、快捷控制配置)进行隔离配置。
需要使用新接口获取固件列表、发起升级。
固件通道类型
作为标识 普通固件 的固件通道,在查询固件列表时,UpgradeInfoBean
中 type
字段为固件通道类型,可以通过typeDesc
来获取到具体的描述。
通常通道 type
含义如下表所示,推荐根据实际情况使用模型返回的 typeDesc
来标识实际固件描述。
普通固件通道 type | 固件通道含义 |
---|---|
0 | 主联网模块、Wi-Fi 模块、蓝牙模块 |
1 | 蓝牙模块 |
2 | GPRS 模块 |
3 | Zigbee 模块 |
5 | 433 模块 |
6 | NB-IoT 模块 |
9 | MCU 模块 |
10 ~ 19 | 扩展通道 |
接口说明
// 获取 普通固件 及 PID 版本升级固件
void getFirmwareUpgradeInfo(IGetOtaInfoCallback callback);
// 废弃,仅获取普通固件
ITuyaOta iTuyaOta = TuyaOSDevice.newOTAInstance("devId");
iTuyaOta.getOtaInfo(IGetOtaInfoCallback callback);
参数说明
参数 | 说明 |
---|---|
IGetOtaInfoCallback | 设备的固件升级信息回调 |
UpgradeInfoBean
数据模型
字段 | 类型 | 说明 |
---|---|---|
desc | String | 升级文案 |
type | NSInteger | 固件通道类型,普通固件使用 |
typeDesc | NSString | 固件通道描述 |
upgradeStatus | int |
|
version | String | 新版本使用的固件版本 |
currentVersion | String | 当前的固件版本 |
devType | int |
|
upgradeType | int |
|
url | String | 蓝牙设备的升级固件包下载 URL |
fileSize | String | 固件包的大小,单位:字节 (byte) |
md5 | String | 固件的 MD5 |
controlType | boolean |
|
waitingDesc | String | 固件等待设备唤醒的文案 |
upgradingDesc | String | 固件升级中的提示文案 |
canUpgrade | boolean |
|
remind | String | 前置校验规则未通过的提示文案 |
upgradeMode | UpgradeModeEnum | 固件类别,v3.35.5 开始支持
|
实例代码
iTuyaOTAService.getDeviceLocalFirmwareInfo(new IGetOtaInfoCallback() {
@Override
public void onSuccess(List<UpgradeInfoBean> upgradeInfoBeans) {
}
@Override
public void onFailure(String code, String error) {
}
});
查询正在升级中的固件信息。
接口说明
void getUpgradeProgress(IOtaProgressCallback callback);
参数说明
参数 | 说明 |
---|---|
IOtaProgressCallback | 固件升级进度回调 |
TuyaDevUpgradeStatusBean
数据模型
字段 | 类型 | 说明 |
---|---|---|
devId | String | 设备 ID |
firmwareType | int | 固件类型 |
statusText | String | 状态描述 |
statusTitle | String | 状态标题 |
progress | int | 进度,部分情况下,参数值可能小于 0,请忽略此种小于 0 的进度 |
status | DevUpgradeStatusEnum | 升级状态枚举
|
upgradeModeEnum | UpgradeModeEnum |
|
errorMsg | String | 失败信息 |
实例代码
iTuyaOTAService.getUpgradeProgress(new IOtaProgressCallback() {
@Override
public void onSuccess(TuyaDevUpgradeStatusBean progress) {
}
@Override
public void onFailure(String code, String error) {
}
});
接口说明
// 支持 普通固件 以及 PID 版本升级固件
// 在原本的基础上支持 单点蓝牙设备、蓝牙 Mesh 动态网关 等设备的升级
// 同一设备的多个固件可以依次升级
void startFirmwareUpgrade(List<UpgradeInfoBean> upgradeInfoBeans);
// 废弃,推荐使用 `startFirmwareUpgrade:` 发起升级
// 仅支持 普通固件,仅支持有 Wi-Fi 能力的设备 以及 Zigbee 子设备,无法支持单点蓝牙设备
// 仅能发起单个固件升级
// `type`:需要升级的类型,从设备升级信息接口 `getFirmwareUpgradeInfo` 获取
iTuyaOta.startOta();
参数说明
字段 | 类型 | 描述 |
---|---|---|
upgradeInfoBeans | List |
从设备升级信息接口 getFirmwareUpgradeInfo 获取的固件列表 |
通过设备升级信息接口 getFirmwareUpgradeInfo
获取的信息列表中会包含下列状态信息:
上述状态信息用于展示升级相关状态。仅 有新版本 (upgradeStatus: 1) 状态时,可以发起升级。请在使用做好相关过滤和状态展示。
部分设备有前置校验限制。通过 getFirmwareUpgradeInfo
获取的信息列表,采用其中任何一个升级信息模型 UpgradeInfoBean
对象中的 canUpgrade
进行判断。
若有前置校验,且校验未通过,无法升级的,可以通过 remind
获取不可升级的说明文案。
实例代码
iTuyaOTAService.startFirmwareUpgrade(upgradeInfoBeans);
目前仅支持在升级中收到进度回调时,error.code
为 5005
的场景。
在升级 Wi-Fi 和双模类设备时,为保证升级通畅,通常会设置一个最低的信号强度当。发起升级时,会检查设备的信号强度是否符合。不符合则会回调进度状态 error.code = 5005
。此时,可以通过 UI 交互,让用户做选择。例如,弹窗提示:“设备信号弱,升级可能失败,是否继续升级?”
接口说明
void confirmWarningUpgradeTask(String devId, boolean isContinue);
参数说明
参数 | 说明 |
---|---|
devId | 设备 ID |
isContinue | 是否继续升级 |
特别注意
仅通过 startFirmwareUpgrade:
发起的升级,才有此流程。
示例代码
// isContinue 由用户选择是否继续
iTuyaOTAService.confirmWarningUpgradeTask(devId",isContinue);
目前仅支持低功耗类型的设备,此类设备在发起升级后,可能处于待唤醒状态(upgradeStatus == 5)。通过此方法,可以取消待唤醒的升级任务。
接口说明
// 目前仅支持取消低功耗类型设备的升级任务。
void cancelFirmwareUpgrade(int otaType, IResultCallback callback);
参数说明
参数 | 说明 |
---|---|
otaType | 固件类型 |
callback | 回调 |
取消待唤醒的升级仅适用于 upgradeStatus
为 5
(等待设备唤醒)的设备。
示例代码
iTuyaOTAService.cancelFirmwareUpgrade(otaType, new IResultCallback() {
@Override
public void onError(String code, String error) {
}
@Override
public void onSuccess() {
}
});
接口说明
对于低功耗类型的设备,在发起升级后,可能处于待唤醒状态 (upgradeStatus == 5
)。通过此方法,可以取消待唤醒的升级任务。
void cancelUpgradeFirmware(int type, IResultCallback callback);
参数说明
参数 | 描述 |
---|---|
type | 升级的设备类型,同 UpgradeInfoBean 中的 type 字段 |
callback | 接口结果回调 |
取消待唤醒的升级仅适用于 upgradeStatus
为 5
(等待设备唤醒)的设备。
示例代码
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();
}
}
});
}
通过 startFirmwareUpgrade:
发起的升级,推荐使用 void registerDevOTAListener(IDevOTAListener listener);
注册回调。此回调包含 状态变化、进度更新、失败原因。其他废弃回调方法,也依然会回调。为了防止重复的回调监听,建议将相关逻辑迁移至此回调。
示例代码
iTuyaOTAService.registerDevOTAListener(new IDevOTAListener() {
@Override
public void firmwareUpgradeStatus(TuyaDevUpgradeStatusBean upgradeStatusBean) {
}
});
部分设备支持自动保持最新版本,通过 DeviceBean - isSupportAutoUpgrade
来判断设备是否支持该功能。
接口说明
//获取开关状态
void getAutoUpgradeSwitchState(ITuyaDataCallback<Integer> callback);
//修改开关状态
void changeAutoUpgradeSwitchState(int state, IResultCallback callback);
参数说明
参数 | 描述 |
---|---|
state | 功能状态:
|
callback | 接口结果回调 |
示例代码
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();
}
}
});
}
TuyaDevUpgradeStatusBean
中的错误码,仅在通过新升级接口时可用。
错误码 | 说明 | 备注 |
---|---|---|
5000 | 设备所有固件已是最新,无需升级 | |
5001 | 未检查到固件 | |
5002 | 蓝牙类设备同时只能有一个设备在升级 | 通常为 蓝牙单点、涂鸦 Mesh 子设备、蓝牙 Mesh 子设备 |
5003 | App 下载固件包失败 | |
5004 | 获取是否需要信号强度检测失败 | |
5005 | 设备信号强度不满足升级条件 | 建议询问用户是否继续,继续可能会失败。可通过接口 - confirmWarningUpgradeTask: 继续 或者 取消 |
5006 | 连接设备失败 | 通常为 蓝牙单点、涂鸦 Mesh子设备、蓝牙 Mesh 子设备 |
5007 | 将蓝牙单点设备从网关下解绑超时 | |
5009 | App 下载固件 MD5 校验不通过 | |
5010 | App 发送固件失败 | 通常为 蓝牙单点、涂鸦 Mesh 子设备、蓝牙 Mesh 子设备 |
5012 | 设备不在线 | |
5013 | 升级前置校验不通过 | |
5014 | 手机蓝牙未打开 | |
5015 | 可升级固件列表接口请求失败 | |
5099 | 通用错误码 |
该内容对您有帮助吗?
是意见反馈该内容对您有帮助吗?
是意见反馈