English
English
简体中文
Contact Us
Register
Log In
Language
English
English
简体中文
Contact Us
Log In
Register
Go to main website
App Develop

App Development Platform

App development platform provides multiple development methods such as no-code or IoT App SDK development to maximize the monetization of IoT apps.
layoutIndex

Serial Port Protocol

Last Updated on : 2021-07-01 06:45:45download

This topic describes how to implement communications between Tuya Zigbee modules and MCU serial ports through Tuya Zigbee general serial protocol.

Protocol architecture

The following figure shows how Tuya’s Zigbee module communicates with your MCU.

Serial Port Protocol

Serial communication protocol

  • Baud: 9600/115200

  • Data bit: 8

  • Parity check: None

  • Stop bit: 1

  • Data flow control: None

  • Supply voltage: Tuya’s Zigbee module and the MCU are powered by 3.3V DC.
    The following table gives the pin mapping for the module’s firmware keys.

    Module model TX on the module RX on the module Firmware key
    ZS3 PA0 PA1 key4pkap
    ZS5 PA0 PA1 key5r57k
    ZS3L PA5 PA6 keyk5unt
    ZTU PC2 PC3 keyuq4y3 key5sxah
    ZTU PB1 PB7 keytq4v4
    ZT5 PC2 PC3 keyuq4y3 key5sxah
    ZT3L PB1 PB7 keytq4v4
  • Sleep mode:

    • Low-power devices with sleep mode: Reserve two GPIOs on the Zigbee module and the MCU to wake up the MCU and module by level triggered interrupt. Each time before the Zigbee module or the MCU initiates a command, they will do a handshake. For more information about the wake-up method, see the following figure. Serial Port Protocol
      The following table gives the pin mapping for wake-up.

      Module model GPIO used for module to wake up MCU GPIO used for MCU to wake up module
      ZS3 PF5 PA2
      ZS5 PA4 PA3
      ZS3L PC1 PA3
      ZTU PB4 PB5
      ZT5 PB4 PB5
    • Electrical devices without sleep function: The serial port is monitored and the hardware does not need to connect to I/O1 and I/O2.

  • The MCU wakes up the module: You can set a 1 to 10 ms delay before data sending when the GPIO is low. The module is awake as the wake-up GPIO keeps low. To reduce consumption, the module enters sleep mode 300 to 550 ms later after the GPIO is high.

  • When an MCU wakes up the ZT series module, you need to set a delay of at least 10 ms before data sending when the GPIO is low.

    Serial Port Protocol

    The firmware supports wake-up by pulses. The MCU sends a low pulse to the wake-up GPIO lasting for 1 to 5 ms before data sending. When the wake-up GPIO keeps low, the power consumption of the module will increase. This pulse wake-up method can reduce consumption.

    set_gpio_low();
    delay(1);
    set_gpio_high();
    uart_send_buffer();
    

Frame format description

The UART communication data frame between Tuya’s Zigbee module and the MCU is composed of the frame header (Front), version (Ver), command (Cmd), data length(Length), data (Data), and checksum (Check).

Field Length (byte) Description
Header (Front) 2 It is fixed as 0x55aa.
Version (Ver) 1 Serial communication protocol version for upgrade and extension.
Sequence (Seq) 2 Transmission data serial number ranges from 0 to 0xfff0. When reaching 0xfff0, it starts from 0 again.
Command (Cmd) 1 Specific frame type.
Data length (Length) 2 The length of effective data transmitted.
Data (Data) Depend on specific data Effective data transmitted.
Checksum (Check) 1 Data check. Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Note: The length of a single packet transmitted by the Zigbee module determines the data length (Length). Tuya repackages the Zigbee packet data format. Currently, the maximum data length is 62 bytes.

Command index

Command Description
0x01 Report product information.
0x02 Report device status.
0x03 Reset the device.
0x04 Send a command.
0x05 Report status.
0x06 Query status.
0x07 Reserved.
0x08 Detect device functions.
0x09 Query key-press information. Only available for scene switches.
0x0A Trigger the scene. Only available for scene switches.
0x24 Sync time.
0x25 The module queries MCU device type.

Communication method

Note: All data greater than one byte shall be transmitted in the big-endian mode.

Command communication

One command is sent by one party and received by the other party in a synchronous way. That is, one party sends the command, and the other party responds, as shown in the following figure.

Serial Port Protocol

Note: For specific communication modes, see the protocol details.

Module sends command

