Tuya Zigbee module UART communication protocol

The Tuya Zigbee serial port general protocol is the Tuya custom Zigbee module serial port general protocol, which is mainly used for Tuya Zigbee module to directly connect with other MCU serial ports for serial communication.

Figure 1: Tuya Zigbee serial protocol structure

Hardware connection

Zigbee module is powered by DC 3.3V, UART is set to 9600-8-N-1, no data flow control. The UART interface pins use standard logic. In the idle state, the TXD and RXD pins are both high level, with low level as the start bit and high level as the stop bit. The pin stays high even when the device goes to sleep.

For low-power devices, two GPIO ports (PWM1 and PWM2) are reserved between the Tuya Zigbee module and the MCU, which are used when the MCU and module connection wake up. PWM1 is used by the Zigbee module to wake the MCU, and PWM2 is used by the MCU to wake the Zigbee module. The default is high level, low level is valid for more than 10 ms. For low-power low-voltage devices, the initiator needs to make a wake-up handshake connection before actively initiating a command between the Zigbee module and the MCU.

For high-power devices without hibernation, the serial port is in a long listening state and does not need to be connected to PWM1 and PWM2. It can be left floating.

Serial communication

Frame format

The UART communication data frame between Tuya Zigbee module and MCU is composed of frame header (Front), version (Ver), command word (Cmd), data length (Length), data (Data) and checksum (Check). And description is as follows:

Octets: 2	1	2	1	2	Variable	1
Front	Ver	Seq	Cmd	Length	Data	Check

Frame Format Description

Field	Description
Frame Header (Front)	2 byte leader, fixed to 0x55aa
Version (Ver)	Serial communication protocol version, for upgrading and expansion
Sequence number (seq)	The sequence number of the transmitted data, ranging from 0 to 65535, and returned to 0 after reaching 65535
Command Word (Cmd)	For specific frame types, refer to [Table 2] (# 表 1)
Data length (Length)	effective data length of the transmission; single frame data length does not exceed 64 bytes
Data	Valid Data Transferred
Check	Check the data, starting from the header of the frame and summing the results by 256 bytes

Table 1: Frame format description

Note: The version (Ver) is 1, and does not include the serial number parameter; The version number is greater than 1, including the serial number parameter;

Cmd ID	Description
0x01	Product Information Inquiry / Reporting
0x02	Device Status Query / Report
0x03	Zigbee Device Reset
0x04	Order Issuance
0x05	Status Report
0x06	Status Search
0x07	reserved
0x08	Zigbee Device Functional Test
0x09	Query key information (only scene switch devices are valid)
0x0A	Scene wakeup command (only scene switch device is valid)
0x0A-0x23	reserved
0x24	Time synchronization

Table 2: Cmd description table

All data larger than 1 byte is transferred in big-endian mode.

Under normal circumstances, the command word one send and one receive synchronization mechanism is adopted, that is, one party sends a command and the other responds. If the sender does not receive the correct response packet after timeout, the transmission timeout.

Protocol details

Query Product Information

Explanation:

1) Product ID: Corresponds to the Tuya Developer Platform PID (Product Identification), which is generated by the Tuya Cloud Developer Platform and used to record product-related information in the cloud.

2) Product information consists of product ID and MCU software version.

3) MCU software version number format definition: in dotted decimal form, "x.x.x" (0 <= x <= 99), x is a decimal number.

Module sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x01
Data length	2	0x0000
Data	0	None
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55aa 02 N 01 0000 xx

The MCU returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x01
Data Length	2	N
Data	N	{"p": "AIp08kLI", "v": "1.0.0"}
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: {"p": "AIp08kLI", "v": "2.0.0"}

p means product ID is AIp08kLI

v means MCU version is 2.0.0

0x55aa 02 N 01 00 1c 7b2270223a2241497031386b4c49222c2276223a22312e302e30227d xx

Report module network status

