使用限制

使用OTA功能的設備必須使用MQTT協議接入物聯網平臺，設備可以選擇MQTT協議或HTTPS協議下載升級包。

• 單個阿里云賬號最多有500個升級包，賬號下所有RAM用戶共享配額。

• 升級包的數量、大小、格式和地域限制。

  • HTTPS協議下載：可以包括一個或多個文件，單個文件最大為1,000 MB。僅支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack格式的文件。

  • MQTT協議下載：僅包含一個文件，且文件大小不超過16 MB。目前僅支持中國華東2（上海）、華北2（北京）和華南1（深圳）地域。推薦使用物聯網平臺提供的C語言Link SDK，開發MQTT下載文件的能力。詳細內容，請參見示例代碼說明。

工作原理

前提條件

• 使用物聯網卡的設備、使用C LinkSDK 2.x版本及以下的設備，需要獲取OTA升級的域名。

  OTA升級服務于2023年09月01日00:00起，變更下載升級包的域名。如果您的設備（例如，使用蜂窩網絡的物聯網設備）需要針對訪問域名設置白名單，本次變更有可能會造成您的設備無法正常下載新的升級包。您可以提交工單獲取OTA升級服務的最新域名列表。具體內容，請參見【升級】【阿里云】【物聯網平臺】OTA升級功能服務域名調整通知。

• 將設備接入物聯網平臺。使用Link SDK的設備，請參見獲取C Link SDK、設備接入引導。搭載AliOS Things芯片的設備，請參見AliOS Things文檔。

OTA升級步驟

步驟一：設備上報版本號

1. 配置OTA。

   1. 設備接入物聯網平臺。登錄物聯網平臺控制臺，單擊對應實例，在左側導航欄選擇設備管理 > 設備，找到目標設備，查看設備狀態。設備狀態顯示為在線，則表示設備與物聯網平臺成功連接。

   2. 初始化OTA功能。

   3. 配置OTA功能。

2. 設備上報當前版本號。設備需要在首次升級前上報版本號，建議只在系統啟動過程中上報一次，不需要周期循環上報。僅支持每次上報一個模塊及對應的模塊版本，如果需要上報多個模塊的版本，請分次上報。上報的Topic和消息格式參見文末的消息格式。

步驟二：推送升級包信息

1. 購買和查看OTA升級次數：查看當前實例下可用的OTA升級次數，如果可用OTA升級次數不足，請先購買套餐包。

   • 對于新版公共實例，提供免費額度10次/自然月。

   • 對于企業版實例，提供免費額度1000次/自然月。

2. 添加升級包：為產品添加OTA模塊和升級包。

   • 模塊：由用戶自定義，是同產品下設備的不同可升級模塊，例如固件、軟件、驅動等。默認（default）模塊表示整個設備的固件。

   • 整包：完整的升級文件，可以添加單個或多個升級包，如果添加多個示例包必須使用C語言的Link SDK。整包升級前，設備可不上報OTA模塊版本。如不上報，配置批量升級時不能針對指定版本進行升級，具體說明，請參見發起升級批次任務。

   • 差分：僅包含新版本升級包與之前版本的差異部分，設備需要本地進行差分還原，并還原為完整升級包進行升級，差分升級可有效降低OTA升級次數消耗和設備下載差分包的流量消耗。差分升級前，設備必須上報OTA模塊版本。

     • 使用AliOS Things芯片的設備，阿里云提供差分包生成方法和差分還原算法，請參見OTA差分工具使用指南。

     • 其他設備，需要您自行生成差分包并完成差分還原算法開發。

3. （可選）驗證升級包：添加升級包時選擇升級包是否需要平臺驗證為是，則在批量升級前，需選擇部分設備用于測試。測試設備升級成功后，才能使用升級包。

   可以選擇是否由App確認升級后才能進行OTA升級，App確認升級的流程如下：

   1. 用戶自行開發App，平臺不會主動推送升級消息給設備，需要App主動查詢。

   2. App側調用ListOTAUnfinishedTaskByDevice，查詢未完成狀態的設備升級作業。

   3. App側調用ConfirmOTATask，確認升級任務后，平臺才會主動推送升級消息給設備。

