OTA（Over-the-Air Technology）即空中下載技術。物聯網平台支援通過OTA方式進行裝置升級。本文以MQTT協議下的OTA升級為例，介紹OTA升級流程、資料流轉使用的Topic和資料格式。
OTA升級流程
MQTT協議下OTA升級流程如下圖所示。
OTA升級說明
- 差分升級前，裝置必須上報OTA模組版本。整包升級前，裝置可不上報OTA模組版本。如不上報，配置批量升級時不能針對指定版本進行升級，具體說明，請參見發起升級批次任務。
若裝置需要在首次升級前上報版本號碼，建議只在系統啟動過程中上報一次，不需要周期迴圈上報。裝置升級成功後，需要第一時間上報版本。
- 從物聯網平台控制台發起批量升級後，裝置升級操作選項組是待升級。
實際升級從物聯網平台OTA系統，接收到裝置上報的升級進度開始。裝置升級操作選項組是升級中。
說明 裝置端接收到物聯網平台推送的升級通知後，可立即下載升級包進行升級，也可在業務空閑後，主動擷取升級資訊進行升級。 - 物聯網平台根據裝置端上報的版本號碼來判斷裝置端OTA升級是否成功。
- 裝置離線時，不能接收服務端推送的升級訊息。
通過MQTT協議接入物聯網平台的裝置再次上線後，物聯網平台自動檢測到裝置上線，OTA服務端驗證該裝置是否需要升級。如果需要升級，物聯網平台再次推送升級訊息給裝置，否則不推送訊息。
資料格式說明
裝置端OTA開發流程和程式碼範例，請參見Link SDK文檔中，各語言SDK文檔的裝置OTA開發章節。
OTA升級流程及使用的Topic和資料格式如下：
- （可選）裝置串連OTA服務，上報版本號碼。
裝置端通過MQTT協議推送當前裝置OTA模組版本號碼到Topic：
/ota/device/inform/${productKey}/${deviceName}。訊息格式如下：{ "id": "123", "params": { "version": "1.0.1", "module": "MCU" } }表 1. 參數說明 參數 類型 說明 id String 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 version String OTA模組版本。 module String OTA模組名。 說明- 上報預設（default）模組的版本號碼時，可以不上報module參數。
- 裝置的預設（default）模組的版本號碼代表整個裝置的韌體版本號碼。
- 在物聯網平台控制台上，添加升級包、驗證升級包並發起批量升級任務。
具體操作，請參見推送升級包到裝置端。
- 您在控制台觸發升級操作之後，裝置會收到物聯網平台OTA服務推送的升級包的URL地址。
裝置端訂閱Topic：
/ota/device/upgrade/${productKey}/${deviceName}。物聯網平台對裝置發起OTA升級請求後，裝置端會通過該Topic收到升級包的儲存地址URL。訊息格式如下：
- 單個檔案的OTA升級包資訊：
- 升級包下載協議為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\":\"升級底層網路攝影機驅動，解決視頻映像模糊的問題。\"}" } } } - 升級包下載協議為MQTT：
{ "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" } } }
- 升級包下載協議為HTTPS：
- 多個檔案的OTA升級包僅支援HTTP下載協議，資訊如下：
{ "id": "123", "code": 200, "data": { "version": "2.0.0", "isDiff": 1, "signMethod": "MD5", "files":[ { "fileSize":432944, "fileName":"file1-name", "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***", "fileMd5":"93230c3bde425a9d7984a594ac55ea1e", "fileSign":"93230c3bde425a9d7984a594ac55****" }, { "fileSize":432945, "fileName":"file2-name", "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***", "fileMd5":"93230c3bde425a9d7984a594ac56ea1f", "fileSign":"93230c3bde425a9d7984a594ac56****" } ], "module": "MCU", "extData":{ "key1":"value1", "key2":"value2", "_package_udi":"{\"ota_notice\":\"升級底層網路攝影機驅動，解決視頻映像模糊的問題。\"}" } } }
表 2. 參數說明 參數 類型 說明 id Long 訊息ID號。每個訊息ID在當前裝置中具有唯一性。 message String 結果資訊。 code String 狀態代碼。 version String 裝置升級包的版本資訊。 size Long 升級包檔案大小，單位：位元組。 OTA升級包中僅有一個升級包檔案時，包含該參數。
url String 升級包在Object Storage Service上的儲存地址。 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 簽名方法。取值： SHA256MD5
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相同。
- 單個檔案的OTA升級包資訊：
- （可選）裝置端SDK接收到物聯網平台推送的升級包URL後，若未在24小時內完成升級包下載，該URL失效。裝置端可通過調用以下topic，重新向物聯網平台主動請求擷取升級任務。
裝置端發起請求的Topic為
/sys/${productKey}/${deviceName}/thing/ota/firmware/get，訊息格式如下。{ "id": "123", "version": "1.0", "params": { "module": "MCU" }, "method": "thing.ota.firmware.get" }表 4. 參數說明 參數 類型 說明 id String 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 version String 協議版本，固定為1.0。 params Object 請求參數。 module String 升級包所屬的模組名。 說明 不指定則表示請求預設（default）模組的升級包資訊。method String 要求方法，取值thing.ota.firmware.get。 物聯網平台收到請求後，通過響應Topic：
/sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply，向裝置端返回升級包資訊。- 下發升級包資訊。返回資料格式如下：
- 單個檔案的OTA升級包資訊：
- 升級包下載協議為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\":\"升級底層網路攝影機驅動，解決視頻映像模糊的問題。\"}" } } } - 升級包下載協議為MQTT：
{ "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" } } }
- 升級包下載協議為HTTPS：
- 多個檔案的OTA升級包僅支援HTTP下載協議，資訊如下：
{ "id": "123", "code": 200, "data": { "version": "2.0.0", "isDiff": 1, "signMethod": "MD5", "files":[ { "fileSize":432944, "fileName":"file1-name", "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***", "fileMd5":"93230c3bde425a9d7984a594ac55ea1e", "fileSign":"93230c3bde425a9d7984a594ac55****" }, { "fileSize":432945, "fileName":"file2-name", "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***", "fileMd5":"93230c3bde425a9d7984a594ac56ea1f", "fileSign":"93230c3bde425a9d7984a594ac56****" } ], "module": "MCU", "extData":{ "key1":"value1", "key2":"value2", "_package_udi":"{\"ota_notice\":\"升級底層網路攝影機驅動，解決視頻映像模糊的問題。\"}" } } }
表 1. 參數說明 參數 類型 說明 id String 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 此處訊息ID返回的是裝置請求中的訊息ID，即請求Topic
/sys/${productKey}/${deviceName}/thing/ota/firmware/get資料中的id。code Integer 狀態代碼，200表示成功。 data String 升級包資訊，其中參數說明，請參見物聯網平台推送OTA升級包資訊的參數表。 - 單個檔案的OTA升級包資訊：
- 無升級包資訊下發。返回資料格式如下：
{ "id": "123", "code": 200, "data": { } }
- 下發升級包資訊。返回資料格式如下：
- 裝置端SDK收到物聯網平台推送的升級包URL後，調用SDK提供的介面下載升級包。具體操作，請參見裝置OTA。 說明 裝置端無法自動下載升級包，可通過調用SDK中介面進行下載。下載須在升級包URL下發後的24小時內完成，否則該URL失效。
升級包下載過程日誌，請參見：
- 升級過程中，裝置端向服務端推送升級進度到Topic：
/ota/device/progress/${productKey}/${deviceName}。說明 建議設定裝置端上報進度頻率為3秒內最多一次。若裝置上報進度頻繁，在物聯網平台控制台的OTA升級包詳情的批次詳情中，可能無法查看到上報的全部進度。訊息格式如下：
{ "id": "123", "params": { "step": "-1", "desc": "OTA升級失敗，請求不到升級包資訊。", "module": "MCU" } }表 3. 參數說明 參數 類型 說明 id String 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 step String OTA升級進度。
取值範圍：- 1~100的整數：升級進度百分比。
-1：升級失敗。-2：下載失敗。-3：校正失敗。-4：燒寫失敗。
裝置上報的進度值及其描述資訊，可根據裝置實際升級情境在裝置端配置。裝置端配置方法，請參見裝置端Link SDK的OTA升級。
desc String 當前步驟的描述資訊，長度不超過128個字元。如果發生異常，此欄位可承載錯誤資訊。 module String 升級包所屬的模組名。模組的更多資訊，請參見添加升級包。 說明 上報預設（default）模組的OTA升級進度時，可以不上報module參數。 - 裝置端完成OTA升級後，推送新版本資訊到Topic：
/ota/device/inform/${productKey}/${deviceName}。如果上報的版本與OTA服務需求的版本一致就認為升級成功，反之失敗。說明 升級成功的唯一判斷標誌是裝置上報正確的版本號碼。即使升級進度上報為100%，如果不上報新的版本號碼，會因逾時導致升級失敗。裝置升級完成時，建議立即重啟裝置，裝置上線後，立即上報新的版本號碼。裝置上線請求和上報版本請求間隔不能超過2秒。
常見下載升級包錯誤
- 簽名錯誤。如果裝置端擷取的升級包的URL不全或者手動修改了URL內容，就會出現如下錯誤：
- 拒絕訪問。URL到期導致。目前，URL有效期間為24小時。
