OTA Firmware Updates

Last Updated on : 2024-06-19 06:29:34download

An OTA update is the wireless delivery of new software, firmware, or other data to connected smart 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 Developer 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

OTA Firmware Updates

Regularly check for updates

OTA Firmware 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