OTA Updates

This topic describes how to update the robot vacuum firmware via OTA. An over-the-air (OTA) update is the wireless delivery of new software, firmware, or other data to connected devices. TuyaOS Robot Vacuum Development Framework provides APIs to help you integrate the OTA update feature into your product easily.

Business logic

The OTA firmware update process involves three components: mobile app, device, and cloud.

• Mobile app: prompts the user with a firmware update notification and displays the update progress.
• Cloud: stores the firmware update, updates the progress, and pushes the update notification.
• Device: receives and installs the firmware update.

Firmware package configuration

1. After a device is paired, you can get its virtual ID from the mobile app to add it to the firmware update allowlist.
2. Build the firmware package, with a version number higher than the currently installed one.
3. Log in to the Tuya Developer Platform. Find the target product and upload the firmware package.
4. For more information, see Manage Firmware and Update Firmware.

Update methods

Tuya provides the following methods to initiate a firmware update on the user side.

• Update notification: When users open the app panel, they receive a firmware update notification. They can then choose whether to install the update.
• Forced update: When users open the app panel, they receive a firmware update notification. They have no option but to update the firmware.
• Check for updates: Users will not receive a firmware update notification, but need to open the app panel of a device and check for updates manually.

Development process

• OTA update condition callback: ty_dev_upgrade_pre_check_cb() is called before each update to verify if the update condition is met. You can add restrictions in this callback.

  /**
   * @brief  The callback for checking if the OTA update condition is met.
   * @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    // Battery level threshold: 30%
      /*The update conditions, such as battery level, device status, etc.*/
      char battery_percentage = 15;  
      if(battery_percentage < BATTERY_CHECK_THREAD) {//Low battery
      return TUS_UPGRADE_ERROR_LOW_BATTERY;
      }
      /*Other conditions you add*/
      return TUS_RD;
  
  }
  

• OTA update request callback: ty_user_upgrade_inform_cb(), with parameters including the firmware download url and the file 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;
  }
  

• In tuya_iot_upgrade_gw_notify, the first callback __ty_user_get_file_data_cb returns file shard data. This function has input and output parameters. The input parameters can be used for your purpose. After you get the output parameters, you need to return whether the data has been written. Return 0 on successful writing.
  The second callback __ty_user_upgrade_notify_cb is used to display the update progress.

• Replace the old firmware with the new one in __ty_user_upgrade_notify_cb. See the demo for details.
  After the firmware is downloaded, you need to implement firmware replacement and restart the device in the specified function.

  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:
          /* Once the OTA file is successfully downloaded to the specified path, you need to perform the OTA update. [ p_mgr_info->upgrade_file_path ]*/
          break;
      case OPRT_COM_ERROR:
  
          break;
      default:
          // Clear the update status when receiving an update failure.
          PR_DEBUG("upgrade https error:%d\n", download_result);
  
          break;
      }
      // Reboot
  
      return OPRT_OK;
  }
  
  

• If the OTA update fails, add the restart operation in __ty_user_upgrade_notify_cb.

  The OTA update is not reversible. If it fails, the device must be restarted.

Custom OTA update progress

• The device downloads firmware through a URL and calls tuya_iot_dev_upgd_progress_rept to report download progress.

  /*
  \fn tuya_robot_upgrade_progress_report
  \brief  Send update progress to the cloud and app.
  \param[in] percent: Update progress in percentage, range [0,100]
  \return SUCCESS - OPERATE_RET, FAIL - COMM ERROR
  */
  OPERATE_RET tuya_robot_upgrade_progress_report(IN UINT_T percent)
  

• The default timeout for OTA updates is 60 seconds. You can specify a timeout value on the Tuya Developer Platform.

FAQs

The app displays the message: Update failed, possibly due to a weak signal. Please check your device’s network and try again. What could be the possible reasons for this?

• Slow internet speeds lead to delays in progress reporting and hinder the download of update packages.
• The update condition is not met. For example, the device is not connected to a charger, or the battery level drops below the set threshold.
• The device does not report the new version number due to an update failure. Or, it takes too long to reconnect to the network after a restart, leading to a timeout in version number reporting.