OTA Update for Extended Firmware

This topic describes the OTA update service for extended firmware.

Overview

An over-the-air (OTA) update is the wireless delivery of new software, firmware, or other data to connected IoT devices.

The MCU SDK supports OTA updates for the MCU’s extended firmware. You can first upload the update file to the Tuya Developer Platform. The Bluetooth module can download the update from the server and send it to the MCU through the serial port. This way, the MCU gets the update and writes it to the local flash memory of the extended module for installation. For more information, see Update Firmware and Select and Change the Firmware Version.

Related protocols

This protocol is intended for updating the MCU’s extended firmware.

Extended firmware update process

Report extended firmware information (0xF9)

• When the MCU has an extended module and needs to support updating the extended module, the MCU should use this interface to report the firmware information of the extended module to the Bluetooth module during the initialization process. During the pairing and reconnection process, the Bluetooth module will report this information.
• The information of the extended firmware will not be retained when the module loses power. Therefore, the MCU needs to update the extended firmware information every time the module starts up to ensure the update works as expected. Each time the module is started, it will query the MCU firmware information through 0xE8. Before responding to the 0xE8 command, it is recommended that the MCU report the extended firmware information to the module through 0xF9. This way, each time the module is started, it can get and update the information of the extended firmware in time to ensure a reliable update.
• For Bluetooth LE+X devices, after the extended firmware is successfully updated, the MCU needs to pay attention to the module’s query via the 0xE8 command. After ensuring the extended firmware version number has been successfully updated, the MCU reports the extended firmware information through 0xF9 and responds to 0xE8. This way, the cellular module can get and update the extended firmware information in time to ensure a reliable update.
• Reporting the extended firmware information is a prerequisite for supporting extended firmware updates.

The MCU sends the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xF9
Data length	7n+1	The total number of bytes in the data field.
Data	1	channel_number
	7	channel_data: channel (1 byte) + Soft_ver (3 bytes) + Hard_ver (3 bytes)
	…	Multiple extended firmware require channel_number of channel_data.
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

• channel_number: Indicates the number of extended channels of the extended firmware, and also the number of groups of channel_data.
• channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the Tuya Developer Platform.
• Soft_Ver: The firmware version of the MCU. For example, 0x01 00 02 represents v1.0.2.
• Hard_ver: The hardware version of the MCU, the PCBA version number.

The module returns the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xF9
Data length	2	0x00 0x01
State	1	Return value
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Return value of state:

• 0x00: Success
• Other values: Failure

Send update request (0xFA)

The Bluetooth module initiates an extended firmware update request to the MCU to get the maximum length of one packet for serial transmission.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xFA
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	2	Len1
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

• channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

• Len1: The maximum length of a packet that can be transmitted over the serial port, in the unit of bytes.

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xFA
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	1	Flag
	5	Type_data: Version (3 bytes) + Len2 (2 bytes)
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

• channel: The same as command sending.

• Flag: 0x00 indicates the update is accepted. 0x01 indicates the update is rejected.

• Version: The current firmware version. For example, 0x01 00 02 represents v1.0.2.

• Len1: The module-specified maximum length of a packet.

• Len2: The maximum length of a packet allowed when the MCU’s extended firmware is updated. If Len1 is less than Len2, Len1 prevails. Otherwise, Len2 prevails.

Get update information (0xFB)

The MCU can use the update information of the extended firmware to decide whether to perform an update.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x10
Command (CMD)	1	0xFB
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	8	Product ID (PID)
	3	File version
	16	File MD5 hash
	4	File length
	4	CRC32
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

• channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

• PID: The product ID (PID) of the extended firmware.

• Firmware version: The version of firmware to be installed. For example, 0x01 00 02 represents v1.0.2.

• File MD5 hash: The MD5 value of the firmware update.

• File length: The total length of the firmware update, in bytes.

• CRC32 checksum: The CRC32 value of the firmware update.

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x10
Command (CMD)	1	0xFB
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	1	STATE
	4	The size of the update that has already been downloaded.
	4	The CRC32 checksum of the update that has already been downloaded.
	16	The MD5 hash value of the update that has already been downloaded. (Not used currently)
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

STATE:

• 0x00: The update is performed as expected.

• 0x01: The received PID does not match the one written to the device.

• 0x02: The update version is earlier than or equal to the current version.

• 0x03: The update size exceeds the upper limit.

• Others: Reserved.

Request the update offset (0xFC)

The module sends the following data.

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command (CMD)	1	0xFC
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	4	OFFSET
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

• channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

• OFFSET: Indicate where to start downloading the update. The value has four bytes.

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55, 0xAA
Version number	1	0x00
Command (CMD)	1	0xFC
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	4	OFFSET
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

• channel: The same as command sending.

• OFFSET: the start offset specified by the MCU.

Transfer the update (0xFD)

The module sends the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x10
Command (CMD)	1	0xFD
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	2	Packet ID
	2	The length (n) of current packet data
	2	The CRC16 checksum of the current packet
	n	The payload of the current packet
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xFD
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	1	STATE
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

Return value of state:

• 0x00: Success

• 0x01: Packet ID error.

• 0x02: The data length does not match the expected one.

• 0x03: CRC check failed.

• 0x04: Other errors.

Request the update result (0xFE)

The module sends the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xFE
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55 0xAA
Version number	1	0x00
Command (CMD)	1	0xFE
Data length (Len)	2	The total number of bytes in the data field.
Data	1	channel
	1	STATE
CRC8	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

channel: The firmware channel ID ranging from 10 to 19, generated when you create the firmware on the platform.

Return value of state:

• 0x00: Success

• 0x01: The total data length error.

• 0x02: The data length does not match the expected one.

• 0x03: Other errors.

FAQs

Q: What is the difference between this protocol and the MCU OTA update protocol?

A: This protocol specifies how to update the extended firmware, and its format is similar to that of the MCU OTA update protocol. The main difference lies in the commands. Moreover, an additional channel field appears before each data field, indicating which firmware the command corresponds to. In the MCU code design, channel number processing can be added to the MCU OTA component and distinguished by commands.

Example:

• If the command is 0xEA to 0xEF, the default channel number is 9 (the MCU’s firmware).
• If the command is 0xFA to 0xFE, the first byte of the data field is parsed as the channel number. After being offset by one byte, the rest is parsed as previously.

Q: What are the prerequisites for using the extended firmware update channel in MCU integration?

A: The following prerequisites are required:

• Create extended firmware on the platform and obtain the channel ID.

• After synchronizing the MCU information with 0x01, the MCU needs to use the 0xF9 command to report the extended firmware information.

Q: How can I update multiple firmware images?

A: You can differentiate the firmware images using the channel field in the OTA update commands 0xFA through 0xFE. The channel is the firmware channel ID, generated when you create the firmware on the platform.

Q: What are the common considerations?

A: For Bluetooth LE+X products, at the end of the extended firmware update process, only the MD5 hash value in the Get update information (0xFB) can be used to verify the update file. The CRC32 value is only valid in Bluetooth connections, but is not supported in cellular connections due to protocol compatibility issues.

Q: Which Bluetooth module firmware supports the extended firmware update service?

A: Currently, only the deliverables named FR8016HA generic integration or BF6H Bluetooth LE generic firmware support the extended firmware update service. The firmware key: keywt49k, and version: 1.3.0 or later. Other generic modules will release this feature later.

Support and help

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