固件升级 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,
"data":{
"type":0,
"firmware":"key5943jddfsy***
}
}设备升级完成上报固件版本信息
json
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"type":1,
"firmware":"key5943jddfsy***
}
}参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${productKey} | string | 设备 ID | 是 | 事件上报的目标设备的所属产品 Key。 |
| ${deviceKey} | string | 设备 ID | 是 | 事件上报的目标设备的 Key。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | 设备固件版本信息 | 是 | 设备固件版本信息。 |
| data.type | number | 业务类型 | 是 | 业务类型。 0: 版本初始化 1: 固件升级完成版本更新 |
| data.firmware | string | 固件版本 | 是 | 固件版本。 |
云端下发 OTA 升级
设备接收消息
云端收到 App 或后台下发升级调用后，检测升级固件版本，下发 OTA 升级给设备。
topic：things/down/${tenantId}/${productKey}/${deviceKey}/ota/firmware/upgrade
json
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"firmware":"1.3.13",
"url":"http://airtake-public-data-1254153901.cos.tuyacn.com/smart/firmware/upgrade/202006/1592465280-tuya_rtl8196e_gw_tar_UG_1.3***.bin",
"size":"1306707",
"md5":"e7471fe76cecc562f93d57745acac***",
"hmac":"952C262E4F40D25B2DF2D3923485AE4EBD8B194F77D41BED2B67B1A335022***",
"forced":1
}
}参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${productKey} | string | 设备 ID | 是 | 事件上报的目标设备的所属产品 Key。 |
| ${deviceKey} | string | 设备 ID | 是 | 事件上报的目标设备的 Key。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | OTA 升级信息 | 是 | OTA 升级信息。 |
| data.firmware | string | 固件版本 | 是 | 固件版本。 |
| data.url | string | 固件下载地址 | 是 | 固件下载地址。 |
| data.size | string | 文件大小 | 是 | 固件大小。 |
| data.md5 | string | 固件文件 MD5 | 是 | 固件 MD5。 |
| data.hmac | string | 固件文件 HMAC 值 | 是 | 固件文件 HMAC 值，通过 deviceSecret 作为秘钥，通过 sha256_HMAC 计算得到。 |
| data.forced | number | 是否强制升级 | 是 | 是否强制升级。 0: 非强制升级 1: 强制升级 |
上报升级状态或进度
设备发送消息
设备收到云端下发的 OTA 升级后，开始升级固件。当升级过程中，设备上报升级状态或进度。
topic：things/up/${tenantId}/${productKey}/${deviceKey}/ota/progress/post
上报进度信息
json
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"firmware":"v1.2.2",
"progress":98
}
}上报升级异常状态
json
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"firmware":"v1.2.2",
"code":42,
"msg": "下载失败，无法连接服务器"
}
}参数说明
| 参数 | 类型 | 说明 | 必选 | 备注 |
|---|---|---|---|---|
| ${productKey} | string | 设备 ID | 是 | 事件上报的目标设备的所属产品 Key。 |
| ${deviceKey} | string | 设备 ID | 是 | 事件上报的目标设备的 Key。 |
| version | string | 协议版本 | 否 | 默认 1.0，且仅有 1.0。 |
| msgId | string | 消息 ID | 是 | 总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。 |
| time | number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。 |
| data | object | OTA 升级信息 | 是 | OTA 升级信息。 |
| data.firmware | string | 固件版本 | 是 | 固件版本。 |
| data.progress | number | 固件升级进度 | 否 | 固件升级进度，范围 0~100。 |
| data.code | number | 固件升级异常状态码 | 否 | 固件升级异常状态码，范围 0~100。 |
| data.msg | string | 固件升级异常状态信息 | 否 | 固件升级异常状态信息。 |