固件升级

更新时间:2023-03-09 08:08:12

固件升级是指把新的固件写入芯片中,代替原有的固件的过程。随着市场变化、开发方案升级等原因,涂鸦会定期进行固件更新。同时,涂鸦会根据原厂芯片迭代等情况,对部分旧版本进行停用。另外,设备本身也可以进行功能更新迭代,从而升级固件。

升级流程

  1. 查询设备升级信息。
  2. 下发模组升级指令。
  3. 模组升级成功。
  4. 下发设备控制模组升级指令。
  5. 设备控制模组升级成功。

从 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 配置、面板配置、多语言配置、快捷控制配置)进行隔离配置。

    需要使用新接口获取固件列表、发起升级。

固件通道类型

作为标识 普通固件 的固件通道,在查询固件列表时,UpgradeInfoBeantype 字段为固件通道类型,可以通过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
  • 0:无新版本
  • 1:有新版本
  • 2:在升级中
  • 5:等待设备唤醒
version String 新版本使用的固件版本
currentVersion String 当前的固件版本
devType int
  • 0:普通设备
  • 1:低功耗类型设备
upgradeType int
  • 0:App 提醒升级
  • 2:App 强制升级
  • 3:检测升级
url String 蓝牙设备的升级固件包下载 URL
fileSize String 固件包的大小,单位:字节 (byte)
md5 String 固件的 MD5
controlType boolean
  • YES:升级中可控制
  • NO:升级中不可控制
waitingDesc String 固件等待设备唤醒的文案
upgradingDesc String 固件升级中的提示文案
canUpgrade boolean
  • null: 无前置校验规则,可直接升级
  • false: 有前置校验,不可升级,建议展示 remind 文案
  • true: 有前置校验,可以升级
remind String 前置校验规则未通过的提示文案
upgradeMode UpgradeModeEnum 固件类别,v3.35.5 开始支持
  • 0: 普通固件
  • 1: PID 版本升级固件

实例代码

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 升级状态枚举
  • 2:在升级中
  • 3:升级成功
  • 4:升级失败
  • 5:等待设备唤醒
  • 6:设备已下载固件
  • 7:升级超时
  • 100:App 正在准备中(比如:正在连接蓝牙设备、App 正在下载固件包)
upgradeModeEnum UpgradeModeEnum
  • 0:普通固件
  • 1:PID 版本升级,v3.35.5 开始支持
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 获取的固件列表
  1. 通过设备升级信息接口 getFirmwareUpgradeInfo 获取的信息列表中会包含下列状态信息:

    • 无新版本 (upgradeStatus: 0)
    • 有新版本 (upgradeStatus: 1)
    • 在升级中 (upgradeStatus: 2)
    • 等待设备唤醒 (upgradeStatus: 5)

    上述状态信息用于展示升级相关状态。仅 有新版本 (upgradeStatus: 1) 状态时,可以发起升级。请在使用做好相关过滤和状态展示。

  2. 部分设备有前置校验限制。通过 getFirmwareUpgradeInfo 获取的信息列表,采用其中任何一个升级信息模型 UpgradeInfoBean 对象中的 canUpgrade 进行判断。

    若有前置校验,且校验未通过,无法升级的,可以通过 remind 获取不可升级的说明文案。

实例代码

iTuyaOTAService.startFirmwareUpgrade(upgradeInfoBeans);

继续升级

目前仅支持在升级中收到进度回调时,error.code5005 的场景。

在升级 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 回调

取消待唤醒的升级仅适用于 upgradeStatus5(等待设备唤醒)的设备。

示例代码

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 接口结果回调

取消待唤醒的升级仅适用于 upgradeStatus5(等待设备唤醒)的设备。

示例代码

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 功能状态:
  • 0:关闭
  • 1:开启
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 通用错误码