Subordinate Firmware Update

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.

Terms

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.

Features

• 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

Framework and application interaction

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 */
    GW_PERMIT_DEV_TP_T tp;
    /** attach version, format xx.xx.xx */
    CHAR_T ver[SW_VER_LEN + 1];
    CHAR_T md5[SW_MD5_LEN + 1];
} GW_ATTACH_ATTR_T;

/**
* @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);

Example

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.

FAQs

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.