固件升级

更新时间:2024-07-04 06:03:37下载pdf

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

  • 从 v4.0.0 版本 SDK 开始,新增产品 ID(PID)级别升级固件。新的 开始升级 接口支持升级蓝牙设备的固件,并且可以选择多个固件升级。
  • 固件升级相关接口需要是 家庭创建者家庭管理员 才有权限使用,对于 家庭普通成员 仅能使用 家庭普通成员获取设备固件升级信息 中的接口进行获取固件升级信息。

升级流程

查询设备升级信息
下发模组升级指令
模组升级成功
下发设备控制模组升级指令
设备控制模组升级成功

初始化固件信息

接口说明

支持 Wi-Fi、Zigbee 网关、摄像头、蓝牙、Mesh 等设备。

IThingOTAService iThingOTAService = ThingHomeSdk.newOTAServiceInstance(devId);

参数说明

参数 说明
devId 设备 ID

查询升级信息

使用查询设备升级信息接口,可以查询到 ThingSmartFirmwareUpgradeModel 固件升级模型。其中:

  • type 属性表示固件通道类型。
  • upgradeMode 属性表示固件类别。
  • typeDesc 属性表示固件类型的描述。

固件类别

  • 普通固件:传统意义上的固件,用于升级设备内固件。

  • PID 版本升级固件:新引入产品版本的概念,不同版本间的数据能在指定功能模块范围内(即产品 schema 配置、面板配置、多语言配置、快捷控制配置)进行隔离配置。

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

固件通道类型

作为标识 普通固件 的固件通道,在查询固件列表时,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);

// 废弃,仅获取普通固件
IThingOta iThingOta = ThingOSDevice.newOTAInstance("devId");
iThingOta.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),fileSize 仅支持蓝牙设备
md5 String 固件的 MD5
controlType boolean
  • YES:升级中可控制
  • NO:升级中不可控制
waitingDesc String 固件等待设备唤醒的文案
upgradingDesc String 固件升级中的提示文案
canUpgrade boolean
  • null: 无前置校验规则,可直接升级
  • false: 有前置校验,不可升级,建议展示 remind 文案
  • true: 有前置校验,可以升级
remind String 前置校验规则未通过的提示文案
upgradeMode UpgradeModeEnum 固件类别,v4.0.0 开始支持
  • 0: 普通固件
  • 1: PID 版本升级固件

示例代码

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

            }

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

            }
        });

查询设备正在升级的固件状态

查询正在升级中的固件信息。

接口说明

void getUpgradeProgress(IOtaProgressCallback callback);

参数说明

参数 说明
IOtaProgressCallback 固件升级进度回调

ThingDevUpgradeStatusBean 数据模型

字段 类型 说明
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 版本升级,v4.0.0 开始支持
errorMsg String 失败信息

示例代码

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

            }

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

            }
        });

开始升级

接口说明

// 支持 普通固件 以及 PID 版本升级固件
// 在原本的基础上支持 单点蓝牙设备、蓝牙 Mesh 动态网关 等设备的升级
// 同一设备的多个固件可以依次升级
void startFirmwareUpgrade(List<UpgradeInfoBean> upgradeInfoBeans);

// 废弃,推荐使用 `startFirmwareUpgrade:` 发起升级
// 仅支持 普通固件,仅支持有 Wi-Fi 能力的设备 以及 Zigbee 子设备,无法支持单点蓝牙设备
// 仅能发起单个固件升级
// `type`:需要升级的类型,从设备升级信息接口 `getFirmwareUpgradeInfo` 获取
iThingOta.startOta();

参数说明

字段 类型 描述
upgradeInfoBeans List 从设备升级信息接口 getFirmwareUpgradeInfo 获取的固件列表
  • 通过设备升级信息接口 getFirmwareUpgradeInfo 获取的信息列表中会包含下列状态信息:

    • 无新版本(upgradeStatus: 0)

    • 有新版本(upgradeStatus: 1)

    • 在升级中(upgradeStatus: 2)

    • 等待设备唤醒(upgradeStatus: 5)

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

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

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

示例代码

iThingOTAService.startFirmwareUpgrade(upgradeInfoBeans);

继续升级

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

在升级 Wi-Fi 和双模类设备时,为保证升级通畅,通常会设置一个最低的信号强度。发起升级时,会检查设备的信号强度是否符合。不符合则会回调进度状态 error.code = 5005。此时,可以通过 UI 交互,让用户做选择。例如,弹窗提示:设备信号弱,升级可能失败,是否继续升级?

接口说明

void confirmWarningUpgradeTask(String devId, boolean isContinue);

参数说明

参数 说明
devId 设备 ID
isContinue 是否继续升级

特别注意

仅通过 startFirmwareUpgrade: 发起的升级,才有此流程。

示例代码

// isContinue 由用户选择是否继续
iThingOTAService.confirmWarningUpgradeTask(devId",isContinue);

取消升级

目前仅支持低功耗类型的设备,此类设备在发起升级后,可能处于待唤醒状态(upgradeStatus = 5)。通过此方法,可以取消待唤醒的升级任务。

接口说明

// 目前仅支持取消低功耗类型设备的升级任务。
void cancelFirmwareUpgrade(int otaType, IResultCallback callback);

参数说明

参数 说明
otaType 固件类型
callback 回调

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

示例代码

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

    }

    @Override
    public void onSuccess() {

    }
});

取消等待唤醒的升级

接口说明

对于低功耗类型的设备,在发起升级后,可能处于待唤醒状态(upgradeStatus = 5)。通过此方法,可以取消待唤醒的升级任务。

void cancelFirmwareUpgrade(IResultCallback callback);

参数说明

参数 描述
callback 接口结果回调

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

示例代码

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();
            }
        }
    });
}

回调监听

通过 startFirmwareUpgrade: 发起的升级,推荐使用 void registerDevOTAListener(IDevOTAListener listener); 注册回调。此回调包含 状态变化、进度更新、失败原因。其他废弃回调方法,也依然会回调。为了防止重复的回调监听,建议将相关逻辑迁移至此回调。

示例代码

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

    }
});

自动保持最新版本

部分设备支持自动保持最新版本,通过 DeviceBean - isSupportAutoUpgrade 来判断设备是否支持该功能。

接口说明

//获取开关状态
void getAutoUpgradeSwitchState(IThingDataCallback<Integer> callback);
//修改开关状态
void changeAutoUpgradeSwitchState(int state, IResultCallback callback);

参数说明

参数 描述
state 功能状态:
  • 0:关闭
  • 1:开启
callback 接口结果回调

示例代码

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();
            }
        }
    });
}

家庭普通成员获取设备固件升级信息

此接口从 5.1.0 版本 SDK 开始提供。

接口说明

void memberCheckFirmwareStatus(IFirmwareInfoCallback callback);

参数说明

参数 说明
callback 回调

DeviceFirmwareInfo 数据模型

字段 类型 说明
type int 固件通道类型
upgradeStatus int
  • 0:无新版本
  • 1:有新版本
  • 2:在升级中
  • 5:等待设备唤醒
version String 新版本使用的固件版本
upgradeText String 固件升级信息

示例代码

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();
            }
        }
    });
}

错误码

ThingDevUpgradeStatusBean 中的错误码,仅在通过新升级接口时可用。

错误码 说明 备注
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 可升级固件列表接口请求失败 -
5018 设备升级中失败,设备上报失败原因 详细描述通过 getErrorMsg() 获取
5099 通用错误码 -
其他错误 调用发起 OTA 升级接口返回的错误码 服务器返回接口调用错误,详细描述通过 getErrorMsg() 获取