Network Firmware Update

An OTA update is the wireless delivery of new software, firmware, or other data to connected smart devices. It can be used to fix bugs and add features.

Features

• Update the firmware on the main network module.
• Multiple update methods are available.

Update methods

Three update methods are available based on how an update is notified.

• Update notification: Users are prompted whether to install an update when they open a device panel.

• Forced update: Users receive a firmware update notification and have no option but to update the firmware.

• Check for updates: Users will not receive a firmware update notification, but need to manually check for new updates.

Automatic update

Automatic update is determined by the auto update setting on the Developer Platform and the app together.

Automatic update is determined by the auto update setting on the Tuya Developer Platform and the app together.

• If you disable the automatic update feature on the Tuya Developer Platform, the selected update method will be applied.
• If you enable the automatic update feature on the Tuya Developer Platform:
  • If users enable the automatic update feature on the app, the device firmware will be automatically updated within a specific time. This is also known as a silent update.
  • If users disable the automatic update feature on the app, the forced update will be applied.

How it works

Update process

Silent update process

Development guide

Reference the header

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

How to use

• Framework manages updates for main network firmware

  1. Create firmware on the Developer Platform and obtain the firmware key.

  2. When calling the device initialization API, specify the firmware key in the input parameter.

  3. To get notified of the progress of the update, you can subscribe to OTA events.

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

  4. Compile the project to obtain the update file with UG in its name.

  5. Upload firmware and deploy an OTA update task on the Developer Platform.

• You manage updates for main network firmware

  1. Register the callback for main network firmware updates to replace the existing one in the framework.
  2. In the main network firmware update callback, initiate downloading the firmware update and implement the required callback.
  3. Create firmware on the Developer Platform and obtain the firmware key.
  4. When calling the device initialization API, specify the firmware key in the input parameter.
  5. Compile the project to obtain the update file with UG in its name.
  6. Upload firmware and deploy an OTA update task on the Developer Platform.

API description

Register main network firmware update callback

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

Initiate firmware update download

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

Example

After downloading the Networked Product Development Framework, you can find the example code for all features in the tuyaos_demo_examples folder under the apps directory. See the code in examples/service_ota/example_main_ota_custom.c. For the usage of the example code, see TuyaOS Example Collection.

FAQs

Why do firmware updates fail?

The reasons are broken down into two categories, firmware download issues and installation issues. Most update failures occur due to download issues. If the update progress is reported as above 90%, it can be considered that the firmware download is complete. Otherwise, it is not.

• Device network issues

  • The signal is weak and there is a high packet loss due to the device being far from the router.
  • The long network latency causes high packet loss.
  • The mobile network operator does not support resumable downloads.

• HMAC verification fails.

• Device certificate issue

• Proxy server issue

• Cloud storage issue

Why aren’t updates detected?

If the updates have been released

Check if you have configured an update rule and confirm whether the target device meets this rule.

If the updates are not released

• Check if the target device has been included in the testing allowlist.

• If the device version on the allowlist page is shown as unknown, it could lead to a failure in detecting updates. Confirm each possible reason below.

  • The device is either inactive, removed, or deployed in a different data center.
  • The device ID is incorrect.
  • After being activated, the device does not report the version number of the target firmware.
  • If the silent update is enabled, the app cannot detect updates as they are initiated by the device.

Reference

• For more information about firmware management, see Manage Firmware.
• For more information about firmware update configuration, see Update Firmware.
• For more information about the updates FAQs, see Q&A.