4. 發起升級批次任務：物聯網平臺向設備批量下發升級相關信息（升級包URL、版本、大小等）。發起批量升級后，在控制臺顯示的設備狀態是待升級或待確認。當物聯網平臺接收到設備上報的升級進度時，設備升級正式開始，在控制臺顯示的設備狀態是升級中。

步驟三：設備下載升級包

1. 設備獲取升級包信息。設備離線時不能接收OTA服務端推送的升級消息，設備再次上線后，OTA服務端驗證該設備是否需要升級。如果需要升級，物聯網平臺再次推送升級消息給設備，否則不推送消息。

   • 物聯網平臺推送升級包信息。設備訂閱Topic：/ota/device/upgrade/${YourProductKey}/${YourDeviceName}，物聯網平臺對設備發起OTA升級請求后，設備通過該Topic收到升級信息。具體有以下兩種情況：

     • 發起升級任務時設備在線，物聯網平臺會直接推送升級相關信息。

     • 發起升級任務時設備離線，之后設備上線，物聯網平臺會推送一次升級相關信息。

   • 設備主動拉取升級包信息。設備向Topic發布消息，物聯網平臺收到消息并通過另一Topic返回升級包信息。拉取升級包的Topic和消息格式參見文末的消息格式。

   • 物聯網平臺發給設備的HTTPS協議、MQTT協議的下載消息格式參見文末的消息格式。

2. 設備使用HTTPS協議或MQTT協議下載升級包。

   • HTTPS協議下載單個文件。

   • HTTPS協議下載多個文件。

   • MQTT協議下載單個文件。

3. 設備上報升級進度。上報進度的Topic和消息格式參見文末的消息格式。

   重要

   如果設備上報進度的間隔低于3秒，在物聯網平臺控制臺的OTA升級包詳情的批次詳情中，可能無法查看到上報的全部進度。

4. 設備上報最新版本號。設備升級完成后，建議立即重啟設備，設備上線后，立即上報新的版本號。設備上線請求和上報版本請求間隔不能超過2秒。

   重要

   如果設備上報的版本與OTA服務要求的版本一致就認為升級成功，反之認為失敗，這是物聯網平臺判斷設備升級成功的唯一條件。即使升級進度上報為100%，如果不上報新的版本號，可能因為超過設備升級超時時間導致升級失敗。

   • Topic：/ota/device/inform/${YourProductKey}/${YourDeviceName}

   • 消息格式

     {
       "id": 1,
       "params": {
         "version": "2.0.0"
       }
     }

步驟四：查看升級結果

1. 查看升級情況：查看目標設備升級狀態、升級包信息等。

2. 查看升級包版本和成功率：查看升級后的版本分布和成功率分布統計，分析OTA升級失敗原因，進而提升設備升級成功率。

相關文檔

• 設備OTA升級失敗的常見問題和解決方法，請參見如何解決設備OTA升級失敗問題。

• 可以在物聯網平臺控制臺，查詢云端運行日志。該日志包含了物聯網平臺、設備、您的應用程序三者之間的交互通信記錄。

• 物聯網平臺可能返回給設備端的錯誤碼及說明，請參見設備端接收的錯誤碼。

• 如果需要將設備上報的升級信息，通過AMQP通道推送至您的服務器，請參見配置AMQP服務端訂閱。OTA升級相關Topic數據，經過消息轉發后的數據格式，請參見數據格式。

消息格式

上報版本號

• Topic：/ota/device/inform/${YourProductKey}/${YourDeviceName}

• 消息格式

  {
    "id": 1,
    "params": {
      "version": "1.0.0",
      "module":"mcu"      //該參數如果不填，表示默認版本號default
    }
  }

  參數	類型	說明
  id	String	消息ID號。數字可為String或Long類型，以設備端上報的數據類型為準。取值范圍為0~4294967295，且每個消息ID在當前設備中具有唯一性。
  version	String	OTA模塊版本。
  module	String	OTA模塊名。上報默認（default）模塊的版本號時，可以不上報module參數。默認（default）模塊代表整個設備的固件版本號。

主動拉取升級包