Device Status ID	Description
0x00	The device is not connected to the network
0x01	The device is connected to the network
0x02	Device network status is abnormal

Explanation:

1) The device is not connected to the network: When the device is powered on for the first time, or fails to connect to the network, or is disconnected from the network, the device status is not connected to the network; the status is sent to the MCU.

2) The device is in the networked state: After the device is successfully connected to the network, the device is in the networked state; this state is sent to the MCU.

3) When the network status of the module changes, it will actively send the network status of the module to the MCU.

Module sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x02
Data Length	2	0x0001
Data	1	Indicate module working status: 0x00: status 1 0x01: status 2
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55aa 02 N 02 0001 00 xx

The MCU returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x02
Data length	2	0x0000
Data	0	None
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55aa 02 N 02 0000 xx

Configure Zigbee module

Note: There are two types of commands for configuring the Zigbee module, as shown in the figure below.

Command	Explanation
0x00	Reset module software
0x01	Configure the module to start the network configuration (off the network first and then the network)

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x03
Data Length	2	0x0001
Data	0	0x00 / 0x01
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55aa 02 N 03 0001 01 xx

The module returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x03
Data length	2	0x0000
Data	0	None
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55aa 02 N 03 0000 xx

Command issued

Command issued frame format

! [img] (https://airtake-public-data.oss-cn-hangzhou.aliyuncs.com/fe-static/tuya-docs/4def757c-b094-4fb9-a7ef-fa4999fedbf3.png)!

Explanation:

1) The datapoint command / status data unit is as follows:

Data Section	Length (byte)	Explanation
Dpid	1	datapoint number
Type	1	Corresponds to the specific data type of a datapoint on the open platform.
Type	Value	Length (Bytes)	Description
raw	0x00	N	corresponding to raw datapoint (module transparent transmission)
bool	0x01	1	value range: 0x00 / 0x01
value	0x02	4	corresponding to int type, big-endian representation
string	0x03	N	corresponds to a specific string
enum	0x04	1	Enumeration type, range 0-255
bitmap	0x05	1/2/4	When the length is greater than 1 byte, big-endian means
Len	2	Number of bytes of length corresponding to value
Value	1/2/4 / N	hex indicates that more than 1 byte is transmitted in big-endian

2) Except for the "raw" type, the datapoint command / status data unit belongs to the "obj" type datapoint.

3) The "command delivery" may include multiple datapoint "command data units".

4) "Command issuance" is an asynchronous processing protocol, corresponding to the "status report" of the MCU's datapoint.

Module sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x04
Data length	2	Depends on "command data unit" type and number
Data	N	"3.4 Command Data Unit" Group
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: The system switch corresponds to DP No. 3, using a bool variable, and the boot value is 1.

0x55aa 02 N 04 0005 ** 03 01 0001 01 ** xx

Status reporting (passive)

Explanation:

1) After the MCU receives the command issued by the module side and performs the corresponding action, it needs to passively report the new status to the module side;

a. After the status is correctly executed, only the datapoint status of the performed operation is reported;

2) "Status reporting (passive)" is a synchronous processing protocol. After receiving the datapoint information, the module will immediately return an ACK to the MCU;

3) "Status reporting (passive)" may include multiple datapoint "command data units". For details of the datapoint status data unit description, see "Section 3.4"

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x05
Data length	2	Depends on the type and number of Status Data Units
Data	N	"3.4 Status Data Unit" Group
Checksum	1	Byte-sum results from the header of the frame to 256

Example: Humidity corresponds to No. 5 DP, use valve type variable, humidity is 30 ℃

0x55aa 02 N 05 00 08 ** 05 02 0004 0000001e ** xx

The module returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x05
Data Length	2	0x0001
Data	0	0x00 / 0x01 0x00: Status reporting failed 0x01: Status reporting successful
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: Module returns ACK status to MCU successfully

0x55aa 02 N 05 0001 01 xx