The module sends commands to the MCU in an asynchronous way.

  • The following figure illustrates the typical command transmission. Assume that the module sends a command X, and the MCU reports command Y.

    Serial Port Protocol
  • Sending process

    1. The module sends the DP data through the 0x04 command.
    2. When the MCU receives the 0x04 command, the MCU responds to the module that the command has been received through the serial port.
    3. The MCU sends the execution result to the cloud through the 0x05 command.
    4. Verify whether the serial number of the 0x05 command is consistent with that of the 0x04 command.

MCU reports status

The MCU reports status to the module in an asynchronous way. The MCU reports status in a passive or active way.

  • Passive reporting: The module sends commands to the MCU, and the MCU returns the status after execution.

    Serial Port Protocol
  • Active reporting: When the status of the MCU changes due to operations or reboot after shutdown, the MCU actively reports its current status to the module. Active reporting works in an asynchronous way. If the MCU does not receive the response frame within the timeout period or receives a failure response, the MCU must retransmit the status data.

    Serial Port Protocol

Basic protocol

Query MCU device type

The module queries the MCU device type after power-on. If the query succeeds, the module will save the device type without querying again.

Note: This is a new function. You need to test whether your module firmware supports it.

  • How it works: When receiving a response from the MCU, the Zigbee module will reboot and then continue data transmission with the module after loading parameters.

  • How to detect: The module sends a query command at 9600 baud rate after power-on. If no response is received from the MCU, the module will continue detection at 115200 baud rate.

    Note:

    • The device is treated as a low power device during detection. Before serial data transmission, the module sends a 50 ms low pulse to the MCU wake-up I/O pin.
    • For your released MCU firmware, the latest firmware applies to this function. But when connecting new products, this protocol shall be implemented.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x25
Data length 2 0x0000
Data 0 0
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x25
Data length 2 0x0001
Data 1
  • 0x01: Electrical device.
  • 0x02: Low power device.
  • 0x03: Scene panel for electrical device.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Query product information

Product information consists of product ID (PID) and the MCU software version. When the module is reset, it will actively query product information. If the MCU does not respond or respond with incorrect data, the MCU will query every five seconds.

  • PID: It is automatically generated for each created product on the Tuya IoT Platform to record product information in the cloud.

  • MCU software version number: Defined as dot-decimal notation in the format of x.x.x and x is a decimal digit.

    Note: The MCU version is represented with a single byte for OTA-related commands. The maximum version is 3.3.15 due to the limitation of byte length.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x01
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 01 0000 xx

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x01
Data length 2 N
Data N
  • For example, {“p”:”AIp08kLI”, “v”:”2.0.0” }
  • Parameter description:
    • p: Product ID (PID).
    • v: MCU version number.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 01 00 1c 7b2270223a2241497031386b4c49222c2276223a22312e302e30227d xx

Report network status of the module

The network status indicates the networking of the Zigbee module. When the module is successfully paired, it means a device is connected. The network status is independent of gateway outage and parent node loss. When the network status of the module changes, the module actively sends the current network status to the MCU.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x02
Data length 2 0x0001
Data 1 Module network status:
  • 0x00: Not connected. The following status is considered not connected.
    • First power-on.
    • Connection fails.
    • Offline.
  • 0x01: Connected.
  • 0x02: Network exception.
  • 0x03: Connecting.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 02 0001 00 xx

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x02
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 02 0000 xx

Query network status of the module

The MCU can query the current network status of the Zigbee module.

Note: Before enabling this function, you need to test whether the current firmware supports it.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x20
Data length 2 0x0000
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 20 0000 xx

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x20
Data length 2 0x0001
Data 1 Module network status:
  • 0x00: Not connected. The following status is considered not connected.
    • First power-on.
    • Connection fails.
    • Offline.
  • 0x01: Connected.
  • 0x02: Network exception.
  • 0x03: Connecting.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 20 0001 xx xx

Configure Zigbee module

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x03
Data length 2 0x0001
Data 0
  • 0x00: Reset the module software.
  • 0x01: Start pairing (disconnect and pair).
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 03 0001 01 xx

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x03
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 03 0000 xx

Send commands

A Zigbee module can send commands.

  • For DP commands and status data units, except the raw type, all other types belong to the obj type data points.
  • Sending multiple commands are supported in obj type data points.
  • The asynchronous processing protocol is used to send commands, corresponding to the MCU status reporting.

The frame format for sending commands:

Serial Port Protocol

Data point format:

