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, false, 0);
  
      return 0;
  }
  

• tuya_iot_upgrade_gw_notify is used to register callback functions related to OTA upgrades.

  /***********************************************************
  *  Function: tuya_iot_upgrade_gw->tuya iot upgrade gateway
  *  Input: fw->fireware upgrade
  *         get_file_cb->get file callback
  *         upgrd_nofity_cb->upgrade notify callback
  *         pri_data->private data
  *  Output: none
  *  Return: OPERATE_RET
  ***********************************************************/
  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)
  

  Parameters

  Parameter	Description
  fw	Firmware upgrade information structure.
  get_file_cb	Used to obtain file shard data. This function contains input and output parameters: input parameters are provided for your use; after you obtain the data, the output parameter needs to return whether the data writing is completed, and return 0 for a successful write.
  upgrd_nofity_cb	Used to display the overall progress of OTA upgrades.
  pri_data	Private data.
  notify	Progress report control flag. TRUE means to use the built-in progress report logic of the SDK, and the SDK will automatically report the upgrade progress; FALSE means the business layer can customize the progress report logic.
  download_buf_size	Download buffer size.

• 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 error message of failed update due to a weak signal. What could be the possible reasons for this?

When the error Update failed, possibly due to a weak signal. Please check your device’s network and try again. occurs, you can refer to the following possible reasons:

• 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.

How to exit the current upgrade process on the device?

You can call the following API once to terminate the current upgrade. However, it should be noted that the progress bar must not be reported again after calling this API; otherwise, the app will still display that the device is in the upgrading state.

/**
 * @brief tuya_iot_refuse_upgrade
 *
 * @param[in] fw Upgrade parameters
 * @param[in] dev_id Device ID
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_iot_refuse_upgrade(IN CONST FW_UG_S *fw, IN CONST CHAR_T *dev_id);