附属固件升级

随着业务多元化发展，在主联网模组上会挂载多个不同功能的附属模组（如控制器、语音模组等），以便满足各种场景需求。TuyaOS 框架也支持这些模组的固件升级。

名词解释

升级通道号：是涂鸦对设备固件、文件或者配置进行升级通道绑定的一种机制。

• 通用通道号：涂鸦固化的一些通道，用于指定类型的固件升级使用，范围：0-9。

  名称	通道号	描述
  DEV_NM_ATH_SNGL	0	主联网固件升级通道
  DEV_BLE_SNGL	1	蓝牙固件升级通道
  DEV_ZB_SNGL	3	Zigbee 固件升级通道
  DEV_NM_NOT_ATH_SNGL	9	MCU 固件升级通道

• 自定义通道号：您可以根据自己的实际需求进行规划使用，范围：10-19。

  名称	通道号	描述
  DEV_ATTACH_MOD_x	≥ 10	开发者自定义的升级通道

功能描述

• 支持多个附属模组进行固件升级。

• 支持多种固件升级方式。

  附属固件的支持的升级方式和 主联网固件升级方式 保持一致附属固件也支持 自动升级。

• 应用可以拒绝此次升级。

工作原理

框架和应用交互流程

开发指导

关联头文件

• tuya_iot_com_api.h
• tuya_devos_utils.h

使用方法

1. 在涂鸦开发者平台上 创建固件，选择固件类型和固件通道，并得到固件 key。

2. 调用 设备初始化接口。

3. 注册附属固件的通道号以及对应的固件版本。

4. 注册附属固开始升级的通知回调，注册 gw_ug_cb 回调函数。

5. （非必选）如果想在框架收到升级请求时得到通知，您可注册 pre_gw_ug_cb 回调函数。

   如果您想拒绝此次升级，可通过该回调的返回值通知框架，将返回值设置成 非 OPRT_OK 的值。

6. 当收到附属固件开始升级的通知时，调用接口开始拉取附属固件包的数据。

7. 数据包接收完成后，更新附属固件的版本号。

API 说明

启动拉取附属固件包数据

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

设置附属固件的版本号

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

参考示例

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

常见问题

数据包已经拉取完成，为什么 App 面板还显示升级失败？

检查是否更新了附属模组的固件版本号，App 会检测升级后的版本号。

附属固件升级通道如何确定？

• 如果附属模组固件符合涂鸦规划的通用固件类型（除了主联网固件），可以使用对应的通用通道。
• 如果附属模组固件在通用类型中找不到符合的类型，可以使用自定义通道。
• 一个附属模组对应一个升级通道。

升级任务的线程优先级？

升级任务的优先级是 THREAD_PRIO_3。

该任务本身在 TuyaOS 框架内部是优先级最低的。但是 OTA 任务本身不会主动休眠，但会阻塞在网络接收上。因此，如果网络数据始终可用，则理论上 OTA 任务不会主动释放 CPU 资源，比 THREAD_PRIO_3 优先级低的任务可能会得不到执行。

升级中设备无法进行远程控制？

升级中，框架不会响应 DP 指令。