| Field property | Length (byte) | Description |
| ---- | ---- | ---- | ---- | ---- | ---- |
| dpid | 1 | DP number | | | |
| type | 1 | Correspond to the data type specified in the Tuya IoT Platform:

  • raw: raw type. The module sends raw data.
    • Value: 0x00
    • Length (byte): N
  • bool: boolean type. The value is 0x00 or 0x01.
    • Value: 0x01
    • Length (byte): 1
  • value: integer type. Use a big-endian representation.
    • Value: 0x02
    • Length (byte): 4
  • string: string type.
    • Value: 0x03
    • Length (byte): N
  • enum: enumeration type. Range from 0 to 255.
    • Value: 0x04
    • Length (byte): 1
  • bitmap: fault type. Use a big-endian representation when there is more than one byte.
    • Value: 0x05
    • Length (byte): 1, 2, or 4
| | | |
| len | 2 | The length is the bytes of the value (big-endian). | | | |
| value | 1/2/4/N | Expressed in hexadecimal format. Use a big-endian representation when there is more than one byte. | | | |

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x04
Data length 2 None
Data Depend on specific data See data point format.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 04 0005 03 01 0001 01 xx

Note: 03 01 0001 01 indicates the switch function is represented by DP 3 and uses a Boolean type. The value is 1, meaning the device is turned on.

Passive statue reporting

After the MCU receives the command sent by the module and executes the corresponding action, the MCU shall report the new status to the module. After the action is executed correctly, only the status of the executed DP is reported.

  • Passive status reporting is processed in a synchronous way. After receiving DP status, the module will immediately return an ACK message to the MCU.
  • Passive status reporting may include multiple obj type DP commands.
  • raw data and obj data cannot be reported simultaneously.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x05
Data length 2 Depend on specific data.
Data Depend on specific data See data point format.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 05 00 08 05 02 0004 0000001e xx

Note: 05 02 0004 0000001e indicates humidity reporting is represented by DP 5 and uses a value type. The humidity is 30%.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x05
Data length 2 0x0001
Data 0
  • 0x00: Status reporting failed.
  • 0x01: Status reporting succeeded.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 05 0001 01 xx

Active status reporting

  • When the MCU reboots or detects DP changes, the MCU sends the current DP status to the module.

    • For normal status changes, only the status of the changed DP is reported.
    • For status changes resulted from anomalies such as reboot, all DP status shall be reported.
  • Active status reporting is processed in an asynchronous way. After receiving a response from the Zigbee gateway, the module will return status to the MCU. If returning status timed out or failed, the MCU shall report the status again.

  • Passive status reporting may include multiple obj type DP commands.

  • raw data and obj data cannot be reported simultaneously.

Note: If you want DP data to be reported after successful pairing to synchronize with the app panel, it is recommended to set a 5-second timeout on status reporting.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x06
Data length 2 Depend on specific data.
Data Depend on specific data See data point format.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 06 08 05 02 0004 0000001e xx

Note: 05 02 0004 0000001e indicates humidity reporting is represented by DP 5 and uses a value type. The humidity is 30%.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x06
Data length 2 0x0001
Data 0
  • 0x00: Status reporting failed.
  • 0x01: Status reporting succeeded.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 06 0001 01 xx

Functional test of Zigbee module

The Zigbee module can scan the RSSI value of a specified channel, and then return the scanning result and signal strength percentage. This command can work properly only when the device is not paired, and the module must reboot after a single test is completed.

Note: Channel 11 is used by default. When MCU sends data, channel 11 shall be selected.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x08
Data length 2 0x0001
Data 1 Channel value (11 to 26)
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 08 0001 0b xx indicates that the MCU requires the module to scan the RSSI value of channel 11.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x08
Data length 2 0x0002
Data 2
  • Data[0]:
    • 0x00: Failure
    • 0x01: Success
  • Data[1]:
    • When Data[0] is 0x00: Data[1] indicates signal strength, ranging from 0 to 100, 0 for the weakest and 100 for the strongest.
    • When Data[0] is 0x01:
      • Data[1] is 0x00: The specified RSSI has not been found.
      • Data[1] is 0x01: The authorization key is not programmed to the module.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 08 0002 01 64 xx

Note: If a channel is invalid, channel 11 is selected by default.

Time synchronization

Synchronize the network time of the gateway to the MCU.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x24
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x024
Data length 2 0x0002
Data 2 The data length is an 8-byte time value. The format is the standard timestamp (4 bytes) plus local timestamp (4 bytes).
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.
  • The standard timestamp is the total seconds from GMT 00:00:00, January 1, 1970 to the current time.
  • The local timestamp is the standard timestamp plus the difference in seconds between standard time and local time (including time zone and daylight saving time).