Status reporting (active)

Explanation:

1) In the case that the MCU actively detects a change in the datapoint or the MCU restarts, it is necessary to send the changed datapoint status to the module.

a. When there is a normal change, only the changed datapoint is reported;

b. In abnormal situations such as restart, all datapoints need to be reported;

2) "Status reporting (active)" is an asynchronous processing protocol. After receiving the response from the gateway within the timeout period, the module will return the status to the MCU. If the status returns timeout or the status is fail, the MCU needs to do random Backoff retransmission mechanism.

3) The "status report (active)" may include multiple datapoint "command data units". For details of the datapoint status data unit description, see "Section 3.4".

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x06
Data length	2	Depends on the type and number of Status Data Units
Data	N	"3.4 Status Data Unit" Group
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: Humidity corresponds to No. 5 DP, use valve type variable, humidity is 30 ℃

0x55aa 02 N 06 08 ** 05 02 0004 0000001e ** xx

The module returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x06
Data Length	2	0x0001
Data	0	0x00 / 0x01 0x00: Status reporting failed 0x01: Status reporting successful
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: Module returns ACK status to MCU successfully

0x55aa 02 N 06 0001 01 xx

Zigbee module functional test

Note: Scan the RSSI value of the specified channel, and return the scan result and signal strength percentage. This command can run normally only when the device is not connected to the network. The module must be restarted after a single test.

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x08
Data Length	2	0x0001
Data	Data	Channel Value (11-26)
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

example:

The MCU requires the module to scan the RSSI value of the 11 channels:

0x55aa 02 N 08 0001 0b xx

The module returns:

Field	Length (byte)	Explanation
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x08
Data Length	2	0x0002
Data	2	The data length is 2 bytes: Data [0]: 0x00 failed, 0x01 succeeded; When Data [0] is 0x01, that is, success, Data [1] indicates the signal strength (0-100, 0 signal is the most Poor, 100 signal is the strongest) When Data [0] is 0x00, that is, failure, Data [1] is 0x00 means that RSSI is not scanned on the specified channel, and Data [1] is 0x01, which means the module has not flashed the authorization key
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

example:

0x55aa 02 N 08 0002 01 64 xx

Explanation:

The effective value of the channel is (11-26), and the invalid channel will use 11 channels by default;

Time synchronization

Note: Time synchronization is used by the MCU to measure the network time usage of the synchronization gateway.

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x24
Data length	2	0x0000
Data	NA
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

The module returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x024
Data Length	2	0x0002
Data	2	The data length is 8-byte time value, the format reference is as follows time synchronization data format
Checksum	1	Byte-sum results from the header of the frame to 256

Time-synchronized data format, including standard timestamps and local timestamps.

Variable	Variable
Standard timestamp (4 byte)	Local timestamp (4 byte)

Time synchronization data format

1.The standard time stamp is the total number of seconds from 00: 00: 00 on January 01, 1970, GMT.

Local timestamp = standard timestamp + seconds between standard time and local time (including time zone and daylight saving time)

Scene switch protocol

In the scene switch device, the MCU only needs to inform the Zigbee module device how many keys it has through the serial port transparent transmission protocol, and which key is currently operated.

Query key information

Module sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x09
Data length	2	0x0000
Data	NA
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

example:

The module requires to obtain the total value of the MCU's keys:

0x55aa 02 N 09 0000 xx

The MCU returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x09
Data Length	2	0x0001
Data	2	Total number of keys on the panel switch
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

example:

0x55aa 02 N 09 0001 02 xx

Scene wake command

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x0A
Data Length	2	0x0001
Data	Button ID
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Note: There is a one-to-one correspondence between the key ID and the total number of keys.

example:

The MCU requires the module to execute the scenario corresponding to button 1:

0x55aa 02 N 0A 0001 01 xx

