Update Firmware

Tuya Developer Platform provides the over-the-air (OTA) firmware update feature for you to update the firmware version of delivered devices after a respective product is released. This topic describes firmware update methods that match different development solutions, the OTA process and interaction protocol for each update method, and how to port the OTA feature based on Tuya’s Bluetooth SDK.

OTA update methods

Module OTA update

Tuya standard module

If Tuya’s standard Bluetooth module is used, the respective Bluetooth module SDK encapsulates the implementation of OTA updates. Therefore, the module natively supports the OTA firmware update capability. You can upload the target firmware to perform OTA update tasks on the Tuya Developer Platform. For more information, see Procedure.

Proprietary module

If a proprietary module is used, you need to implement the OTA feature that matches the chip platform by calling Tuya’s Bluetooth SDK. Then, you can create OTA update tasks on the Tuya Developer Platform.

Tuya’s OTA process, interaction protocol, and OTA update APIs in the Bluetooth SDK will be described later. You can follow these instructions to implement the OTA update program.

MCU OTA update

Tuya Bluetooth SDK has implemented the OTA update program for a microcontroller unit (MCU) and a Bluetooth module. The SDK interacts with the MCU to transmit OTA update files and other data through serial communication. This update method allows you to update firmware on the Tuya Bluetooth module and your proprietary module, as well as the MCU.

In addition, follow the instructions on MCU OTA updates in Bluetooth Serial Communication Protocol and implement the serial communication program and OTA data processing program on the MCU. This way, the MCU OTA method is implemented. You can also go to Tuya Developer Platform > Product > Tuya OS > Development > Hardware Development, and specify MCU SDK as SelectedCloud AccessMode. This allows you to download the MCU SDK in the Development Documents section. The MCU SDK already implements the framework for serial communication and OTA update based on the Bluetooth serial protocol and OTA update protocol. You only need to implement the features such as Universal Asynchronous Receiver/Transmitter (UART) communication and flash memory reading and writing that adapt to the MCU platform. This ensures quick integration with the MCU OTA update capability. For more information, see MCU SDK Migration Guide.

If you do not require OTA data transmission through serial ports, follow the instructions in Port MCU OTA to port the communication program.

OTA update process

Update process

Procedure

Add firmware version

1. To update firmware, the new firmware version must be uploaded to the Tuya Developer Platform. Before the firmware is uploaded, update the firmware to the target version number. Specifically, modify the values of TY_DEVICE_FVER_NUM and TY_DEVICE_FVER_STR in the file tuya_ble_sdk_demo.h. In the following example, the firmware is updated to v0.2.

   /* Set the firmware version number, which must be identical to the one specified when you add firmware. */
   #define TY_DEVICE_FIR_NAME    "ble_module_sdk_development_demo"
   #define TY_DEVICE_FVER_NUM    0x00000002
   #define TY_DEVICE_FVER_STR    "0.2"
   

   For Bluetooth Low Energy (LE) firmware, the version number is in the format bv.sv (0.0 to 99.99). In actual scenarios, the officially released version is v1.0 or higher. Modify the version number against the following table and compile code to generate the new firmware. This process is known as the firmware update.

   Version update	TY_DEVICE_FVER_NUM	TY_DEVICE_FVER_STR
   1.0 > 1.1	0x00000100 > 0x00000101	"1.0" > "1.1"
   2.10 > 3.0	0x0000020A > 0x00000300	"2.10" > "3.0"

2. Go to Tuya Developer Platform > Firmware Management, find the target firmware, and then click Create Version.

   

3. In the Add Firmware Version drawer that appears on the right, enter the version number identical to that specified in the firmware and upload the firmware. Finish other content and click Save & Enabled.

   

4. Set Deployment Scope and click Save and Enable to see the following result. You can also choose Firmware Management > Details to see this page. The Add Firmware Version button is also available on this page.

   

Create update task

1. In the left-side navigation pane, click Product > Device > Firmware Update to go to the Firmware Update page.

