獲取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");