1. 設備發布消息到Topic：/sys/{productKey}/{deviceName}/thing/ota/firmware/get。

   • 消息格式

     {
         "id": "123",
         "version": "1.0",
         "params": {
             "module": "MCU"
         },
         "method": "thing.ota.firmware.get"
     }

   • 參數說明

     參數	類型	說明
     id	String	消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
     version	String	協議版本，固定為1.0。
     params	Object	請求參數。
     module	String	升級包所屬的模塊名。不指定則表示請求默認（default）模塊的升級包信息。
     method	String	請求方法，取值thing.ota.firmware.get。

2. 物聯網平臺收到請求后，通過響應Topic：/sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply，向設備端返回升級包信息。

HTTPS協議下載

單文件包下載

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升級底層攝像頭驅動，解決視頻圖像模糊的問題。\"}"
        }
    }
}

多文件包下載

{
    "code": "1000",
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d***",
                "fileSign":"93230c3bde425a9d****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://***/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***qAKU%3D&security-token=***q6Ft5B2y***",
                "fileMd5":"93230c3bde425a92***",
                "fileSign":"93230c3bde425a92****"
            }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升級底層攝像頭驅動，解決視頻圖像模糊的問題。\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

MQTT協議下載

升級包下載協議為MQTT時，只支持單文件包下載。設備端獲取OTA升級包信息后，可以選擇整包下載或分片下載。

1. 整包下載

   • 消息格式

     {
         "id": "123",
         "code": 200,
         "data":{
             "size":432945,
             "digestsign":"A4WOP***SYHJ6DDDJD9***",
             "version":"2.0.0",
             "isDiff":1,
             "signMethod":"MD5",
             "dProtocol":"mqtt",
             "streamId":1397345,
             "streamFileId":1,
             "md5":"93230c3bde***",
             "sign":"93230c3bde42***",
             "module":"MCU",
             "extData":{
                 "key1":"value1",
                 "key2":"value2"
             }
         }
     }

   • 參數說明

     參數	類型	說明
     id	Long	消息ID號。每個消息ID在當前設備中具有唯一性。
     message	String	結果信息。
     code	String	狀態碼。
     version	String	設備升級包的版本信息。
     size	Long	升級包文件大小，單位：字節。 OTA升級包中僅有一個升級包文件時，包含該參數。
     url	String	升級包在對象存儲（OSS）上的存儲地址。 OTA升級包中僅有一個升級包文件，且下載協議為HTTPS時，包含該參數。
     dProtocol	String	升級包下載協議。 僅升級包下載協議為MQTT時，包含該參數。
     streamId	Long	通過MQTT協議下載OTA升級包時的唯一標識。 僅升級包下載協議為MQTT時，包含該參數。
     streamFileId	Integer	單個升級包文件的唯一標識。 僅升級包下載協議為MQTT時，包含該參數。
     isDiff	Long	僅當升級包類型為差分時，消息包含此參數。 取值為1，表示僅包含新版本升級包與之前版本的差異部分，需要設備進行差分還原。
     digestsign	String	OTA升級包文件安全升級后的簽名。僅當OTA升級包開啟安全升級功能，才有此參數。開啟OTA升級包安全升級功能的方法，請參見添加升級包。
     sign	String	OTA升級包文件的簽名。 OTA升級包中僅有一個升級包文件時，包含該參數。
     signMethod	String	簽名方法。取值： SHA256 MD5 對于Android差分升級包類型，僅支持MD5簽名方法。
     md5	String	當簽名方法為MD5時，除了會給sign賦值外還會給md5賦值。 OTA升級包中僅有一個升級包文件時，包含該參數。
     module	String	升級包所屬的模塊名。模塊名為default時，物聯網平臺不下發module參數。
     extData	Object	升級批次標簽列表和推送給設備的自定義信息。 _package_udi表示自定義信息的字段。 單個標簽格式："key":"value"。
     files	Array	多個升級包文件的信息列表。 OTA升級包中有多個文件時，包含該參數。每個升級包文件信息如下： fileSize：升級包文件大小。 fileName：升級包文件的名稱。 fileUrl、fileMd5、fileSign：含義與url、md5、sign相同。