Scene switch protocol

For a scene switch, the MCU only needs to notify the Zigbee module of the number of keys and the currently operated keys through the serial pass-through protocol.

Query key-press information

After reboot, the module will send a command to query key-press information.

  • The maximum number of keys supported is 10, indicating 10 scenes can be created.
  • The feature is only applicable to the scene panel, but cannot be used by other DPs and custom DPs.
  • When a product is being created, the required DPs are scene ID and group ID (1 to 10).
  • The scene ID shall be arranged in ascending order, starting from scene 1.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x09
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 09 0000 xx

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x09
Data length 2 0x0001
Data 2 The total number of keys on the panel switch.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 09 0001 02 xx

Scene triggering command

Trigger the scene panel to execute scene-based operations. After the MCU sends the request, the module returns the following status.

  • Success: The key is bound to a scene in the app, and the corresponding scene is successfully executed.
  • Failure: The key is not bound to a scene in the app, and the scene will not be executed.

When the key is pressed, the scene panel will also send a key value to the gateway to link the cloud scene. If the scene panel only uses the cloud scene, when the MCU reports a key to the gateway, the reporting is considered to be successful, no matter what the module responds.

The difference between cloud scene and local scene

  • Local scene: The standard Zigbee scene, conforming to Zigbee protocol. Note that currently, the scene data saved in the device is the specified attribute value, and some commands are not supported. These unavailable functions shall be implemented through cloud scenes.
  • Cloud scene: Essentially, it is cloud linkage control, referring to scenes implemented through cloud functions.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x0A
Data length 2 0x0001
Data Depend on specific data Key ID
Note: If the total number of keys is four, the data is 01 02 03 04.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 0A 0001 01 xx indicates that the MCU requires the module to execute the scene specified by key 1.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x0A
Data length 2 0x0001
Data 1
  • 0: Failed to trigger the scene.
  • 1: Triggered the scene successfully.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55aa 02 N 0A 0001 01 xx

MCU OTA protocol

The OTA process is as follows.

  1. The cloud sends an OTA notification.
  2. The MCU responds to this notification after receiving it.
  3. The MCU initiates a data request, and the maximum request packet size is 50 bytes.
  4. The module will forward the request to the gateway.
  5. The gateway responds with data according to the current offset and packet size.

To improve the data request logic of the MCU, a timeout mechanism is required. If the MCU receives no response within a time period, it sends the request again.

Note: It is recommended to set the timeout to three to five seconds. The maximum of five timeouts is allowed. If the response time exceeds 3 to 5 seconds for 5 consecutive times or more, it is considered that the OTA update exception occurs and the update is canceled.

Data format of requesting OTA version

To support the MCU update, this command must be implemented. Support gateway query and MCU reporting.

  • Scenarios where the gateway queries OTA version:
    • Pairing succeeded.
    • MCU update exception.
  • Scenarios where the MCU reports OTA version:
    • Pairing succeeded. (Required)
    • OTA update succeeded.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 Generated by the module.
Command 1 0x0B
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55 AA 02 00 f0 0B 00 00 XX

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 Sent by the MCU.
Command 1 0x0B
Data length 2 0x0001
Data 1 Current version number. For example, (bits) 01.00.0001 indicates 1.0.1.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 55 AA 02 00 39 0B 00 01 40 XX

Note: The MCU version is represented in a single byte for OTA-related commands. The maximum version is 3.3.15 due to the limitation of byte length.

OTA updates notification

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 Generated by the module.
Command 1 0x0C
Data length 2 0x0011
Data 8 PID. Data[0] to Data[7].
Data 1 Current version number. For example, (bits) 01.00.0001 indicates 1.0.1.
Data 4 Firmware size. The maximum size is 256 KB.
Data 4 Firmware checksum: Start from the first byte of the firmware, add up all the bytes, and then divide the sum by 256 to get the remainder.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For 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

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 Serial number sent by the module.
Command 1 0x0C
Data length 2 0x0001
Data 1
  • 0x00: Succeeded.
  • 0x01: Failed.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55 AA 02 00 1C 0C 00 01 00 XX

Request OTA firmware content

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 0x0000
Command 1 0x0D
Data length 2 0x000E
Data 8 PID
Data 1 Current version number. For example, (bits) 01.00.0001 indicates 1.0.1.
Data 4 The offset of the data packet (location of the firmware).
Data 1 The size of the data packet, a maximum of 50 bytes.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55 AA 02 00 00 0D 00 0E 30 31 32 33 34 35 36 37 40 00 00 00 01 32 XX

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 0x0000
Command 1 0x0D
Data length 2 0x0006+N
Data 1
  • 0x00: Succeeded.
  • 0x01: Failed.
