物聯網平臺提供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 | 升級包在對象存儲（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 | 簽名方法。取值：
|
| 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值相同。單位字節。 |
相關文檔
錯誤碼說明及解決辦法，請參見設備端接收的錯誤碼。