文档

设备OTA升级

更新时间:

本文介绍设备OTA升级的基本流程,OTA升级功能开发的接口说明及接入方法。

获取SDK

您可以下载物联网平台提供的Android Link SDK Demo

重要

下载本Demo默认您同意本软件许可协议

OTA升级基本流程

  1. 设备上报版本号。

  2. 设备订阅OTA升级相关Topic。

  3. 在物联网平台控制台的OTA升级页面配置OTA升级任务,可以按多维度指定要升级的设备。

  4. 成功订阅OTA升级相关Topic的设备在当前配置的OTA升级任务中,设备会收到一个推送信息,其中包括:

    • 可升级的版本号。

    • OTA升级包地址、大小、MD5。

  5. 设备下载OTA升级包,开始升级,并上报升级进度。

  6. 设备升级完成后,自动上报新的版本号。

OTA升级配置的操作流程,请参见OTA升级概述

使用限制

当前Android Link SDK的OTA升级过程中仅支持使用HTTPS协议下载升级包。

SDK接口说明

SDK中OTA升级相关接口说明,请参见接口IOta

SDK接入方法

具体代码实现,请参见SDK Demo中的OTAActivity.java

  1. 物联网平台控制台,配置OTA升级任务,获取OTA实例:

           mOta = LinkKit.getInstance().getOta()              
  2. 准备OTA升级任务,tryStartOta实现了当前版本上报,订阅Topic,当有OTA升级推送时,会通过IOta.STEP_RCVD_OTA回调。

    说明
    • 用户可以使用OTA对多个模块升级。默认的OTA任务的模块名是default或者为空。用户可以自定义不同的模块。

    • tryStartOta会上报默认模块的版本号。如果要在启动时上报自定义模块的版本号,可以对每个模块调用reportModuleVersion进行上报。

    • 用户可以在IOta.STEP_RCVD_OTA的回调结果中,查看OTA任务的模块名称和版本号。因此,在使用了多个自定义OTA模块的场景,也不需要重复调用tryStartOta。 

    • 在该回调中,用户返回true表示进行OTA升级,返回false表示拒绝此次OTA升级(设备重新上线或者主动请求OTA任务时,会再次下发该OTA任务)。

    mOta.tryStartOta(mConfig, new OtaListener(){
        public boolean onOtaProgress(int step, IOta.OtaResult otaResult) {
    
            //当前升级过程的状态值(错误码)。
            int code = otaResult.getErrorCode();
            if (code != IOta.NO_ERROR) {
                AppLog.e(TAG, "onOtaProgress error:" + code);
                // show tip for uses.
                return false;
            }
    
            Object data = otaResult.getData();
            switch (step) {
                case IOta.STEP_REPORT_VERSION:
                    // 通知用户已完成向服务端上报设备版本号。
                    break;
                case IOta.STEP_SUBSCRIBE:
                    // 通知用户已完成向服务端订阅OTA报文。
                    break;
                case IOta.STEP_RCVD_OTA:
                    // 通知用户当前OTA任务的版本号、模块信息、 MD5等信息。用户如果需要OTA升级,需要返回true;如果拒绝OTA升级,需要返回false(设备重新上线或者主动请求OTA任务时会再次下发该OTA任务)。
                    AppLog.d(TAG, "STEP_RCVD_OTA");
                    otaInfo = (OtaInfo) otaResult.getData();
                    AppLog.d(TAG, "STEP_RCVD_OTA,module:"+ otaInfo.module);
                    AppLog.d(TAG, "STEP_RCVD_OTA,ext:"+ otaInfo.extData);
                    break;
                case IOta.STEP_DOWNLOAD:
                    // 下载OTA升级包中,用户可从中感知下载OTA升级包的百分比,具体请参见Demo。
                    break;
            }
            return true;
        }
    });                  
  3. 设备收到推送的OTA升级包时,返回true,会自动下载OTA升级包,下载进度通过IOta.STEP_DOWNLOAD回调。

    说明
    • 默认模块可以通过reportProgress上报升级进度。

    • 自定义模块可以通过reportModuleProgress上报升级进度。

  4. 设备下载OTA升级包完成后,设备厂商通过自己的OTA方式升级设备即可。

  5. 设备OTA升级完成后,需要上报最新版本号给服务端,服务端判断该版本号是否和预期的升级包版本号一致,如果一致则判定OTA升级成功。

    • 设备可以通过调用reportVersion接口(对于模块的OTA任务需要调用reportModuleVersion接口)实现当前版本号的上报。

    • 设备也可以通过调用tryStartOta接口重新注册OTA升级服务时上报版本号。该接口的第一个入参需要指定设备的当前的版本号,因此该接口执行后,SDK将设备当前的版本号上报到服务端。

      说明

      tryStartOta接口不能上报模块的版本号。

  6. 当您需要退出OTA升级服务(不再监听OTA升级消息)时,需要调用tryStopOta接口。

    如果之前已经执行过步骤2,当您需要通过LinkKit.getInstance().deinit()接口退出物联网服务时,请先调用tryStopOta确保之前的OTA服务已经退出。

重要

本SDK只提供OTA升级包的管理、推送、下载,具体OTA升级进度需要开发者自己定义,可通过接口reportProgress()完成。SDK同时提供reportVersion()接口,用于上报版本。

断点续传

SDK默认不开启断点续传功能,如果您需开启该功能,请参考以下方式开启。

说明

对于下载过程中断电重启的场景:

  • 不支持断电续传。

  • 重启成功后,在新启动的OTA升级任务中,将从文件头开始下载。

//设置为true,打开断点续传功能,默认为false。
mOta.enableContinuousDownload(true);

//下载异常断开后,重试24*60次,每次间隔60秒,用户可以根据自己情况进行调整。
mOta.setRetryParams(24*60, 60);

主动下载OTA升级包

SDK默认是被动接收服务端的升级消息,SDK也支持设备主动向云端查询OTA升级包的升级消息。

说明

主动下载OTA升级包功能,需设备的OTA升级开发完成才能使用。设备OTA开发,请参见上文SDK接入方法

//设备主动向云端查询OTA升级包的升级消息,"default"表示查询的是默认模块,您也可以指定其他模块名。
mOta.tryGetOtaFirmware("default");