Data 8 PID
Data 1 Current version number. For example, (bits) 01.00.0001 indicates 1.0.1.
Data 4 The offset of the data packet (location of the firmware).
Data N Data
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 55 AA 02 00 39 0D XXXX 00 30 31 32 33 34 35 36 37 40 00 00 00 01 … XX

Report OTA firmware update result

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 Serial number sent by the MCU.
Command 1 0x0E
Data length 2 0x000A
Data 1
  • 0x00: Succeeded.
  • 0x01: Failed.
Data 8 PID
Data 1 Current version number. For example, (bits) 01.00.0001 indicates 1.0.1.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55 AA 03 00 f0 0E 00 0A 00 30 31 32 33 34 35 36 37 40 26

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Sequence (Seq) 2 Serial number sent by the MCU.
Command 1 0x0E
Data length 2 0x0001
Data 1
  • 0x00: Succeeded.
  • 0x01: Failed.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

For example, 0x55 AA 02 00 1C 0E 00 01 00 XX

MCU broadcasts data

When the MCU broadcasts data, the data of this frame is used.

Note: The interval between broadcasts is required, which is determined by the network scale.

All devices connected to this network can receive the broadcast data. For low-power devices, they shall be in a periodic wake-up status, and the wake-up period shall be less than the broadcast period. Otherwise, before waking up, the next broadcast data will overwrite the previous one.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x27
Data length 2 N
Data Depend on specific data Specific data point format.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x027
Data length 2 0x0001
Data 1 00: Reporting failed. 01: Reporting succeeded.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

MCU configures policy parameters of the Zigbee network

When receiving the PID query frame from the module, the MCU can send data after a milliseconds delay.

Note: After receiving and successfully responding to the command, the module will reboot.

  • Heartbeat time

    The heartbeat time is used to determine whether the data link between the device and the gateway works properly. The heartbeat time of electrical devices is 150 plus random (30) seconds by default, and for low-power devices, it is four hours by default. If no heartbeat is received within 12 hours, the gateway will consider the device offline. Only the heartbeat time of low-power devices can be modified.

  • Timeout

    After the MCU sends a pairing command, the module will execute pairing operations for a period of time and send the current network status as the pairing status. If the module fails to be paired due to no pairing network available or poor network signal, pairing will time out. After the timeout, the module waits for pairing and sends the current status to the MCU simultaneously.

  • Polling

    The polling cycle means that paired low-power modules will wake up periodically. After wake-up, the low-power module will send a data request to its parent node to check whether there is cache data. If there is cache data, the parent node can send the data to the low power module.

    • Polling settings

      • For products that require high real-time performance, such as smart switches (no neutral wire required), the polling value can be set to 250 ms.
      • For other products, such as sensors, the data is reported when the DP status changes or periodic reporting is executed. When the data is reported, polling can be disabled. The module cannot receive the control commands sent by the gateway.
    • Poll settings after power-on
      Set a period of fast polling after power-on to let the module receive commands from the gateway. The fast polling after power-on is set to 30 seconds by default and the MCU setting is available. If polling needs to be disabled but the MCU needs commands from the gateway, it is recommended to increase the time window of the fast polling.

    • Disable polling
      The gateway will cache data. When the module reports data, it will carry a data request. The gateway will send the data to the module.

    Note: The polling value affects power consumption. The shorter the wake-up period, the higher the power consumption. The minimum value of polling is 200 ms. It is recommended to set a value not greater than eight seconds. If the value is set to 0, polling will be disabled.

  • Rejoin

    Rejoin means joining the network again. This mechanism is used for low-power devices to rejoin the network when the parent node is lost.

    Note: Rejoin does not mean pairing. The pairing mode of the gateway is not required.

    The interaction between the module and the parent node is as follows:

    1. The module sends a data request.
    2. The parent node responds.
      • Cache data: Send data to the module.
      • No cache data: Only respond with ACK.

    If the module sends a data request, but the module does not receive the ACK due to the environment, distance, or power-off of the parent node, the polling is considered failed. If the accumulated times of polling failure reach a value, it is considered that the parent node has been lost, and rejoin shall be triggered.

    Note: If the module receives ACK from the parent node during the polling failure accumulation, the accumulation will be cleared.

    • Trigger rejoin
      Two unaffiliated methods to trigger rejoin are available currently:

      • Application layer sends data.
      • Period trigger: The module is offline, and rejoin is triggered periodically until the module rejoins the previous network.

      Note: Successful rejoin only indicates that the module can communicate with the parent node properly. Whether the data can be sent to the gateway depends on the routing between the gateway and the parent node. Both parameters can be configured by the MCU currently.

    • Rejoin intervals
      The interval at which rejoin is triggered periodically. If real-time data or low power is required, the rejoin interval can be shorter, such as three to five seconds. For sensors or scenarios triggered by data reporting, the interval can be longer, such as one hour.

    • Rejoin attempt
      Rejoin attempt refers to the number of times that the module can send rejoin commands after the device triggers rejoin. For devices that require short polling time and interval, the number of attempts can be reduced, such as one to two times. If a longer rejoin interval is required, the attempts can be slightly increased, such as three to four times.

      Note: If the set parameter value is not within the value range, the parameter value will be invalid.

