Subordinate Firmware Update

Last Updated on : 2024-04-26 08:41:23download

The main network module can have different subordinate modules (such as controllers and voice modules) mounted to support various use cases. The TuyaOS framework supports OTA updates for the firmware on these modules.


Update channel ID: Used to associate with the channel for updating the device firmware, files, or configurations.

  • Generic channel ID: The fixed channels used to update the specified types of firmware, ranging from 0 to 9.

    Name Channel ID Description
    DEV_NM_ATH_SNGL 0 The update channel for the main network firmware.
    DEV_BLE_SNGL 1 The update channel for the Bluetooth firmware.
    DEV_ZB_SNGL 3 The update channel for the Zigbee firmware.
    DEV_NM_NOT_ATH_SNGL 9 The update channel for the MCU firmware.
  • Custom channel ID: Assigned based on your needs, ranging from 10 to 19.

    Name Channel ID Description
    DEV_ATTACH_MOD_x ≥ 10 The custom update channels.


  • Update the firmware on multiple subordinate modules.

  • Multiple update methods are available.

    The update methods for the subordinate firmware are the same as those for the main network firmware. Subordinate firmware also supports automatic updates.

  • The application can reject an update request.

How it works

The update process and the trigger of silent updates for the subordinate firmware are the same as those for the main network firmware. See How the firmware update works for the main network module.

Framework and application interaction

ApplicationFrameworkRegister update callbacks.Send the update request if the callback has been registered.Check the currentstatus and determinewhether to acceptthe update request.Return the result.Start the updateprocess.Possible reasons such asa low battery.Exit the updateprocess.alt[Accept the update][Reject the update]opt[An update request triggered]Notify the application of the start of the update with information such asfirmware channel ID, update size, and HMAC.Register the parameters and callbacks for update download.Request the packetsfrom the cloud.Pass through the data.Process the data.Send the processing result along with the pending data information.Pass through theremaining and newdata to theapplication in thenext loop.Exit the updateprocess as thefirmware updatefailed.Notify the application of update failure.Continuedownloading theupdate.alt[Application fails to process the data.][Application processes the datasuccessfully.]loop[Download the update in packets.]Process the lastpacket.Update the firmware version number to the latest one.Send the update result.opt[The update is downloaded.]opt[Update process]ApplicationFramework

Development guide

Reference the header

  • tuya_iot_com_api.h
  • tuya_devos_utils.h

How to use

  1. Create firmware on the Tuya IoT Development Platform, choose the firmware type and channel, and obtain the firmware key.

  2. Call the device initialization API.

  3. Register the channel ID and firmware version for the subordinate firmware.

  4. Register the callback gw_ug_cb to get notified when a subordinate firmware update starts.

  5. (Optional) Register the callback pre_gw_ug_cb to get notified when the framework receives an update request.

    To reject an update request, set the return value of this callback to anything other than OPRT_OK.

  6. When notified of the start of a subordinate firmware update, call the API to download the update package.

  7. After the update is installed, update the version number of the subordinate firmware.

API description

Start downloading the subordinate firmware update

* @brief tuya_iot_upgrade_gw_notify
* @desc upgrage gateway firmware
* @param[in] fw: firmware info
* @param[in] get_file_cb: download content storage callback
* @param[in] upgrd_nofity_cb: firmware download finish callback
* @param[in] pri_data: private param of get_file_cb && upgrd_nofity_cb
* @param[in] notify: notify app the upgrade status
* @param[in] download_buf_size: max download buffer size when downloading
* @return OPRT_OK: success Other: fail
OPERATE_RET tuya_iot_upgrade_gw_notify(IN CONST FW_UG_S *fw,
                                       IN CONST GET_FILE_DATA_CB get_file_cb,
                                       IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,
                                       IN CONST PVOID_T pri_data,
                                       BOOL_T notify, UINT_T download_buf_size);
#define tuya_iot_upgrade_gw(fw, get_file_cb, upgrd_nofity_cb, pri_data) \
    tuya_iot_upgrade_gw_notify(fw, get_file_cb, upgrd_nofity_cb, pri_data, TRUE, 0)

Set the version number of subordinate firmware

typedef struct {
    /** attach ota channel */
    /** attach version, format xx.xx.xx */
    CHAR_T ver[SW_VER_LEN + 1];
    CHAR_T md5[SW_MD5_LEN + 1];

* @brief set versions of pointer attach module.
* @param[in] tp: type of attach module
* @param[in] attr: attributes of attach module
* @note This API is used for attach modules updating in case of firmware update
* Info of main network module will also be included when upload.
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
OPERATE_RET tuya_iot_dev_set_attach_attr(GW_PERMIT_DEV_TP_T tp, GW_ATTACH_ATTR_T * attr);


After downloading the Networked Product Development Framework, you can find the example code for all features in the tuyaos_demo_examples folder under the apps directory. See the code in examples/service_ota/example_attach_ota.c. For the usage of the example code, see TuyaOS Example Collection.


The update has been downloaded, but why does the app panel still display update failure?

Check if the version number of the subordinate firmware has been updated. The app determines the update result based on the current version number.

How can I determine the update channel for the subordinate firmware?

  • If the subordinate firmware is in line with Tuya’s generic firmware types (excluding the main network firmware), you can use the corresponding generic channel ID.
  • If your firmware is not one of the generic types, you can use a custom channel.
  • One subordinate module corresponds to one update channel.

What is the thread priority for update tasks?

The priority is THREAD_PRIO_3.

The update task is of the lowest priority in the TuyaOS framework. The OTA task does not automatically enter sleep mode, but it can be blocked when receiving data. If network data is consistently accessible, OTA tasks will not release CPU resources proactively. Tasks with lower priority than THREAD_PRIO_3 may not be executed.

Is it possible to remotely control the device during an update?

The framework does not respond to DP commands during an update.