设备OTA升级

获取SDK

您可以下载物联网平台提供的Android Link SDK 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协议下载升级包。

• 当您在物联网平台控制台验证升级包和发起升级批次任务时，升级包下载协议必须选择HTTPS。更多信息，请参见验证升级包和发起升级批次任务。

• 当您调用云端接口验证升级包（CreateOTAVerifyJob）和发起升级批次任务（CreateOTAStaticUpgradeJob和CreateOTADynamicUpgradeJob）时，请求参数DownloadProtocol必须传入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默认不开启断点续传功能，如果您需开启该功能，请参考以下方式开启。

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

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

主动下载OTA升级包

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

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