OTA Update

Overview

This topic describes how to develop the over-the-air (OTA) update feature, which serves as one of the most critical methods for device updates and maintenance. When the SDK detects firmware updates, it will notify the device of OTA updates through a callback.

For updates of base stations, gateways, or similar devices, including both the main device and its bound sub-devices, all update data will be retrieved through the SDK.

OTA initialization

It is recommended to initialize the OTA feature according to the following logical order.

In the initialization parameters, you must set the callback for receiving OTA data. For the interface specification and input parameters, refer to the following section.

Data structure and development suggestions

The callback set includes handlers for both main devices and sub-devices. Configure them according to your requirements.

typedef struct {
    TUYA_IPC_SDK_DEV_UPGRADE_INFORM_CB upgrade_cb;      // main dev upgrade info
    TUYA_IPC_SDK_DEV_UPGRADE_INFORM_CB pre_upgrade_cb;  // main dev upgrade enable query

    TUYA_IPC_SDK_SUB_DEV_UPGRADE_INFORM_CB sub_dev_upgrade_cb;       // sub-dev upgrade info
    TUYA_IPC_SDK_SUB_DEV_UPGRADE_INFORM_CB pre_sub_dev_upgrade_cb;   // sub-dev upgrade enable query
} TUYA_IPC_SDK_UPGRADE_T;

typedef struct {
.
.
.
    TUYA_IPC_SDK_UPGRADE_T  upgrade_cb_info;    ///< OTA callback function, triggered by upgrading from app and Tuya cloud
.
.
.
} TUYA_IPC_ENV_VAR_T;

/**
 * @brief Initialize Tuya SDK for embedded devices
 *
 * @param[in] p_var: TUYA_IPC_ENV_VAR_T
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_init_sdk(IN CONST TUYA_IPC_ENV_VAR_T *p_var);

Development guide

Refer to the demo to learn how to implement the update callbacks for main devices and sub-devices.

Main device OTA updates

For example, get the update data of the main device. Refer to the callback implementation of upgrade_cb in the following code:

INT_T TUYA_IPC_Upgrade_Inform_cb(IN CONST FW_UG_S *fw)
{
    PR_DEBUG("Rev Upgrade Info");
    PR_DEBUG("fw->fw_url:%s", fw->fw_url);
    PR_DEBUG("fw->sw_ver:%s", fw->sw_ver);
    PR_DEBUG("fw->file_size:%u", fw->file_size);

    tuya_ipc_upgrade_sdk(fw, __IPC_APP_get_file_data_cb, __IPC_APP_upgrade_notify_cb, NULL);

    return OPRT_OK;
}

Things to note

• After the main device receives an OTA request, this callback will be triggered. The input parameters include the URL (download link) of the firmware download and the size (file size).
• tuya_ipc_upgrade_sdk is specifically designed for secure OTA package download via URL. The first callback function __IPC_APP_get_file_data_cb is used to get file sharding data (download). This function has input and output parameters. The input parameters can be used for your purpose. After you get the output parameters, you need to return whether the data has been written. Return 0 on successful writing.
• The second callback function __IPC_APP_upgrade_notify_cb is used to show the overall progress of the OTA update. It is recommended to use OPERATE_RET tuya_ipc_upgrade_progress_report_by_type(IN UINT_T percent, IN BYTE_T type); to report the update progress. The parameter type is DEV_TYPE_T, and the reported progress value is recommended to be less than 99%.
• After the firmware is downloaded, you can replace the old firmware with the new one in the function __IPC_APP_upgrade_notify_cb. After the replacement is successful, restart the device in this function.
• If the OTA update fails, add the restart operation in __IPC_APP_upgrade_notify_cb.
• When the firmware is being updated, the progress displayed on the app will pause at 98%. At this time, the firmware has been downloaded, and the app is waiting for the device to be restarted and send the new firmware version number. After receiving the new version number, the app will display a successful update.
• Generally, the app waits one minute for the device to replace the firmware and report the new version number. If the waiting time of your device exceeds one minute, you can contact the project manager to configure the PID in the backend.

Sub-device OTA updates

The basic logic of sub-device updates is similar to that of the main device. After starting the OTA update, the sub-device starts running sub_dev_upgrade_cb. The callback function format is as follows:

INT_T TUYA_IPC_subdev_upgrade_cb(CONST CHAR_T *dev_id, CONST FW_UG_S *fw)
{
    // The developer needs to implement the operation of sub_dev OTA upgrade,
    // Refer to the "tuya_ipc_upgrade_sdk" to obtain the firmware data of the sub-device,
    //The "pri_data" parameter is used to pass the dev_id of the sub-device to ensure the uniqueness of the firmware of the sub-device.
    // In addition, it is recommended to use "tuya_ipc_upgrade_progress_report_by_sub_dev_type" to report the OTA progress of the sub-device

    return OPRT_OK;
}

• Compared with the main device, the sub-device callback requires special attention to the dev_id parameter. Typically, this parameter is the UUID assigned during sub-device binding, which specifies the target sub-device for updating.
• Refer to how the main device gets data packets, that is, use tuya_ipc_upgrade_sdk to download data packets.
• Use OPERATE_RET tuya_ipc_upgrade_progress_report_by_sub_dev_type(IN CONST CHAR_T *dev_id, IN UINT_T percent, IN BYTE_T type); to report the sub-device OTA update progress.

FAQs

How to update sub-devices of the same type in bulk?

The SDK does not currently provide this feature, so you need to develop it yourself. After receiving the data packets of a specific sub-device, you can manage the updates of sub-devices of the same type.