固件升级 OTA

更新时间：2024-06-19 06:29:09下载pdf

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

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

名称解释

名词	含义
固件通道号	通道号用来标识设备固件的类型，可以理解为固件的标识符。可分为： `0`：主模块固件通道 `1`：蓝牙固件通道 `3`：Zigbee 固件通道 `9`：MCU 固件通道 `>9`：扩展通道。
云端推送升级	用户在 App 或 SaaS 平台等业务系统操作发起升级，涂鸦云端推送升级到设备。
设备定时检测升级	设备主动或定时到云端请求 OTA 升级，升级过程用户无感知。

OTA 流程

MQTT 协议下 OTA 升级流程如下图所示：

云端推送升级流程

固件升级 OTA

设备定时检测升级流程

固件升级 OTA

设备上报固件版本

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

设备发送消息

设备注册激活后，如果需要使用 OTA 功能，则需要对接 OTA 协议上报对应的固件通道号及版本信息。

topic：tylink/${deviceId}/ota/firmware/report

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{
        "bizType":"INIT",
        "pid":"5k8h97qska6pf***",
        "firmwareKey":"key5943jddfsy***",
        "otaChannel":[
            {
                "channel":0,
                "version":"1.1.6"
            },
            {
                "channel":9,
                "version":"1.0.0"
            }
        ]
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID，如果是子设备的身份，`deviceId` 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	设备固件版本信息	是	设备固件版本信息。
data.bizType	string	业务类型	是	业务类型。 `INIT`：固件版本初始化 `UPDATE`：固件升级完成版本更新
data.pid	string	产品 PID	是	产品 PID
data.firmwareKey	string	固件 key	否	产品固件 key，针对模块固件，支持上报固件 key 的情况，初始化时需要带上固件 key。
data.otaChannel	object	固件信息列表	是	固件版本信息列表。
data.otaChannel.channel	number	固件通道号	是	固件 OTA 通道号。 `0`：主模块固件通道 `1`：蓝牙固件通道 `3`：Zigbee 固件通道 `9`：MCU 固件通道 `>9`：扩展通道。
data.otaChannel.version	string	固件版本	是	版本号采用 `xx.yy.zz` 点分表示，范围支持 `0.0.0` 到 `99.99.99`。例如：`1.0.0`。

云端下发 OTA 升级

设备接收消息

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

topic：tylink/${deviceId}/ota/issue

{
    "msgId":"45lkj3551234***",
  	"time":1626197189638,
	"data":{
        "ctId":"bee8d56c2868302ec4d094d652325***",
        "channel":0,
        "version":"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",
        "cdnUrl":"https://images.tuyacn.com/smart/firmware/upgrade/202006/1592465280-tuya_rtl8196e_gw_tar_UG_1.3***.bin",
        "size":"1306707",
        "md5":"e7471fe76cecc562f93d57745acac***",
        "hmac":"952C262E4F40D25B2DF2D3923485AE4EBD8B194F77D41BED2B67B1A335022***",
        "httpsUrl":"https://fireware.tuyacn.com:1443/smart/firmware/upgrade/202006/1592465280-tuya_rtl8196e_gw_tar_UG_1.3***.bin",
        "upgradeType":1,
        "execTime":0
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID，如果是子设备的身份，`deviceId` 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	OTA 升级信息	是	OTA 升级信息。
data.ctId	string	发起固件升级的 App 客户端 `traceId`	是	用来做日志回溯, 开发者可不用处理。用来标识发起固件升级的 App 客户端 `traceId`，仅定位发起升级的 App 信息，如：`bee8d56c2868302ec4d094d652325***`。
data.channel	number	固件通道号	是	固件 OTA 通道号。 `0`：主模块固件通道 `1`：蓝牙固件通道 `3`：Zigbee 固件通道 `9`：MCU 固件通道 `>9`：扩展通道。
data.version	string	固件版本号	是	版本号采用 `xx.yy.zz` 点分表示，范围支持 `0.0.0` 到 `99.99.99`。例如：`1.0.0`。
data.url	string	固件 URL 地址	是	固件 URL 地址。
data.cdnUrl	string	CDN 固件 URL 地址	是	CDN 固件 URL 地址。
data.size	string	文件大小	是	单位为字节。
data.md5	string	固件文件 MD5	是	固件文件 MD5。
data.hmac	string	固件文件 HMAC 值	是	固件文件 HMAC 值，通过 `deviceSecret` 作为秘钥，通过 `sha256_HMAC` 计算得到。
data.httpsUrl	string	HTTPS 固件 URL 代理地址	是	HTTPS 固件 URL 代理地址。
data.upgradeType	integer	升级类型	是	升级类型。 `0`：App 提醒升级 `1`：设备静默升级 `2`：App 强制升级 `3`：App 检测升级
data.execTime	long	指定执行时间	是	用于静默升级向设备指定升级时间，为 `0` 或者小于当前时间表示立即执行。

设备获取固件升级

设备发送消息

设备发送 MQTT 到云端获取固件升级版本、URL 等信息。

topic：tylink/${deviceId}/ota/get

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{}
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID，如果是子设备的身份，`deviceId` 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息的id	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	获取 OTA 参数	否	获取 OTA 参数。

设备接收消息

云端响应设备获取固件升级版本、URL 等信息。

topic：tylink/${deviceId}/ota/get_response

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{
        "url":"http://airtake-public-data-1254153901.cos.tuyacn.com/smart/firmware/upgrade/202006/1592465280-tuya_rtl8196e_gw_tar_UG_1.3***.bin",
        "cdnUrl":"https://images.tuyacn.com/smart/firmware/upgrade/202006/1592465280-tuya_rtl8196e_gw_tar_UG_1.3***.bin",
        "size":"1306707",
        "md5":"e7471fe76cecc562f93d57745acac***",
        "hmac":"952C262E4F40D25B2DF2D3923485AE4EBD8B194F77D41BED2B67B1A335022***",
        "version":"1.3.13",
        "channel":0,
        "httpsUrl":"https://fireware.tuyacn.com:1443/smart/firmware/upgrade/202006/1592465280-tuya_rtl8196e_gw_tar_UG_1.3***.bin",
        "upgradeType":1,
        "execTime":0
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备id	是	设备 ID，如果是子设备的身份，`deviceId` 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息的id	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	OTA升级信息	是	OTA 升级信息。
data.url	string	固件 URL 地址	是	固件 URL 地址。
data.cdnUrl	string	CDN 固件 URL 地址	是	CDN 固件 URL 地址。
data.size	string	文件大小	是	单位为字节。
data.md5	string	固件文件 MD5	是	固件文件 MD5。
data.hmac	string	固件文件 HMAC 值	是	固件文件 HMAC 值，采用 `deviceSecret` 作为秘钥，通过 `sha256_HMAC` 计算得到。
data.version	string	固件版本号	是	版本号采用 `xx.yy.zz` 点分表示，范围支持 `0.0.0` 到 `99.99.99`。例如：`1.0.0`。
data.channel	number	固件通道号	是	固件 OTA 通道号。 `0`：主模块固件通道 `1`：蓝牙固件通道 `3`：Zigbee 固件通道 `9`：MCU 固件通道 `>9`：扩展通道。
data.httpsUrl	string	HTTPS 固件 URL 代理地址	是	HTTPS 固件 URL 代理地址。
data.upgradeType	integer	升级类型	是	升级类型。 `0`：App 提醒升级 `1`：设备静默升级 `2`：App 强制升级 `3`：App 检测升级
data.execTime	long	指定执行时间	是	用于静默升级向设备指定升级时间，为 `0` 或者小于当前时间表示立即执行。

上报升级状态或进度

设备发送消息

设备上报固件升级进度。

topic：tylink/${deviceId}/ota/progress/report

上报升级进度

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{
        "channel":0,
        "progress":98
    }
}

上报升级异常状态

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{
        "channel":0,
        "errorCode":42,
        "errorMsg":"下载失败，FLASH 空间不足"
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID，如果是子设备的身份，`deviceId` 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	升级进度信息	是	升级进度信息。
data.channel	number	固件通道号	是	固件 OTA 通道号。 `0`：主模块固件通道 `1`：蓝牙固件通道 `3`：Zigbee 固件通道 `9`：MCU 固件通道 `>9`：扩展通道。
data.progress	integer	升级进度	否	升级中才需要上报升级进度，故升级进度字段只要大于等于 `0`，则表示升级中状态。取值范围：`0`-`100`。
data.errorCode	integer	升级失败异常码	否	若升级异常则必须传 `errorCode` 字段。固件升级异常码如下： `40`：升级失败，未知异常 `41`：下载失败，电量不足 `42`：下载失败，FLASH 空间不足 `43`：下载失败，RAM 申请出错或不足 `44`：下载失败，下载请求超时 `45`：下载失败，数据校验出错 `46`：升级失败，电量不足 `47`：升级失败，RAM 申请出错或不足 `48`：升级失败，版本错误 `49`：升级失败，HMAC 校验错误 `50`：升级失败，网关繁忙，不支持多子设备同时升级
data.errorMsg	string	升级失败原因描述	否	如果发生异常，此字段可承载错误信息，长度不超过 20 个字符。

上报设备固件版本

设备发送消息

升级成功，设备上报固件版本号。

topic：tylink/${deviceId}/ota/firmware/report

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{
        "bizType":"UPDATE",
        "otaChannel":[
            {
                "channel":0,
                "version":"1.1.6"
            },
            {
                "channel":9,
                "version":"1.0.0"
            }
        ]
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备id	是	设备 ID，如果是子设备的身份，`deviceId` 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息的id	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	设备固件版本信息	是	设备固件版本信息。
data.bizType	string	业务类型	是	业务类型。 `INIT`：固件版本初始化 `UPDATE`：固件升级完成版本更新
data.otaChannel	object	固件信息列表	是	固件版本信息列表。
data.otaChannel.channel	number	固件通道号	是	固件 OTA 通道号。 `0`：主模块固件通道 `1`：蓝牙固件通道 `3`：Zigbee 固件通道 `9`：MCU 固件通道 `>9`：扩展通道。
data.otaChannel.version	string	固件版本	是	版本号采用 `xx.yy.zz` 点分表示，范围支持 `0.0.0` 到 `99.99.99`。例如：`1.0.0`。

上一篇子设备上下线

下一篇远程配置