OTA Firmware Updates

An OTA update is the wireless delivery of new software, firmware, or other data to connected IoT devices. It can be used to fix bugs and add features.

This topic describes the MQTT topics and data structures for implementing the OTA update feature. This can allow a device to report the firmware version, download updates, regularly request updates, report the status or progress of updates, and return the new firmware version after the update is finished.

Terms

Term	Description
Update channel	The update channel is used to identify the firmware types. 0: Main module firmware 1: Bluetooth firmware 3: Zigbee firmware 9: MCU firmware > 9: Extended firmware
Push firmware updates	When users initiate a firmware update using a mobile app or SaaS platform, the Tuya IoT Development Platform pushes the update to the target device.
Regularly check for updates	The device proactively or regularly checks for updates without interrupting users’ experience.

OTA update process

The following diagram shows how the OTA updates over MQTT work.

Push firmware updates

Regularly check for updates

Device reports firmware version

The device reports the firmware version information on initialization.

Device sends messages

After activation, the device should report its update channel and firmware version information if it uses the OTA update feature.

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"
            }
        ]
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	If this is a sub-device, the deviceId should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 bits in length. The request and response are associated with a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	Firmware version information	Yes	Firmware version information.
data.bizType	string	Business type	Yes	Business type. INIT: Initialize firmware version. UPDATE: Update firmware version.
data.pid	string	Product ID (PID)	Yes	Product ID (PID)
data.firmwareKey	string	Firmware key	No	If the module firmware can report the firmware key, the firmware key must be specified on initialization.
data.otaChannel	object	Firmware information	Yes	The list of firmware version information.
data.otaChannel.channel	number	Update channel	Yes	OTA update channels. 0: Main module firmware 1: Bluetooth firmware 3: Zigbee firmware 9: MCU firmware > 9: Extended firmware
data.otaChannel.version	string	The firmware version.	Yes	The version number is in the format of xx.yy.zz, ranging from 0.0.0 to 99.99.99. For example, 1.0.0

Cloud pushes OTA updates

Device receives messages

After receiving an update request, the cloud will check for updates and push an OTA update to the device.

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
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	If this is a sub-device, the deviceId should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 bits in length. The request and response are associated with a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	OTA update information	Yes	OTA update information.
data.ctId	string	The traceId of the app that initiates the firmware update.	Yes	This field is used to track logs. You can leave it as is. The traceId only identifies the app that initiates a firmware update, such as bee8d56c2868302ec4d094d652325***.
data.channel	number	Update channel	Yes	OTA update channels. 0: Main module firmware 1: Bluetooth firmware 3: Zigbee firmware 9: MCU firmware > 9: Extended firmware
data.version	string	Firmware version number	Yes	The version number is in the format of xx.yy.zz, ranging from 0.0.0 to 99.99.99. For example, 1.0.0
data.url	string	URL to the firmware	Yes	URL to the firmware.
data.cdnUrl	string	CDN URL to the firmware	Yes	CDN URL to the firmware.
data.size	string	File size	Yes	The unit is in bytes.
data.md5	string	The MD5 hash of the firmware file.	Yes	The MD5 hash of the firmware file.
data.hmac	string	The HMAC key of the firmware file	Yes	The HMAC key is calculated by using sha256_HMAC with the deviceSecret as the secret.
data.httpsUrl	string	HTTPS proxy URL to the firmware	Yes	HTTPS proxy URL to the firmware.
data.upgradeType	integer	Types of updates	Yes	Types of updates. 0: Update notification. 1: Silent updates. 2: Forced update. 3: Manual check for updates.
data.execTime	long	Scheduled update time	Yes	Schedule a silent update to take place at a specific time. A value less than the current time or equal to 0 means to perform an update immediately.

Device requests firmware updates

Device sends messages

The device requests the latest firmware version and URL.

Topic: tylink/${deviceId}/ota/get

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

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	If this is a sub-device, the deviceId should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 bits in length. The request and response are associated with a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	OTA update parameters	No	OTA update parameters.

