联网固件升级

OTA（Over-the-Air Technology）即空中下载技术，是指通过无线网络从远程服务器下载最新的应用或系统，从而对设备固件实现升级。主要有两个应用场景：修复已知 Bug 和增加新功能。

功能描述

• 支持主联网设备的固件升级。
• 支持多种固件升级方式。

升级方式

根据通知升级方式的不同，有以下升级方式：

• App 提醒升级：用户进入设备面板主动提醒 App 用户，用户可以选择是否升级。

• App 强制升级：升级提醒主动推送给 App 用户，用户无权选择，必须升级。

• App 检测升级：升级提醒不会主动推送给 App 用户，需要用户主动发起版本检测，才能看到升级提醒。

自动升级

自动升级由涂鸦开发者平台 自动升级开关 和 App 端自动升级开关共同决定。

• 如果您在平台配置固件升级时关闭了自动升级，则根据用户配置的升级方式进行升级。
• 如果您在平台配置固件升级时开启了自动升级：
  • 如果用户在 App 端也开启了自动升级，那么设备会在设置的时间段内升级固件，用户无感知。这种升级方式也被称为 静默升级。
  • 如果用户在 App 端没有开启自动升级，则会选择上文描述的 App 强制升级 方式进行升级。

工作原理

升级流程

静默升级触发流程

开发指导

关联头文件

• tuya_iot_wifi_api.h
• base_event_info.h
• tuya_svc_upgrade.h

使用方法

• 由框架管理主联网固件升级

  1. 在涂鸦开发者平台上 创建固件，得到获取固件 key。

  2. 调用 设备初始化接口 时，通过入参传入获取的固件 key。

  3. 如果您想知道固件升级阶段的状态，可通过 事件服务 订阅和 OTA 相关事件。

     // ota
     #define EVENT_OTA_PROCESS_NOTIFY    "ota.process"
     #define EVENT_OTA_FAILED_NOTIFY     "ota.failed"
     #define EVENT_OTA_FINISHED_NOTIFY   "ota.finished"
     

  4. 编译工程，得到升级固件，升级固件带 UG 标识。

  5. 在涂鸦开发者平台 上传固件，并进行升级配置。

• 您自主管理主联网固件升级包

  1. 注册主联网固件升级通知回调，代替框架内部注册的函数。

  2. 在主联网固件升级通知回调里，调用 启动拉取升级固件包数据 的接口，并按照您的需求自行实现相关回调函数。

  3. 在涂鸦开发者平台 创建固件，得到获取固件 key。

  4. 调用 设备初始化接口 时，通过入参传入获取的固件 key。

  5. 编译工程，得到升级固件，升级固件带 UG 标识。

  6. 在涂鸦开发者平台，上传固件，并进行升级配置。

API 说明

注册主联网固件升级通知回调

/**
 * @brief Register pre-precess handler to replace the default one
 *
 * @param[in] pre_ug_cb The new handler
 */
VOID tuya_svc_upgrade_register_pre_cb(DEV_UPGRADE_PRE_INFORM_CB pre_ug_cb);

启动拉取升级固件包数据

/**
 * @brief Start to download the specific firmware
 *
 * @param[in] dev_id ID of sub-device, or NULL for GW
 * @param[in] fw Firmware info to download
 * @param[in] get_file_cb Callback to transfer data while downloading
 * @param[in] pri_data Private data
 * @param[in] upgrd_nofity_cb Callback when update is completed or an error occurs
 * @param[in] upload_upgrade_percent Upload update percent or not
 * @param[in] download_buf_size Buffer size allocated for OTA
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_svc_upgrade_start(CONST CHAR_T *dev_id,
                                   CONST FW_UG_S *fw,
                                   CONST GET_FILE_DATA_CB get_file_cb,
                                   VOID *pri_data,
                                   CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,
                                   CONST BOOL_T upload_upgrade_percent,
                                   CONST UINT_T download_buf_size);

参考示例

下载联网单品框架后，框架的 apps 目录下有所有功能示例代码集合 tuyaos_demo_examples，可参考 examples/service_ota/example_main_ota_custom.c 文件中的代码。关于功能示例代码集合的使用，参考 TuyaOS 示例集合。

常见问题

固件升级失败原因有哪些?

升级失败原因一般有两大类，即固件下载异常和安装异常，大部分都是下载问题。一般升级进度上报到 90% 以上，基本可以认为固件下载完成，否则可以判断设备固件没有下载完成。

• 设备网络问题

  • 距离路由器较远，信号弱，数据传输丢包率较高引起。
  • 网络传输时延较长，丢包率高。
  • 运营商网络不支持断点续传。

• HMAC 签名验证失败

• 设备证书问题

• 代理服务器问题

• 云存储问题

设备检测不到升级？

已发布的固件升级

检查升级是否已经配置规则，以及对应设备是否满足该规则。

未发布的固件升级

• 检查设备是否已加入升级测试白名单。

• 如果白名单页面设备版本显示未知，会造成检测不到升级，一般有以下几种原因，请逐一确认。

  • 设备未激活或者被移除，或者设备不在该数据区。
  • 设备 ID 填写错误。
  • 设备激活上报时，没有上报对应固件的版本号。
  • 如果开启了静默升级，在 App 上是无法检测到该升级的，静默升级是由设备主动发起的升级。

参考文档

• 更多关于固件管理的指导说明，参考 固件管理。
• 更多关于固件升级配置的说明，参考 固件升级。
• 更多关于固件升级常见问题的说明，参考 固件升级-常见问题。