OTA 功能开发

概述

OTA 即 Over-the-Air，作为设备升级与维护的最重要途径之一，将在本文具体介绍。当有固件需要升级时，SDK 将通过回调的形式告知设备，进行 OTA 操作。

基站或网关等设备的升级，包含主设备和绑定的子设备升级，升级的数据都会在 SDK 中获取到。

OTA 初始化

建议参照以下逻辑顺序初始化 OTA 功能：

初始化参数中需要设置接收 OTA 数据的回调，接口和入参请参考下文介绍。

数据结构与开发建议

回调集合中包含主设备和子设备的回调，请按需设置。

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);

开发指导

主设备和子设备升级回调的实现可参考 Demo。

主设备 OTA

以获取主设备升级数据为例，upgrade_cb 的回调实现可参考如下代码：

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

注意事项

• 主设备收到 OTA 请求后，该回调函数将会执行，传入参数会包含固件下载的 URL（下载链接）以及 Size（文件的大小）。
• tuya_ipc_upgrade_sdk 的功能是通过 URL 下载 OTA 数据包。第一个回调函数 __IPC_APP_get_file_data_cb 用于获取文件分片数据（下载），函数中有入参与出参。入参主要提供开发者使用，出参获取到数据后，需要返回是否已完成数据的写入，写入成功返回 0。
• 第二个回调函数 __IPC_APP_upgrade_notify_cb 用于显示 OTA 升级整体进度，推荐使用 OPERATE_RET tuya_ipc_upgrade_progress_report_by_type(IN UINT_T percent, IN BYTE_T type); 上报升级进度。参数 type 类型为 DEV_TYPE_T，上报的进度值建议小于 99%。
• 固件下载完成后，建议在函数 __IPC_APP_upgrade_notify_cb 中替换新固件。替换成功后，需要在此函数内进行设备的重启操作。
• 若 OTA 升级失败，需要在函数 __IPC_APP_upgrade_notify_cb 中加入重启操作。
• 固件升级时，手机 App 进度显示会暂停在 98%。此时，固件已完成下载，App 正在等待设备重启并上报新固件版本号。版本号上报成功后，App 将显示 升级成功。
• App 等待设备替换固件与上报新版本号的时间为 1 分钟。若设备流程超过此时间，需要告知项目经理 PID，在后台进行配置。

子设备 OTA

子设备升级更新的基本逻辑与主设备相似。开始 OTA 后，子设备回调开始执行 sub_dev_upgrade_cb ，回调函数形式如下所示：

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

• 与主设备升级回调相比，子设备回调中需要注意 dev_id 参数，一般情况下此参数是子设备绑定时的 UUID，即会指定某一具体子设备的升级。
• 可参考主设备升级获取数据包的逻辑实现，即使用 tuya_ipc_upgrade_sdk 下载数据包。
• 上报子设备 OTA 进度可通过 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); 实现。

FAQ

如何实现同一类型子设备批量更新？

SDK 暂不提供此功能，建议自行开发。可以在接收某个子设备数据包后，自行实现同一类别子设备的升级管理。