Device receives messages

The device receives the latest firmware version and 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
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	Device ID	Yes	If this is a sub-device, the deviceId should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 bits in length. The request and response are associated with a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	OTA update information	Yes	OTA update information.
data.url	string	URL to the firmware	Yes	URL to the firmware.
data.cdnUrl	string	CDN URL to the firmware	Yes	CDN URL to the firmware.
data.size	string	File size	Yes	The unit is in bytes.
data.md5	string	The MD5 hash of the firmware file.	Yes	The MD5 hash of the firmware file.
data.hmac	string	The HMAC key of the firmware file	Yes	The HMAC key is calculated by using sha256_HMAC with the deviceSecret as the secret.
data.version	string	Firmware version number	Yes	The version number is in the format of xx.yy.zz, ranging from 0.0.0 to 99.99.99. For example, 1.0.0
data.channel	number	Update channel	Yes	OTA update channels. 0: Main module firmware 1: Bluetooth firmware 3: Zigbee firmware 9: MCU firmware > 9: Extended firmware
data.httpsUrl	string	HTTPS proxy URL to the firmware	Yes	HTTPS proxy URL to the firmware.
data.upgradeType	integer	Types of updates	Yes	Types of updates. 0: Update notification. 1: Silent updates. 2: Forced update. 3: Manual check for updates.
data.execTime	long	Scheduled update time	Yes	Schedule a silent update to take place at a specific time. A value less than the current time or equal to 0 means to perform an update immediately.

Device reports the update status or progress

Device sends messages

The device reports the progress of the firmware update.

Topic: tylink/${deviceId}/ota/progress/report

Report the progress of the firmware update

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

Report errors occurred during the firmware update

{
    "msgId":"45lkj3551234***",
    "time":1626197189638,
    "data":{
        "channel":0,
        "errorCode":42,
        "errorMsg":"Download failed due to insufficient flash memory"
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	If this is a sub-device, the deviceId should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 bits in length. The request and response are associated with a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	Update progress	Yes	The progress of the firmware update.
data.channel	number	Update channel	Yes	OTA update channels. 0: Main module firmware 1: Bluetooth firmware 3: Zigbee firmware 9: MCU firmware > 9: Extended firmware
data.progress	integer	Update progress	No	The device reports the progress when a firmware update is performed. As long as this field is greater than or equal to 0, it means the update is in progress. Valid values range from 0 to 100.
data.errorCode	integer	Error codes for failed firmware update	No	If the firmware update failed, errorCode must be passed. Error codes: 40: Update failed due to unknown reasons. 41: Download failed due to low battery. 42: Download failed due to insufficient flash memory. 43: Download failed due to insufficient RAM or failed RAM allocation. 44: Download failed due to download request timeout. 45: Download failed due to data verification error. 46: Update failed due to low battery. 47: Update failed due to insufficient RAM or failed RAM allocation. 48: Update failed due to version error. 49: Update failed due to HMAC verification error. 50: Update failed due to the gateway being busy. Multiple sub-devices cannot be updated at the same time.
data.errorMsg	string	Possible reasons for update failure	No	This field is used to present an error code to users, with no more than 20 characters.

Device reports firmware version

Device sends messages

The device reports the current firmware version number after the update is installed.

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"
            }
        ]
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	Device ID	Yes	If this is a sub-device, the deviceId should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 bits in length. The request and response are associated with a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	Firmware version information	Yes	Firmware version information.
data.bizType	string	Business type	Yes	Business type. INIT: Initialize firmware version. UPDATE: Update firmware version.
data.otaChannel	object	Firmware information	Yes	The list of firmware version information.
data.otaChannel.channel	number	Update channel	Yes	OTA update channels. 0: Main module firmware 1: Bluetooth firmware 3: Zigbee firmware 9: MCU firmware > 9: Extended firmware
data.otaChannel.version	string	The firmware version.	Yes	The version number is in the format of xx.yy.zz, ranging from 0.0.0 to 99.99.99. For example, 1.0.0