The MCU sends the following command:

Field
Length (byte)
Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x26
Data length 2 0x0e
Data 2 Heartbeat time (seconds)
Only the heartbeat of low-power devices can be modified. The default heartbeat of low-power devices is four hours, and the value range is from 10 to 18,000 seconds.
  • 0xffff: Current value.
  • 0xfffe: Default value.
2 Pairing timeout time (seconds)
The default timeout is 180 seconds, and the value range is from 30 to 600 seconds.
  • 0xffff: Current value.
  • 0xfffe: Default value.
2 Rejoin interval (seconds)
The value range is from 3 to 3600 seconds, and the default value is 180 seconds. When the device loses its parent node, it will try to rejoin every 180 seconds.
  • 0xffff: Current value.
  • 0xfffe: Default value.
2 Poll time (milliseconds)
The default value is 5,000 ms, and the value range is from 200 to 10,000 ms. The module will wake up once every polling period to confirm whether the parent node has data to send. For sensors that only report data, this value can be set to 0.
  • 0: Disable polling.
  • 0xffff: Current value.
  • 0xfffe: Default value.
2 The time period of fast polling (seconds).
The value range is from 10 to 3,000 seconds. The duration of fast polling after power on. The duration is 250 ms. When fast polling completes, the polling will run according to the set polling time, and the default value is 30 seconds.
  • 0xffff: Current value.
  • 0xfffe: Default value.
1 The times of polling failure.
The value range is from 3 to 40. When the maximum value is reached and the rejoin triggering time is set, the device will trigger rejoin when the time is reached.
  • 0xFF: Current value.
  • 0xfe: Default value.
1 Whether to trigger rejoin when the application data is sent.
0 means that rejoin is not triggered. 1 means that rejoin is triggered. The value is 1 by default.
  • 0xFF: Current value.
  • 0xfe: Default value.
1 The rejoin attempts.
The default value is 1. Value range: 1 to 100.
  • 0xFF: Current value.
  • 0xfe: Default value.
1 The transmit power.
The default value is 11. Value range: 3 to 19 dB.
  • 0xFF: Current value.
  • 0xfe: Default value.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x02
Serial number 2 N
Command 1 0x026
Data length 2 0x0001
Data 1
  • 0x00: Failure
  • 0x01: Success
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Change history

| Major changes | Revision date | Description |
|- |- |- |- |-
| Create Document | 20180623 | First Draft |
| Revision | 20180628 | 1. Modify the timeout period
2. Modify passive upload method
3. Modify module configuration method |
| Revision | 20180702 | 1. Add passive upload and timeout retransmission mechanism
2. Add hardware handshake I/O | Revision | 20180731
| Revision | 20180731 | 1. Add scene switching protocol
| Revision | 20181029 | 1. Add reliability transmission
2. Add wake-up mechanism for sleep mode
| Add network status during pairing | 20200204 | Add the status description of the network status during pairing | | Optimization
| Optimize the protocol content | 20200715 | 1. Range of sequence
2. Data length modified to 62
3. Default to Channel 11 when the incoming channel is illegal during RF test
4. Add protocol description |
| Add protocol | 20200801 | 1. Add frames that the module can query
2. Add frames of network status that the MCU can set |
| Optimize protocol | 20201118 | 1. Specify that the wake-up methods can be the voltage level or pulse. Both methods are compatible and apply to the situation where the MCU wakes up the module and the module wakes up the MCU.
2. Specify that the rejoin period in network parameters is the time when long-time rejoin fails. |