物聯網平台提供OTA升級與管理服務。本文介紹OTA升級訊息的Topic和資料格式，包括裝置上報OTA模組版本、物聯網平台推送升級包資訊、裝置上報升級進度和裝置請求擷取最新升級包資訊。
裝置進行OTA升級的完成流程，請參見OTA升級步驟。
裝置上報OTA模組版本
資料上行。
Topic：/ota/device/inform/${productKey}/${deviceName}。
裝置通過這個Topic上報當前的OTA模組版本資訊。
重要 本Topic只支援單個模組的版本上報。如果裝置需要上報多個模組的版本，請分多次上報，每次上報一個模組的版本資訊。
請求資料格式：
{
"id": "123",
"params": {
"version": "1.0.1",
"module": "MCU"
}
}| 參數 | 類型 | 說明 |
| id | String | 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 |
| version | String | OTA模組版本。 |
| module | String | OTA模組名。 說明
|
物聯網平台推送OTA升級包資訊
資料下行。
Topic：/ota/device/upgrade/${productKey}/${deviceName}。
物聯網平台通過這個Topic推送OTA升級包資訊， 裝置訂閱該Topic可以獲得升級包資訊。
- 單個檔案的OTA升級包資訊：
- 升級包下載協議為HTTPS：
{ "code": "1000", "data": { "size": 432945, "version": "2.0.0", "isDiff": 1, "url": "https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P6DW***qAKU%3D&security-token=***Tz2IHtIf3***", "md5": "93230c3bde425a9d***", "digestsign":"A4WOP***SYHJ6DDDJD9***", "sign": "93230c3bde425a9d***", "signMethod": "MD5", "module": "MCU", "extData":{ "key1":"value1", "key2":"value2", "_package_udi":"{\"ota_notice\":\"升級底層網路攝影機驅動，解決視頻映像模糊的問題。\"}" } }, "id": 1626969597470, "message": "success" } - 升級包下載協議為MQTT：
{ "code":"1000", "data":{ "size":432945, "version":"2.0.0", "isDiff":1, "signMethod":"MD5", "dProtocol":"mqtt", "streamId":1397345, "streamFileId":1, "md5":"93230c3bde425***", "digestsign":"A4WOP***SYHJ6DDDJD9***", "sign":"93230c3bde425***", "module":"MCU", "extData":{ "key1":"value1", "key2":"value2" } }, "id":1507707025, "message":"success" }
- 升級包下載協議為HTTPS：
- 多個檔案的OTA升級包僅支援HTTP下載協議，資訊如下：
{ "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" }
| 參數 | 類型 | 說明 |
| 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 | 簽名方法。取值：
|
| md5 | String | 當簽名方法為MD5時，除了會給sign賦值外還會給md5賦值。 OTA升級包中僅有一個升級包檔案時，包含該參數。 |
| module | String | 升級包所屬的模組名。 說明 模組名為default時，物聯網平台不下發module參數。 |
| extData | Object | 升級批次標籤列表和推送給裝置的自訂資訊。 _package_udi表示自訂資訊的欄位。 單個標籤格式： |
| files | Array | 多個升級包檔案的資訊列表。 OTA升級包中有多個檔案時，包含該參數。每個升級包檔案資訊如下：
|
裝置上報升級進度
資料上行。
Topic：/ota/device/progress/${productKey}/${deviceName}。
OTA升級過程中，裝置可以通過這個Topic上報OTA升級的進度百分比。
說明 建議設定裝置端上報進度頻率為3秒內最多一次。若裝置上報進度頻繁，在物聯網平台控制台的OTA升級包詳情的批次詳情中，可能無法查看到上報的全部進度。
請求資料格式：
{
"id": "123",
"params": {
"step": "-1",
"desc": "OTA升級失敗，請求不到升級包資訊。",
"module": "MCU"
}
}| 參數 | 類型 | 說明 |
| id | String | 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 |
| step | String | OTA升級進度。 取值範圍：
裝置上報的進度值及其描述資訊，可根據裝置實際升級情境在裝置端配置。裝置端配置方法，請參見裝置端Link SDK的OTA升級。 |
| desc | String | 當前步驟的描述資訊，長度不超過128個字元。如果發生異常，此欄位可承載錯誤資訊。 |
| module | String | 升級包所屬的模組名。模組的更多資訊，請參見添加升級包。 說明 上報預設（default）模組的OTA升級進度時，可以不上報module參數。 |
裝置請求OTA升級包資訊
資料上行。
請求Topic：/sys/${productKey}/${deviceName}/thing/ota/firmware/get。
響應Topic：/sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply。
請求資料格式：
{
"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。 |
物聯網平台收到裝置請求後，響應請求。
- 下發升級包資訊。返回資料格式如下：
- 單個檔案的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\":\"升級底層網路攝影機驅動，解決視頻映像模糊的問題。\"}" } } }
表 5. 參數說明 參數 類型 說明 id String 訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。 此處訊息ID返回的是裝置請求中的訊息ID，即請求Topic
/sys/${productKey}/${deviceName}/thing/ota/firmware/get資料中的id。code Integer 狀態代碼，200表示成功。 data Object 升級包資訊，其中參數說明，請參見物聯網平台推送OTA升級包資訊的參數表。 - 單個檔案的OTA升級包資訊：
- 無升級包資訊下發。返回資料格式如下：
{ "id": "123", "code": 200, "data": { } }
裝置請求下載檔案分區
升級包下載協議為MQTT時，裝置端擷取OTA升級包資訊後，可通過以下Topic分區下載OTA升級包檔案。
重要 裝置端通過MQTT協議下載的單個檔案大小不能超過16 MB。
- 請求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。
- 響應的JSON資料格式：
{ "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 |
| code | Integer | 狀態代碼，200表示成功。 |
| msg | String | 請求失敗時，返回的錯誤資訊。 |
| data | Object | 返回裝置端的資料。 |
| fileToken | String | 檔案的唯一標識Token。若請求參數傳入了fileToken值，則返回該參數。 |
| fileLength | Integer | 檔案的總大小，單位位元組。 |
| bSize | Integer | 當前檔案分區的大小，單位位元組。 |
| bOffset | Integer | 當前檔案分區對應位元組的起始地址，與請求資料中的offset值相同。單位位元組。 |
相關文檔
錯誤碼說明及解決辦法，請參見裝置端接收的錯誤碼。