OTA Updates

This topic describes how to update firmware over-the-air (OTA).

Overview

Concepts

OTA technology enables the device firmware to be updated wirelessly. You can use Tuya-enabled gateways or the Tuya Smart app to deliver updates to devices, continuously enhancing the user experience.

OTA update process

Source code

The OTA update logic for TuyaOS Bluetooth Low Energy (LE) is handled by the component tuya_ble_ota.c. The logic applies to all the chip platforms. The storage logic is handled by tkl_ota.c, while the processing logic varies by chip platform.

Data structure

tuya_ble_ota_data_type_t

typedef enum {
    TUYA_BLE_OTA_REQ,
    TUYA_BLE_OTA_FILE_INFO,
    TUYA_BLE_OTA_FILE_OFFSET_REQ,
    TUYA_BLE_OTA_DATA,
    TUYA_BLE_OTA_END,
    TUYA_BLE_OTA_UNKONWN,
} tuya_ble_ota_data_type_t;

• TUYA_BLE_OTA_REQ: Requests to initiate an OTA update.
• TUYA_BLE_OTA_FILE_INFO: Reads the OTA update information.
• TUYA_BLE_OTA_FILE_OFFSET_REQ: Reads the OTA update offset.
• TUYA_BLE_OTA_DATA: Writes the OTA data.
• TUYA_BLE_OTA_END: Finishes the OTA update.
• TUYA_BLE_OTA_UNKONWN: Unknown status.

tuya_ble_ota_data_t

typedef struct {
    tuya_ble_ota_data_type_t type;
    UINT16_T data_len;
    UINT8_T *p_data;
} tuya_ble_ota_data_t;

• type: See tuya_ble_ota_data_type_t.
• data_len: The length of the OTA data.
• p_data: The OTA data.

API description

Macro on/off

TUYA_BLE_FEATURE_OTA_ENABLE

Receive data

API description

UINT32_T tuya_ble_ota_handler(tuya_ble_ota_data_t* ota);

Direction

Parameter description

Parameter	Description
ota	The data of the OTA update protocol.

Return response

API description

tuya_ble_status_t tuya_ble_ota_response(tuya_ble_ota_response_t *p_data);

Direction

Parameter description

Parameter	Description
p_data	The response to the OTA update request.

Process OTA update request

API description

STATIC UINT32_T tuya_ble_ota_req_handler(UINT8_T* cmd, UINT16_T cmd_size, tuya_ble_ota_response_t* rsp)

Direction

Parameter description

Parameter	Description
cmd	The protocol content for the respective command.
cmd_size	The length of the protocol content for the respective command.
rsp	The response to the protocol content for the respective command.

Process OTA update information

API description

STATIC UINT32_T tuya_ble_ota_file_info_handler(UINT8_T* cmd, UINT16_T cmd_size, tuya_ble_ota_response_t* rsp)

Direction

Parameter description

Parameter	Description
cmd	The protocol content for the respective command.
cmd_size	The length of the protocol content for the respective command.
rsp	The response to the protocol content for the respective command.

Process OTA update offset

API description

STATIC UINT32_T tuya_ble_ota_file_offset_handler(UINT8_T* cmd, UINT16_T cmd_size, tuya_ble_ota_response_t* rsp)

Direction

Parameter description

Parameter	Description
cmd	The protocol content for the respective command.
cmd_size	The length of the protocol content for the respective command.
rsp	The response to the protocol content for the respective command.

Process OTA update data

API description

STATIC UINT32_T tuya_ble_ota_data_handler(UINT8_T* cmd, UINT16_T cmd_size, tuya_ble_ota_response_t* rsp)

Direction

Parameter description

Parameter	Description
cmd	The protocol content for the respective command.
cmd_size	The length of the protocol content for the respective command.
rsp	The response to the protocol content for the respective command.

Finish OTA update

API description

STATIC UINT32_T tuya_ble_ota_end_handler(UINT8_T* cmd, UINT16_T cmd_size, tuya_ble_ota_response_t* rsp)

Direction

Parameter description

Parameter	Description
cmd	The protocol content for the respective command.
cmd_size	The length of the protocol content for the respective command.
rsp	The response to the protocol content for the respective command.

Get information about existing firmware

API description

OPERATE_RET tkl_ota_get_old_firmware_info(TUYA_OTA_FIRMWARE_INFO_T **info)

This API is used for OTA resumable transfer.

Parameter description

Parameter	Description
info	The information about the OTA update that has been downloaded.

How to use

Communication process

Code development

The macro TUYA_BLE_FEATURE_OTA_ENABLE is enabled by default.

See the example in tuya_ble_protocol_callback.c.

STATIC VOID_T tuya_ble_protocol_callback(tuya_ble_cb_evt_param_t* event)
{
    switch (event->evt) {
        …………

        case TUYA_BLE_CB_EVT_OTA_DATA: {
            if (event->ota_data.p_data[0] == 0) {
#if defined(TUYA_BLE_FEATURE_OTA_ENABLE) && (TUYA_BLE_FEATURE_OTA_ENABLE == 1)
                tuya_ble_ota_handler(&event->ota_data);
#endif
            } else {
                …………
            }
        } break;

        …………

        default: {
            TAL_PR_INFO("tuya_ble_protocol_callback Unprocessed event type 0x%04x", event->evt);
        } break;
    }
}

VOID_T tuya_ble_protocol_init(VOID_T)
{
    …………
#if defined(TUYA_BLE_FEATURE_OTA_ENABLE) && (TUYA_BLE_FEATURE_OTA_ENABLE == 1)
    tuya_ble_ota_init();
#endif
    …………
}

Functional testing

Prerequisites

• You have installed the Smart Life app on your phone.
• Your device has been paired.
• Create a product to get the PID.

Procedure

1. Write the license to the device for authorization.

2. Open the Tuya IoT Development Platform. In the development process of the target product, under the Hardware Development tab, choose TuyaOS for access mode and select the hardware based on the chip platform you use.

3. Click Add Custom Firmware and complete the required information.

4. Click New Firmware Version. Complete the required information, upload the firmware update, and enable the firmware.

5. Click OTA Updates. Click New Update Deployment and complete the required settings.

   

6. Click Verify > Add by Device ID.

   

7. Open the device panel on the mobile app and tap the pencil icon in the top right corner. Tap Device Information, copy the Virtual ID, and paste it into the dialog in the previous steps.

   

8. On the mobile app, go back to the previous page and tap Device Update. Tap Update and wait for it to complete.

   

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.