2. 可選：分片下載。獲取上面的升級包信息后，設備通過以下Topic分片下載OTA升級包文件。

   • 請求Topic：/sys/${productKey}/${deviceName}/thing/file/download

   • 響應Topic：/sys/${productKey}/${deviceName}/thing/file/download_reply

   • 請求消息格式

     {
      "id": "123456",
      "version": "1.0",
      "params": {
      "fileToken":"1bb8***",
      "fileInfo":{
      "streamId":1234565,
      "fileId":1
      },
      "fileBlock":{
      "size":256,
      "offset":2
      }
      }
     }

   • 請求消息的參數說明

     參數	類型	說明
     id	String	消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
     version	String	協議版本，固定為1.0。
     params	Object	請求參數。
     fileToken	String	文件的唯一標識Token，非必填參數。支持數字、英文字母、下劃線（_）和英文句號（.），不超過16個字符。 使用說明： 若傳入該參數，物聯網平臺響應設備請求時，會返回該參數，便于您在設備端多文件下載場景下，從響應消息中確認下載的對應文件。 若確認設備端在下載文件的請求和響應周期內，不需要對其他文件發起下載請求，可不設置該參數。
     fileInfo	Object	OTA升級包文件信息。
     streamId	Long	通過MQTT協議下載OTA升級包時的唯一標識。
     fileId	Integer	單個升級包文件的唯一標識。
     fileBlock	Object	文件分片信息。
     size	Integer	請求下載的文件分片大小，單位字節，取值范圍為256~131072。若為最后一個文件分片，取值范圍為1~131072。
     offset	Integer	文件分片對應字節的起始地址。取值范圍為0~16777216。

   • 響應消息的結構

     

     結構項	說明
     JSON Bytes Length	表示響應數據中JSON字符串對應的字節數組長度，必須占位2個字節，高位字節在前，低位字節在后。 例如，響應的JSON字符串使用UTF-8編碼轉碼成字節數組的長度為十進制的87，對應十六進制57，則高位字節為0x00，低位字節為0x57。
     JSON String Bytes	表示響應數據中JSON字符串對應的字節數組，編碼格式為UTF-8。具體內容，請參見下文的“響應的JSON數據格式”。
     File Block Bytes	表示當前文件分片的字節數組，字節順序按照相對于文件頭的偏移量從小至大排列。
     CRC16/IBM	表示文件分片的校驗值，僅支持CRC16/IBM，占位2個字節，低位字節在前，高位字節在后。 例如，文件分片的校驗值為0x0809，則低位字節為0x09，高位字節為0x08。

   • 響應消息格式

     {
      "id": "123456",
      "code":200,
      "msg":"file size has exceeded the limit 16 MB",
      "data": {
      "fileToken":"1bb8***",
      "fileLength":1238848,
      "bSize":1491,
      "bOffset":2
      }
     }

   • 響應消息的參數說明

     參數	類型	說明
     id	String	消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。 此處消息ID返回的是設備請求中的消息ID，即請求Topic/sys/${productKey}/${deviceName}/thing/file/download數據中的id。
     code	Integer	狀態碼，200表示成功。
     msg	String	請求失敗時，返回的錯誤信息。
     data	Object	返回設備端的數據。
     fileToken	String	文件的唯一標識Token。若請求參數傳入了fileToken值，則返回該參數。
     fileLength	Integer	文件的總大小，單位字節。
     bSize	Integer	當前文件分片的大小，單位字節。
     bOffset	Integer	當前文件分片對應字節的起始地址，與請求數據中的offset值相同。單位字節。

上報升級進度

• 設備發布消息到Topic：/ota/device/progress/${YourProductKey}/${YourDeviceName}。

• 消息格式

  {
      "id": "123",
      "params": {
          "step": "-1",
          "desc": "OTA升級失敗，請求不到升級包信息。",
          "module": "MCU"
      }
  }

• 格式說明

  參數	類型	說明
  id	String	消息ID號。String類型的數字，取值范圍0~4294967295，且每個消息ID在當前設備中具有唯一性。
  step	String	OTA升級進度。設備上報的進度值及其描述信息，可根據設備實際升級場景在設備端配置。設備端配置方法，請參見示例代碼說明。 1~100的整數：升級進度百分比。 -1：升級失敗。 -2：下載失敗。 -3：校驗失敗。 -4：燒寫失敗。
  desc	String	當前步驟的描述信息，長度不超過128個字符。如果發生異常，此字段可承載錯誤信息。
  module	String	升級包所屬的模塊名。模塊的更多信息，請參見添加升級包。 上報默認（default）模塊的OTA升級進度時，可以不上報module參數。