2. Choose the target product from the Change Product drop-down list, select its firmware to be updated, and then click New Update Deployment.

   

3. In the New Update Deployment drawer that appears, enter the required information and click OK. In the following example, Update Method is set to Update Notification.

   

4. Before the update task is released, verify the update task by using a test device. Click Verify as denoted in the following figure to enter the device verification page.

   

Verify updates

1. Click Add by Device ID, and in the dialog box, enter the virtual ID of the test device.

   

   The virtual device ID can be obtained from the device panel, as shown in the following figures.

   

2. After the virtual device ID is added, go to the Smart Life app and open the device panel to see the update notification. Follow the instructions to finish the update.

   

3. Return to the Tuya Developer Platform, go to the Verification of test equipment page, and then click Verify Update to see the verified test result.

   

Release firmware update

On the Firmware Update page, click Release to open the Release a new version page, choose between canary release or full release as needed, and then click Submit.

OTA protocol

This section describes the communication protocol between the Smart Life app and Tuya’s Bluetooth module during the OTA firmware update. If Tuya’s Bluetooth module SDK is used, you can check the respective macros and variables against the identifiers listed in the following tables.

Data format

Frame format

Field	Number of bytes	Description
type	1	The OTA data transfer type, defined by tuya_ble_ota_data_type_t.
data_len	2	The length of OTA data. It is the number of bytes used by p_data.
p_data	data_len	The OTA data. For more information, see Interaction protocol.

OTA command

The OTA command is defined by tuya_ble_ota_data_type_t as described in the following table.

OTA command	Identifier	Command
OTA update request	TUYA_BLE_OTA_REQ	0x00
Information about OTA update file	TUYA_BLE_OTA_FILE_INFO	0x01
Offset of OTA update file	TUYA_BLE_OTA_FILE_OFFSET_REQ	0x02
OTA update data	TUYA_BLE_OTA_DATA	0x03
OTA update result	TUYA_BLE_OTA_END	0x04

Interaction protocol

OTA update request

Mobile app to device communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.

Device to mobile app communication

p_data	Number of bytes	Identifier	Description
[0]	1	flag	The flag of the response to an update request. 00: accepts the update. 01: rejects the update.
[1]	1	ota_version	The major version of the OTA protocol. For example, 03 represents the OTA protocol v3.x.
[2]	1	type	It is fixed to 0.
[3:6]	4	version	The version number of the current firmware, in big-endian format. For example, 00 00 02 0A represents 2.10.
[7:8]	2	package_maxlen	The size of the largest packet that can be transmitted over the serial port. The maximum length is 512 bytes for the current protocol version.

Information about OTA update file

Mobile app to device communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1:8]	8	pid	The PID of the product. The reserved field. For an OEM product, the PID might not match the one written to the device. We recommend that you skip PID verification and ignore this parameter during an OTA update.
[9:12]	4	version	The version number of the update file, in big-endian format. For example, 00 00 03 00 represents 3.0.
[13:28]	16	md5	The MD5 hash of the update file.
[29:32]	4	file_len	The length of the update file.
[33:36]	4	crc32	The CRC32 checksum.

Device to mobile app communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1]	1	state	The update status. Valid values: 00: The update is performed as expected. 01: The received PID does not match the one written to the device. 02: The update version is earlier than or equal to the current version. 03: The update size exceeds the upper limit.
[2:5]	4	old_file_len	The size of the update that has already been downloaded. It is used for resumable transfer. Based on this size, the app calculates the CRC32 checksum of the new file.
[6:9]	4	old_crc32	The CRC32 checksum of the update that has already been downloaded. It is used for resumable transfer. After receiving the response message, the app compares this CRC32 checksum to the calculated one.
[10:25]	16	old_md5	The MD5 hash value of the update that has already been downloaded. (Not used currently)

Offset of OTA update file

Mobile app to device communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1:4]	4	offset	The offset of the update file.

Device to mobile app communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1:4]	4	offset	The start offset specified by the device. The start offset address specified by the device takes precedence over the one provided by the app. The device-specified offset is usually less than the one provided by the app.

