OTA 升级

本文介绍扫地机固件 OTA 升级的实现流程。OTA（Over-the-Air）即空中下载技术，通过网络远程为设备更新和升级软件程序。TuyaOS 扫地机开发框架提供简易的 OTA 接口，让您的产品快速集成 OTA 功能。

业务基本链路

设备升级过程涉及手机 App、设备和云端。

• 手机 App：升级进度结果的展示或者升级消息的发起者。
• 云端：升级过程中的管理者，负责升级固件的存储、设备升级状态的更新以及升级文案的推送。
• 设备：固件升级的执行者，负责接收固件。

固件包配置

1. 设备配网成功后，从 App 上获取设备信息里的虚拟 ID，作为固件升级的白名单。
2. 编译出要升级的固件包，固件版本要高于设备中运行的固件版本。
3. 登录 涂鸦开发者平台 ，到对应创建的产品下，上传配置固件包。
4. 其他操作，参考 固件管理 和 固件升级。

升级方式

设备固件上传到云端后，设备不会立即收到升级消息。目前，涂鸦支持以下升级方式：

• App 提醒升级：用户打开设备面板时，会收到升级提醒弹框，可选择升级或不升级。
• App 强制升级：用户打开设备面板时，会收到升级提醒弹框。只能选择升级，否则设备无法操作。
• App 检测升级：App 用户打开对应设备的面板，然后单击右上角进入设备信息界面，检测设备固件版本，主动更新。

开发流程

• OTA 升级条件回调函数：ty_dev_upgrade_pre_check_cb()，每次升级前会先调用该函数，来判断是否符合升级条件。您可以在该回调中加入限制条件。

  /**
   * @brief  OTA 前检查设备状态是否符合升级的回调
   * @param  [TY_SDK_FW_UG_T] *fw
   * @return [*]
   */
  INT_T ty_dev_upgrade_pre_check_cb(IN CONST FW_UG_S *fw)
  {
      #define BATTERY_CHECK_THREAD   30    //升级电量限制 30%
      /*可以在此处判断是否符合升级条件，例如电量、机器状态等*/
      char battery_percentage = 15;  
      if(battery_percentage < BATTERY_CHECK_THREAD) {//电量不足
      return TUS_UPGRADE_ERROR_LOW_BATTERY;
      }
      /*其他升级条件由您自己添加*/
      return TUS_RD;
  
  }
  

• OTA 升级请求回调函数：ty_user_upgrade_inform_cb()，传入参数包含固件下载的 url（下载链接）以及 size（文件的大小）。

  INT_T ty_user_upgrade_inform_cb(IN CONST FW_UG_S *fw)
  {
      OPERATE_RET ret = OPRT_OK;
  
      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_iot_upgrade_gw_notify(fw, __ty_user_get_file_data_cb, __ty_user_upgrade_notify_cb, NULL, true, 0);
  
      return 0;
  }
  

• 函数 tuya_iot_upgrade_gw_notify 中，第一个回调函数 __ty_user_get_file_data_cb 是用于获取文件分片数据。函数中有入参与出参，入参主要提供给您使用，出参由您获取到数据后，需要返回是否已完成数据的写入，写入成功返回 0。
  第二个回调函数 __ty_user_upgrade_notify_cb 是用于显示 OTA 升级整体进度。

• 在函数 __ty_user_upgrade_notify_cb 中替换新固件，具体实现参考 Demo。
  固件下载完成后，需要您在函数中实现固件的具体替换过程，替换成功后，需要在此函数内进行设备的重启操作。

  OPERATE_RET __ty_user_upgrade_notify_cb(IN CONST FW_UG_S *fw, IN CONST INT_T download_result, IN PVOID_T pri_data)
  {
  
      PR_DEBUG("Upgrade Finish");
      PR_DEBUG("download_result:%d fw_url:%s", download_result, fw->fw_url);
  
      switch (download_result) {
      case 0:
          /* 当 OTA 文件成功下载到指定路径后，您需要执行 OTA 升级操作 [ p_mgr_info->upgrade_file_path ]*/
          break;
      case OPRT_COM_ERROR:
  
          break;
      default:
          // 收到升级失败指令，清空升级状态
          PR_DEBUG("upgrade https error:%d\n", download_result);
  
          break;
      }
      //重启系统
  
      return OPRT_OK;
  }
  
  

• 若 OTA 升级失败，需要在函数 __ty_user_upgrade_notify_cb 中加入重启操作。

  OTA 升级操作不可逆，若 OTA 失败，设备必须进行重启。

OTA 自定义进度上报开发

• 设备端通过 URL 开始下载固件，调用 tuya_iot_dev_upgd_progress_rept 函数，上报 OTA 下载的进度。

  /*
  \fn tuya_robot_upgrade_progress_report
  \brief 发送升级进度到 cloud 和 app
  \param[in] percent：升级进度百分比，有效值[0,100]
  \return SUCCESS – OPERATE_RET，FAIL – COMM ERROR
  */
  OPERATE_RET tuya_robot_upgrade_progress_report(IN UINT_T percent)
  

• 固件超时时间默认为 60 秒。若设备升级流程超过 60 秒时间，前往 涂鸦开发者平台 配置。

FAQs

App 界面提示 升级失败，可能由于信号太弱，请检查设备网络后重新尝试，原因有哪些？

可能原因如下：

• 网速问题，导致进度上报不及时或者升级包下载不通畅。
• 设备升级条件不满足，更多是由于业务上的逻辑限制。例如，未连接充电桩或者电量低于设定阈值。
• 版本号上报超时，设备升级失败导致没有上报新的版本号或设备重启后很长时间才连上网络。