秀杰智联

Appearance

固件升级 OTA ​

OTA（Over-the-Air Technology）即空中下载技术，是指通过无线网络从远程服务器中下载最新的应用或系统，从而对设备固件实现升级。主要有两个应用场景：修复已知 Bug 和增加新功能。

本文主要从设备与云端的交互逻辑，介绍 OTA 升级消息的 Topic 和数据格式，包括设备上报固件版本、云端下发 OTA 升级、设备定时拉取 OTA 升级、设备上报升级状态或进度、设备升级完成上报版本等。

名称解释 ​

名词含义
云端推送升级用户在 App 或 SaaS 平台等业务系统操作发起升级，云端推送升级到设备。
设备定时检测升级设备主动或定时到云端请求 OTA 升级，升级过程用户无感知。

设备上报固件版本 ​

设备初始化上报固件版本信息

设备发送消息 ​

设备注册激活后，如果需要使用 OTA 功能，则需要对接 OTA 协议上报对应的固件通道号及版本信息。设备上报固件版本信息后，云端会根据设备上报的固件版本信息，查询云端是否有对应的升级包。 设备升级完成后，上报升级完成的固件信息。云端根据上报的版本信息，更新设备固件版本信息和升级任务的状态。

topic：things/up/${tenantId}/${productKey}/${deviceKey}/ota/firmware/post

设备初始上报固件版本信息

json
{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "method": "ota/firmware/post",
    "data":{
        "type":0,  
        "channel":0,
        "firmware":"1.3.13"
    }
}

设备升级完成上报固件版本信息

json
{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "method": "ota/firmware/post",
    "data":{
        "type":1,
        "channel":0,
        "taskId":"task001",
        "firmware":"1.3.13"
    }
}

参数说明

参数类型说明必选备注
${productKey}string设备 ID是事件上报的目标设备的所属产品 Key。
${deviceKey}string设备 ID是事件上报的目标设备的 Key。
versionstring协议版本否默认 1.0，且仅有 1.0。
msgIdstring消息 ID是总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
timenumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
methodstring消息类型否消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
dataobject设备固件版本信息是设备固件版本信息。
data.typenumber业务类型是业务类型。 0: 版本初始化 1: 固件升级完成版本更新
data.taskIdstring升级任务ID是云端下发的任务ID
data.channelnumber固件通道号是0：主模块固件通道 1：蓝牙固件通道 3：Zigbee 固件通道 9：MCU 固件通道 >9：扩展通道。
data.firmwarestring固件版本是固件版本。

云端下发 OTA 升级 ​

设备接收消息 ​

云端收到 App 或后台下发升级调用后，检测升级固件版本，下发 OTA 升级给设备。

topic：things/down/${tenantId}/${productKey}/${deviceKey}/ota/firmware/upgrade

json
{
    "msgId":"45lkj3551234***",
  	"time":1626197189638,
    "method": "ota/firmware/upgrade",
	"data":{
        "firmware":"1.3.13",
        "url":"http://ota.xiujiezhilian.com/s_UG_1.3***.bin",
        "httpsUrl":"https://ota.xiujiezhilian.com/s_UG_1.3***.bin",
        "size":"1306707",
        "md5":"e7471fe76cecc562f93d57745acac***",
        "hmac":"952C262E4F40D25B2DF2D3923485AE4EBD8B194F77D41BED2B67B1A335022***",
        "forced":1,
        "channel":0,
        "taskId":"task001"
    }
}

参数说明

参数类型说明必选备注
${productKey}string设备 ID是事件上报的目标设备的所属产品 Key。
${deviceKey}string设备 ID是事件上报的目标设备的 Key。
versionstring协议版本否默认 1.0，且仅有 1.0。
msgIdstring消息 ID是总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
timenumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
methodstring消息类型否消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
dataobjectOTA 升级信息是OTA 升级信息。
data.firmwarestring固件版本是固件版本。
data.urlstring固件下载地址是固件下载地址。
data.sizestring文件大小是固件大小。
data.md5string固件文件 MD5是固件 MD5。
data.hmacstring固件文件 HMAC 值是固件文件 HMAC 值，通过 productKey 作为秘钥，通过 sha256_HMAC 计算得到。
data.forcednumber是否强制升级是是否强制升级。 0: 非强制升级 1: 强制升级
data.channelnumber固件通道号是0：主模块固件通道 1：蓝牙固件通道 3：Zigbee 固件通道 9：MCU 固件通道 >9：扩展通道。
data.taskIdstring升级任务ID是上报进度需要携带

上报升级状态或进度 ​

设备发送消息 ​

设备收到云端下发的 OTA 升级后，开始升级固件。当升级过程中，设备上报升级状态或进度。

topic：things/up/${tenantId}/${productKey}/${deviceKey}/ota/progress/post

上报进度信息

json
{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "method": "ota/progress/post",
    "data":{
        "taskId":"task001",
        "channel":0,
        "firmware":"1.3.13",
        "progress":98
    }
}

上报升级异常状态

json
{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "method": "ota/progress/post",
    "data":{
        "taskId":"task001",
        "channel":0,
        "firmware":"1.3.13",
        "code":42,
        "msg": "下载失败，无法连接服务器"
    }
}

参数说明

参数类型说明必选备注
${productKey}string设备 ID是事件上报的目标设备的所属产品 Key。
${deviceKey}string设备 ID是事件上报的目标设备的 Key。
versionstring协议版本否默认 1.0，且仅有 1.0。
msgIdstring消息 ID是总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
timenumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
methodstring消息类型否消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
dataobjectOTA 升级信息是OTA 升级信息。
data.taskIdstring升级任务ID是云端下发的任务ID
data.channelnumber固件通道号是0：主模块固件通道 1：蓝牙固件通道 3：Zigbee 固件通道 9：MCU 固件通道 >9：扩展通道。
data.firmwarestring固件版本是固件版本。
data.progressnumber固件升级进度否固件升级进度，范围 0~100。
data.codenumber固件升级异常状态码否固件升级异常状态码，范围 0~100。
data.msgstring固件升级异常状态信息否固件升级异常状态信息。