The module returns:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Serial number	2	N
Command Word	1	0x0A
Data Length	2	0x0001
Data	1	0: Scene wakeup failed; 1: Scene wakeup successful;
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

example:

0x55aa 02 N 0A 0001 01 xx

MCU OTA protocol

Data format requested by OTA version

This command must be implemented if MCU upgrade is supported. The gateway will actively query the MCU version number, and the MCU can also report it actively. Query scenarios: 1. During network deployment 2. Device initiated time synchronization 3. When the MCU upgrade process is abnormal; 1. After successful network configuration (must be added) 2. Upgrade is complete.

Module sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Business Sequence Number (Seq)	2	Module Generation
Command Word	1	0x0B
Data length	2	0x0000
Data	0	NA
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55 AA 02 00 f0 0B 00 00 XX

MCU response:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Service Sequence Number (Seq)	2	SEQ issued by MCU
Command Word	1	0x0B
Data Length	2	0x0001
Data	1	Version number (current version) (Bits) 01.00.0001 à1.0.1
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 55 AA 02 00 39 0B 00 01 40 XX

OTA Upgrade Notice

Module sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Business Sequence Number (Seq)	2	Module Generation
Command Word	1	0x0C
Data length	2	0x0011
Data	8	Data [0] ~ Data [7] PID
Data	1	Version number ** (upgrade version) ** (Bits) 01.00.0001 à1.0.1
Data	4	Firmware size up to 64K
Data	4	Firmware checksum: 2 ^ 32 remainder from the result of byte-wise summation from the first byte of firmware
Checksum	1	Byte-sum results from the header of the frame to 256

Example: 0x55 AA 02 00 1C 0C 00 0F 30 31 32 33 34 35 36 37 40 00 01 00 00 30 31 32 33 XX

MCU response:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Business Sequence Number (Seq)	2	seq issued by the module
Command Word	1	0x0C
Data Length	2	0x0001
Data	1	0x00: OK, 0x01: error
Checksum	1	Byte-sum results from the header of the frame to 256

Example: 0x55 AA 02 00 1C 0C 00 01 00 XX

OTA firmware content request

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Business Sequence Number (Seq)	2	0x0000
Command Word	1	0x0D
Data length	2	0x000E
Data	8	PID
Data	1	Version number ** (upgrade version) ** (Bits) 01.00.0001 à1.0.1
Data	4	Offset of packet (location of firmware)
Data	1	Packet size (up to 50 bytes)
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55 AA 02 00 00 0D 00 0E 30 31 32 33 34 35 36 37 40 00 00 00 01 32 XX

Module response:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Business Sequence Number (Seq)	2	0x0000
Command Word	1	0x0D
Data length	2	0x0006 + N
Data	1	Status 0: Success 1: Failure
Data	8	PID
Data	1	Version number ** (upgrade version) ** (Bits) 01.00.0001 à1.0.1
Data	4	Offset of packet (location of firmware)
Data	N	Data
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 55 AA 02 00 39 0D XXXX 00 30 31 32 33 34 35 36 37 40 00 00 00 01…. XX

OTA firmware upgrade result report

MCU sends:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Service Sequence Number (Seq)	2	SEQ issued by MCU
Command Word	1	0x0E
Data length	2	0x000A
Data	1	Status 0: Success 1: Failure
Data	8	PID
Data	1	Version number ** (upgraded current version) ** (Bits) 01.00.0001 à1.0.1
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55 AA 03 00 f0 0E 00 0A 00 30 31 32 33 34 35 36 37 40 26

Module response:

Field	Length (byte)	Description
Frame Header	2	0x55aa
Version	1	0x02
Service Sequence Number (Seq)	2	SEQ issued by MCU
Command Word	1	0x0E
Data Length	2	0x0001
Data	1	0x00: OK, 0x01: error
Checksum	1	Byte-sum results from the header of the frame, 256 remainder

Example: 0x55 AA 02 00 1C 0E 00 01 00 XX