Data of OTA update file

Mobile app to device communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1:2]	2	pkg_id	The ID of a data packet. The packet ID starts with zero, in big-endian (high byte first) format.
[3:4]	2	len	The size of the current packet n.
[5:6]	2	crc16	The CRC16 checksum of the current packet.
[7:(7+n-1)]	n	data	The current data packet.

Device to mobile app communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1]	1	state	The update status. Valid values: 00: The update is performed as expected. 01: Packet ID error. 02: The data length does not match the expected one. 03: CRC check failed. 04: An exception occurs during an update process.

OTA update result

Mobile app to device communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.

Device to mobile app communication

p_data	Number of bytes	Identifier	Description
[0]	1	type	It is fixed to 0.
[1]	1	state	The update status. Valid values: 00: The update is performed as expected. 01: The total data length error. 02: The total CRC check failed. 03: Other errors have occurred while processing your request.

OTA update implementation

Port program for module OTA update

If a proprietary module is used for development, you need to follow the instructions in the OTA update protocol section and develop the module OTA update feature based on Tuya’s Bluetooth SDK. You can go to Tuya Developer Platform > Product > Tuya OS > Development > Hardware Development, and download a Bluetooth module SDK for reference. You can also port the OTA update program as instructed in this section.

Entry point function

Initialization

After the SDK is initialized, add the OTA update initialization function.

void tuya_ble_sdk_demo_init(void)
{
	/* ... */
	tuya_ble_sdk_init(&tuya_ble_device_param);              /* SDK initialization */
	tuya_ble_callback_queue_register(tuya_ble_sdk_callback);/* Register the message callback */
	tuya_ble_ota_init();                                    /* OTA update initialization */
	/* ... */
}

The sample code of the OTA update initialization uses the TLSR825x platform:

uint32_t tuya_ble_ota_init(void)
{
	s_old_file = &s_old_file_info;            /* Get the address of the OTA update file already downloaded */
	tuya_ble_ota_info_load();                 /* Load information about the OTA update file already downloaded */
	s_ota_state = TUYA_BLE_OTA_STATE_UNKNOWN; /* Set initial state for processing OTA update */
	return 0;
}

Callback

The application receives the update through the registered callback if no RTOS is used or through the registered message queue if an RTOS is used. The event ID is TUYA_BLE_CB_EVT_OTA_DATA. The OTA update handler function is added to this event.

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt) {
	case TUYA_BLE_CB_EVT_OTA_DATA: {
		/* Add the OTA update handler function to the OTA update event */
		tuya_ble_ota_handler(&event->ota_data);
	} break;
	/* ... */
}

The sample code of OTA update handler function uses the TLSR825x platform:

void tuya_ble_ota_handler(tuya_ble_ota_data_t *ota)
{
    /* Response data returned by the device */
    tuya_ble_ota_response_t rsp;
    rsp.type = ota->type;
    /* Process OTA update based on the OTA data transfer type */
    switch(ota->type) {
        /* OTA update request */
        case TUYA_BLE_OTA_REQ: {
            tuya_ble_ota_req_handler(ota->p_data, ota->data_len, &rsp);
        } break;
        /* Information about the OTA update file */
        case TUYA_BLE_OTA_FILE_INFO: {
            tuya_ble_ota_file_info_handler(ota->p_data, ota->data_len, &rsp);
        } break;
        /* Offset of the OTA update file */
        case TUYA_BLE_OTA_FILE_OFFSET_REQ: {
            tuya_ble_ota_file_offset_handler(ota->p_data, ota->data_len, &rsp);
        } break;
        /* Data of the OTA update file */
        case TUYA_BLE_OTA_DATA: {
            tuya_ble_ota_data_handler(ota->p_data, ota->data_len, &rsp);
        } break;
        /* OTA update data */
        case TUYA_BLE_OTA_END: {
            tuya_ble_ota_end_handler(ota->p_data, ota->data_len, &rsp);
        } break;
        //* Unknown OTA update command */
        case TUYA_BLE_OTA_UNKONWN: {f
        } break;
        /* default */
        default: {
        } break;
    }
}

