OTA 功能开发

更新时间:2025-07-07 08:17:37下载pdf

概述

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

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

OTA 初始化

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

设置 OTA 回调参数
tuya_ipc_init_sdk

初始化参数中需要设置接收 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,在后台进行配置。
  • 固件替换前,需要备份 DB 文件。固件替换成功后,对比 DB 文件替换固件前后的 MD5 值,若相同,则可以直接重启;若不相同,则将备份的 DB 文件替换现有的 DB 文件,再重启设备。
  • 反初始化的操作不可逆,若 OTA 失败,设备必须进行重启。
  • 升级前建议关闭一些功能(如本地存储、云存等),释放内存空间等资源。
  • 内存资源优化需要在 tuya_ipc_upgrade_sdk 函数前进行。

子设备 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); 实现。

子设备的 OTA 数据获取仍是在主设备中进行。在子设备的 OTA 数据包下载完成后,如何发给子设备需要开发者自行设计实现。

FAQ

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

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