API description

tuya_ble_ota_response

Located in tuya_ble_api.h.

Function name	tuya_ble_ota_response
Function prototype	tuya_ble_status_t tuya_ble_ota_response(tuya_ble_ota_response_t *p_data);
Feature description	The response to an OTA request.
Parameter	p_data [in]: the response data. For more information about the data format, see Interaction protocol.
Return value	TUYA_BLE_SUCCESS: succeeded. TUYA_BLE_ERR_INVALID_STATE: invalid status. TUYA_BLE_ERR_INVALID_LENGTH: data length error. TUYA_BLE_ERR_NO_MEM: failed to request memory allocation. TUYA_BLE_ERR_INTERNAL: other errors.
Remarks	Included in tuya_ble_api.h. It is used after the OTA request data is processed to return a response to the app.

Port MCU OTA program

If the serial communication solution supported by the existing module SDK does not fit your needs, you can follow this section and port the MCU OTA program in a custom solution.

OTA update request

When the mobile app sends an OTA update request to the module:

• The Bluetooth command event defined in the SDK is triggered. The handler function is tuya_ble_evt_process.
• If an OTA command is received, run the OTA request handler function tuya_ble_handle_ota_req.
• For an MCU OTA update, run the MCU OTA request handler function tuya_ble_uart_common_mcu_ota_data_from_ble_handler. This function is called to send the OTA request to the MCU. You can refer to the content of this function and modify the communication section with your communication protocol and interfaces.

/* OTA request handling */
static void tuya_ble_handle_ota_req(uint16_t cmd, uint8_t*recv_data, uint32_t recv_len)
{
    /* ... */
    /* MCU OTA */
    if (recv_data[13] == 1) {
        tuya_ble_uart_common_mcu_ota_data_from_ble_handler(cmd, &recv_data[14], data_len-1);
    }
    /* ... */
}

/* Bluetooth command event handling */
void tuya_ble_evt_process(uint16_t cmd, uint8_t*recv_data, uint32_t recv_len)
{
    switch (cmd) {
    /* ... */
    case FRM_OTA_START_REQ:         /* Update start */
    case FRM_OTA_FILE_INFOR_REQ:    /* Information about the update file */
    case FRM_OTA_FILE_OFFSET_REQ:   /* Offset of the update file */
    case FRM_OTA_DATA_REQ:          /* Data of the update file */
    case FRM_OTA_END_REQ:           /* Update result */
        tuya_ble_handle_ota_req(cmd, recv_data, recv_len);
        break;
    /* ... */
    }
}

OTA response

When the MCU returns the OTA response data to the module:

• The serial command event defined in the SDK is triggered. The serial command handler function is tuya_ble_uart_common_process.
• For an OTA update, run the MCU OTA response handler function tuya_ble_uart_common_mcu_ota_data_from_uart_handler. This entry point function is called to send the OTA response to the app. You can refer to the content and custom communication protocol of this function and modify the data parsing code block. Then, this code block can be called in your MCU data receiver function.
• The data transmission function is tuya_ble_commData_send. Pass in the OTA response data as required.

/* Serial command handling */
void tuya_ble_uart_common_process(uint8_t *p_in_data, uint16_t in_len)
{
    /* ... */
    switch (cmd) {
    case TUYA_BLE_UART_COMMON_MCU_OTA_REQUEST:
    case TUYA_BLE_UART_COMMON_MCU_OTA_FILE_INFO:
    case TUYA_BLE_UART_COMMON_MCU_OTA_FILE_OFFSET:
    case TUYA_BLE_UART_COMMON_MCU_OTA_DATA:
    case TUYA_BLE_UART_COMMON_MCU_OTA_END:
        tuya_ble_uart_common_mcu_ota_data_from_uart_handler(cmd,data_buffer, data_len);
        break;
    /* ... */
    };
}