MCU Integration Protocol for Gateway

Last Updated on : 2022-11-24 09:20:17download

Tuya Wi-Fi serial port protocol is a customized protocol for Wi-Fi modules. It is used for serial port communication between Tuya Wi-Fi modules and other MCU serial ports.

The architecture diagram is shown as follows.

MCU Integration Protocol for Gateway

Serial communication convention

  • Baud: 115200
  • Data bit: 8
  • Parity check: none
  • Stop bit: 1
  • Data flow control: none
  • MCU: the control chip of the control board, connecting to the Tuya module through the serial port

Frame format

Field Length (byte) Description
Header 2 It is fixed as 0x55aa
Version 1 MCU software version number used for upgrading and extension
Command 1 Specific command
Data length 2 In big-endian mode
Data Depend on specific data Data transmitted
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data unit format

Field Bytes Description
dpid 1 The identifier of a DP (DP ID).
type 1 It indicates the data type of a DP defined on the Tuya IoT Development Platform.
  • raw: Represents a DP of raw data type.
    • Value: 0x00
    • Byte(s): N
  • bool: Represents a DP of Boolean data type. The valid values are 0x00 and 0x01.
    • Value: 0x01
    • Byte(s): 1
  • value: Represents a DP of integer data type, in big-endian format.
    • Value: 0x02
    • Byte(s): 4
  • string: Represents a DP of string data type.
    • Value: 0x03
    • Byte(s): N
  • enum: Represents a DP of enum data type, ranging from 0 to 255.
    • Value: 0x04
    • Byte(s): 1
  • bitmap: Represents a DP of fault data type. Data greater than one byte is transmitted in big-endian format.
    • Value: 0x05
    • Byte(s): 1, 2, or 4
len 2 The length is the number of bytes of the value.
value 1/2/4/N Represented in hexadecimal format. Data greater than one byte is transmitted in big-endian format.

Basic protocol

Query product information

Product information consists of product ID (PID) and the MCU software version.

  • PID: Corresponding to the product ID (PID) on the Tuya IoT Platform. It is generated by 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 (0 ≤ x ≤ 99), and x is a decimal digit.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 The following two versions are supported:
  • 0x00: The PID cannot be obtained
  • 0x01: The PID can be obtained
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 00 01 0000 00

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00 or 0x01
Command 1 0x01
Data length 2 N
Data Depend on specific data See the example
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, {"v":"1.0.0", "m":1, "cap":0, "p":"mhnmpqzf7ntzm***", "n":0, "s":0, "a":0}

  • V: the version number of MCU. For example, 1.0.0.

  • m: pairing method.

    • 0: default pairing
    • 1: low power consumption
    • 2: special pairing
  • cap: Capabilities supported by the device. The value has been converted from hexadecimal to decimal. The corresponding functions of the bits are as follows:

    • bit0: local group

    • bit1: local scenario

    • bit2: data point (DP)

    • bit3: SIG mesh

    • bit4: MCU upgrade

    • bit5: group control command with sub_id

    • bit6: Bluetooth serial port pairing, with the access point (AP) mode by default

      Note: For example, the device does not support local groups (bit0 is 0) or local scenario (bit1 is 0), but supports DPs (bit2 is 1). The hexadecimal data is 0000 0000 0000 0100, that is, the cap value is 4.

  • p: product ID (PID). The PID in the example is mhnmpqzf7ntzm***.

  • n (optional): pairing mode.

    • Without this field: Switch between SmartConfig and AP pairing modes.

    • 0: Indicates that both SmartConfig and AP pairing modes are available.

      Note: After this pairing mode is selected, the command operation in the Reset Wi-Fi and select the pairing mode section will be invalid. The SmartConfig and AP pairing mode will remain after reset.

    • 1: Only supports AP pairing mode.

      Note: In this mode, the pairing can only be implemented through AP connection. After this pairing mode is selected, the command operation in the Reset Wi-Fi and select the pairing mode section will be invalid. The AP pairing mode will remain after reset.

  • s (optional): indicates whether the gateway is a security gateway and requires security capability support. Security capability is not supported by default.

    • 0: general gateway without security capability.
    • 1: security gateway with security capability.
  • a (optional): device function capability value. The data is 1 byte, equivalent to 8 bits, and each bit corresponds to a function. The MCU must use the corresponding function.

    • bit0: When it indicates the security gateway function, determine whether the security alarm message is displayed. 0 means not supported, and 1 means supported.

    Note: For the newly connected gateway, bit0 shall be set to 1 to reduce the MCU development workload. The corresponding command is 0xC104.

    • bit1bit7: reserved data points. 0 shall be entered by default.

Query working mode of the module set by MCU

The working mode of the module mainly includes how to indicate Wi-Fi working status and how to reset the Wi-Fi network. There are two cases.

  • The coordinated processing of the MCU and module

    • Wi-Fi working status is displayed by the MCU.
    • Wi-Fi reset: The MCU detects the Wi-Fi reset requirement, and through the serial port, notifies the module to reset.
  • The self-processing mode of the module

    • Wi-Fi working status is displayed by the LED driven by Wi-Fi GPIO pin.
    • Wi-Fi reset: The Wi-Fi is reset by detecting GPIO input requirement. Wi-Fi detects the low level of GPIO input pin for more than 5 seconds to trigger the Wi-Fi reset. The GPIO pins used by the indicators and buttons are configured by the following commands.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
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 00 02 0000 01

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x02
Data length 2
  • 0x0000: the coordinated processing of the MCU and module. The MCU implements the functions mentioned in the Reset Wi-Fi and select the pairing mode section.
  • 0x0004: the self-processing mode of the module.
Data 0/2 The data length is 4, and the port range is 0–3, which represents A–D respectively. The pin range is 0–7.
  • Data[0]: the port of the Wi-Fi indicator
  • Data[1]: the pin of the Wi-Fi indicator
  • Data[2]: the port of the reset button
  • Data[3]: the pin of the reset button
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Example:

  • 0x55aa 00 02 0000 04 (coordinated processing of the MCU and the mode)
  • 0x55aa 00 02 0004 0103 0102 0C (self-processing of the module, indicator 0x0103: PB_3, and reset button 0x0102: PB_2)

Report the network status of the device

Note: If the working mode of the module is set to module self-processing, the MCU does not need to implement this protocol.

  • When the module detects that the MCU reboots or is disconnected and then go back online, the module will send the Wi-Fi status to the MCU.
  • When the Wi-Fi status of the module changes, the Wi-Fi status is sent to the MCU.
Network status of device Description Status value
Status 1 SmartConfig pairing status 0x00
Status 2 AP pairing status 0x01
Status 3 Wi-Fi has been configured, but not connected to the router 0x02
Status 4 Wi-Fi has been configured, and connected to the router 0x03
Status 5 Wi-Fi has been connected to the router and the cloud 0x04
Status 6 Wi-Fi device is in the low power consumption mode 0x05
Status 7 Both SmartConfig and AP pairing status are available 0x06

The status of LED indicator in module self-processing mode.

  • 1: flicker at 250 milliseconds intervals
  • 2: flicker at 1,500 milliseconds intervals
  • 3: off
  • 4: always on
  • 5: always on
  • 6: off
  • 7: flicker at 250 milliseconds intervals

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x03
Data length 2 0x0001
Data 1 Indicate the Wi-Fi working status.
0x00: status 1
0x01: status 2
0x02: status 3
0x03: status 4
0x04: status 5
0x05: status 6
0x06: status 7
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 00 03 0001 00 03

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
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 00 03 0000 02

Reset Wi-Fi

Note: If the working mode of the module is set to module self-processing, the MCU does not need to implement this protocol.

  • Status transfer of resetting Wi-Fi is shown as follows:

    MCU Integration Protocol for Gateway

  • Reset Wi-Fi in self-processing mode: Wi-Fi detects the low level of GPIO input pin for more than 5 seconds to trigger Wi-Fi reset.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x04
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 00 04 0000 03

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x04
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 00 04 0000 03

Reset Wi-Fi and select the pairing mode

Note: If the working mode of the module is set to module self-processing, the MCU does not need to implement this protocol.

You can implement this protocol selectively.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x05
Data length 2 0x0001
Data 1 0x00: enter SmartConfig pairing mode
0x01: enter AP pairing mode
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 00 05 0001 00 05, enter SmartConfig pairing mode.

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x05
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 00 05 0000 04

Enable the access of sub-devices

The app sends a network access command to the gateway, enabling the sub-device to access the network within a specified time.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x06
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 MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x06
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

Disable the access of sub-devices

The app sends a command to the gateway, disabling the access of sub-devices.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x07
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 MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x07
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

Add a sub-device

  • The MCU sends the network access request of the sub-device to Wi-Fi.

  • pk_type is an optional field, and the default value is 1.

  • The channel must be configured when the sub-device needs an OTA function. The default value is 10. Go to Hardware Development > Add custom firmware > Upgrade Channel.

    Note: Incorrect channel configuration might cause exceptional OTA function.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x08
Data length 2 N
Data N
  • Data example:
    {
    “pk_type”:xx
    “sub_id”:“xxxx”,
    “pid”:“xxxx”,
    “ver”:“x.x.x”,
    “channel”:xxx,
    “ota”:x
    }
  • Parameter description
    • pk_type: user-defined product type, but not required.
    • sub_id: the unique identifier of the sub-device, usually MAC address, chip ID, and the like. It cannot be 0000.0000, which represents the general identifier of the gateway itself.
    • pid: product ID (PID).
    • ver: version number. For example, 1.0.0.
    • channel: channel number. Correspond to the upgrade channel number of the extended firmware after the product is created on the Tuya Cloud. It is 10 by default.
    • ota: Indicates whether to support OTA. The OTA is not supported by default. 0: not support. 1: support.
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 0x00
Command 1 0x08
Data length 2 0x0001
Data 1 0x00: Receive request
0x01: Reject request (To check whether the sub-device is actually successfully connected to the network, see Return the result of adding a device)
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Delete a sub-device

The app sends a command to the gateway, disabling the access of sub-devices.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x09
Data length 2 None
Data Depend on specific data
  • Data example:
    {
    “sub_id”:“xxxx”,
    “devkey”:“xxx”,
    “tp”:xx
    }
  • Parameter description
    • sub_id: the ID of the sub-device to be deleted.
    • Devkey (optional): device key, used to remove the sub-device.
    • tp
      • 0: delete the sub-device.
      • 1: restore factory defaults on the app.
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 0x00
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

Heartbeat detection

The Wi-Fi module regularly queries the heartbeat of the sub-device. The query cycle is related to the number of sub-devices. The more the sub-devices are, the more frequently the heartbeat of the sub-devices are queried.

MCU Integration Protocol for Gateway

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0A
Data length 2 None
Data Depend on specific data
  • Data example: {“sub_id”:“xxxx”}
  • Parameter description: sub_id is the ID of the sub-device.
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:

Note: An online device shall return its heartbeat. If it does not respond for two consecutive heartbeat cycles, it is considered offline.

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0A
Data length 2 None
Data Depend on specific data
  • Data example: {“sub_id”:“xxxx”,“lp”:x}
  • Parameter description
    • sub_id: the ID of the sub-device
    • lp: power consumption type of the sub-device
      • 0: device with standard power consumption
      • 1: device with low power consumption
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Query the status

Synchronize the sub-device status.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0B
Data length 2 None
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 the command returned by the MCU, see the Report status section.

Send a command

Send a control command.

  • For DP commands and status data units, except the raw type, all other types belong to the obj type data points.
  • Multiple data point commands can be sent at the same time.
  • The asynchronous processing protocol is used to send the command, corresponding to the Report the status of the MCU.

DP command or status data unit is shown as follows.

Data segment Length (byte) Description
dpid 1 DP number
type 1 The specific data type of a data point in the Tuya IoT Platform:
  • raw: the raw data points (module pass-through)
    • Value: 0x00
    • Length (byte): N
  • bool: the Boolean data points, 0x00 or 0x01
    • Value: 0x01
    • Length (byte): 1
  • value: corresponding to integer type, in big-endian mode
    • Value: 0x02
    • Length (byte): 4
  • String: string type
    • Value: 0x03
    • Length (byte): N
  • enum: enumeration type, ranging from 0 to 255
    • Value: 0x04
    • Length (byte): 1
  • bitmap: fault type and adopt big-endian transmission when there are more than 1 byte
    • Value: 0x05
    • Length (byte): 1, 2, or 4
len 2 The length corresponds to the byte number of the value (big-endian)
value 1/2/4/N Expressed with hex, and adopt big-endian transmission when there are more than 1 byte

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0C
Data length 2 None
Data Depend on specific data
  • Data example: id_len(1byte) + sub_id(nbyte)+ datapoint
  • Parameter description
    • id_len: length of sub-device ID
    • sub_id: the ID of the sub-device
      Note: When sub_id is 0000, it means the command is sent to the data point of the gateway itself (the master device)
    • datapoint: a collection of control command data points
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Report the status

The sub-device responds after receiving the command, or actively pushes the command after receiving the status change.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0D
Data length 2 None
Data Depend on specific data
  • Data example: id_len(1byte) + sub_id(nbyte)+ datapoint
  • Parameter description
    • id_len: length of sub-device ID
    • sub_id: the ID of the sub-device
      Note: When sub_id is 0000, it means the command is sent to the data point of the gateway itself (the master device)
    • datapoint: a collection of control command data points
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Add sub-devices to groups

Add sub-devices to local groups.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0E
Data length 2 None
Data Depend on specific data
  • Data example: Sub-devices 12, 34 and 56 join group 01, so the data is displayed as {"gid":"01", "cids":["12","34","56"]}
  • Parameter description
    • gid: group ID
    • cids: an ID collection of sub-devices that join the group
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 0x00
Command 1 0x0E
Data length 2 None
Data Depend on specific data
  • Data example: { "gid":"12", "cids":["12","34","56"], "rets":[0,0,0] }
  • Parameter description
    • gid: group ID
    • cids: a collection of sub-devices that join the group
    • rets: return results
      • 0: added successfully
      • 1: exceeded the maximum number of groups
      • 2: sub-device timeout
      • 3: The set value is out of range
      • 4: Error writing to file
      • 5: Other errors
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Remove a sub-device from a group

Remove a sub-device from a local group.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0F
Data length 2 None
Data Depend on specific data
  • Data example: Sub-device 12 is removed from group 01, {"gid":"01", "cids":["12"]}
  • Parameter description
    • gid: group ID
    • cids: an ID collection of sub-devices
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 0x00
Command 1 0x0F
Data length 2 None
Data Depend on specific data
  • Data example: { "gid":"01", "cids":["12"], "rets":[0] }
  • Parameter description
    • gid: group ID
    • cids: a collection of sub-devices that join the group
    • rets: return results
      • 0: added successfully
      • 1: exceeded the maximum number of groups
      • 2: sub-device timeout
      • 3: The set value is out of range
      • 4: Error writing to file
      • 5: Other errors
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Get the GMT time of the system

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x10
Data length 2 0x0000
Data 0 For example, 0x55aa 00 10 0000 0F
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 0x00
Command 1 0x10
Data length 2 0x0007
Data 7
  • Data example: 0x55aa 00 10 0007 01 10 04 13 05 06 07 50, which is 05:06:07, April 19, 2016 in the format of Greenwich Mean Time (GMT).
  • Parameter description
    • Data[0]: whether to obtain the time successfully. 0 indicates failure and 1 indicates success.
    • Data[1]: the year, for example, 0x00 indicates the year of 2000
    • Data[2]: the month, ranging from 1 to 12
    • Data[3]: the day, ranging from 1 to 31
    • Data[4]: the hour, ranging from 1 to 23
    • Data[5]: the minute, ranging from 1 to 59
    • Data[6]: the second, ranging from 1 to 59
    Note: The date range is 1 to 31, which is 01–1f in hexadecimal notation. The hexadecimal number 13 corresponds to the decimal number 19, that is, the date is 19.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Get the local time

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x11
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 0x00
Command 1 0x11
Data length 2 0x0008
Data 8
  • Data example: 0x55aa 00 10 0007 01 10 04 13 05 06 07 02 54, which is 05:06:07 Tuesday, April 19, 2016 GMT.
  • Parameter description
    • Data[0]: whether to obtain the time successfully. 0 indicates failure and 1 indicates success.
    • Data[1]: the year, for example, 0x00 indicates the year of 2000
    • Data[2]: the month, ranging from 1 to 12
    • Data[3]: the day, ranging from 1 to 31
    • Data[4]: the hour, ranging from 1 to 23
    • Data[5]: the minute, ranging from 1 to 59
    • Data[6]: the second, ranging from 1 to 59
    • Data[7]: the week, ranging from 1 to 7, and 1 indicates Monday
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Note:

  • If the device is activated in mainland China, the local time is Beijing time (GMT+08:00).
  • If the device is activated in other countries or regions, the local time is the time zone in which the device is.

Add devices in batches

Add multiple sub-devices of the same PID in batches. Maximum 32 sub-devices can be added in a single batch.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x12
Data length 2 None
Data Depend on specific data
  • Data example:
    { "pid":" xxxx", "cids":["12","34","56"], "ver":"x.x.x","channel":xxx,"ota":x}
  • Parameter description
    • pid: product ID (PID).
    • cids: an ID collection of sub-devices
    • ver: version number. For example, 1.0.0
    • channel: the channel number to upgrade a sub-device, which corresponds to the upgrade channel number of the extension firmware uploaded after the product is created on the IoT Platform. The default is 10.
    • ota: whether a sub-device supports OTA. The OTA is not supported by default.
      • 0: not supported
      • 1: supported
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 0x00
Command 1 0x12
Data length 2 None
Data 1
  • 00: data is received successfully
  • 01: failed to receive or parse the data
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return the result of adding a device

After the device is added, notify the MCU of the result.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x13
Data length 2 N
Data N
  • Data example:
    {
    “cids”:[“12”,“34”,“56”],
    “rets”:[0,0,0],
    “key”:[“xxxx”,“xxx”],
    “virt_id”: [“xxxx”,“xxx”]
    }
  • Parameter description
    • cids: an ID collection of sub-devices
    • channel: the channel number to upgrade a sub-device, which corresponds to the upgrade channel number of the extension firmware uploaded after the product is created on the IoT Platform. The default is 10.
    • ota: whether a sub-device supports OTA. The OTA is not supported by default.
      • 0: not supported
      • 1: supported
    • key: the key is optional, only supported by a BLE device
    • virt_id: the virtual ID is optional, only supported by a BLE device
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 0x00
Command 1 0x13
Data length 2 0000
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

Send commands to control the group

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x14
Data length 2 None
Data Depend on specific data
  • Data example: id_len(1byte) + grp_id(nbyte)+ datapoint
  • Parameter description
    • id_len: length of group ID
    • grp_id: group ID
    • datapoint: a collection of control command data points
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 0x00
Command 1 0x14
Data length 2 0000
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

Wi-Fi functional test

Scan the specific SSID: tuya_mdev_test, and return the scanning result and signal strength percentage.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x15
Data length 2 0x0000
Data Data 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 0x00
Command 1 0x15
Data length 2 0x0002
Data 2
  • Data[0]:
    • 0x00: failure
    • 0x01: success
  • Data[1]:
    • When Data[0] is 0x00, Data[1] indicates signal strength (from 0 to 100, 0 for the weakest and 100 for the strongest)
    • When Data[0] is 0x01:
      • Data[1] is 0x00: the specified SSID has not been found
      • Data[1] is 0x01: the authorization key is not burned 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

Get Wi-Fi status

The MCU can get the Wi-Fi status with this command. For specific Wi-Fi status, see Report device network status. The gateway will not return the Wi-Fi status before the network initialization is completed.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x16
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 0x00
Command 1 0x16
Data length 2 0x0001
Data 1 Wi-Fi working status:
0x00: status 1
0x01: status 2
0x02: status 3
0x03: status 4
0x04: status 5
0x05: status 6
0x06: status 7
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Restore factory defaults (optional)

If a local (offline) command is sent to restore factory defaults, the cloud information and the local information will be out of sync. The command must be used when the device is online or before the device is activated for the first time.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x17
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

Report removal status

When receiving the command to remove a sub-device or restore the factory defaults, the gateway will report the status to the MCU.

  • If only the removal command is received, the gateway will only remove the pairing, and will not delete the sub-device information. The next time you connect to the internet, the sub-device information will still be displayed on the app.
  • If a command of restoring factory defaults is received, the gateway will remove the pairing and clear all sub-device information.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x18
Data length 2 0x0001
Data 1
  • 0x00: locally restore factory defaults
  • 0x01: remote removal
  • 0x02: local removal
  • 0x03: remotely restore factory defaults
  • 0x04: clear the data, but the gateway does not exit the network
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Delete a sub-device locally

MCU sends a command to delete a sub-device.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x19
Data length 2 None
Data Depend on specific data For example, { “sub_id”:“xxx” }
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 0x00
Command 1 0x19
Data length 2 0x0001
Data 1
  • 0x00: deleted successfully
  • 0x01: failed to delete
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Locally allow/disallow adding sub-devices

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1A
Data length 2 0x0003
Data 3
  • Data[0]:
    • 00: disallow adding sub-devices
    • 01: allow adding sub-devices
  • Data[1]: allow adding time (high byte)
  • Data[2]: allow adding time (low byte)
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 0x00
Command 1 0x1A
Data length 2 0x0001
Data 1
  • 00: success
  • 01: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Get module memory

Get the remaining memory of the Wi-Fi module.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x1B
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 0x00
Command 1 0x1B
Data length 2 0x0004
Data 4 The data length is 4 bytes in big endian mode. For example, 00 00 28 00 represents the remaining memory is 10,240 bytes.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Query the list of sub-devices

The MCU can query the list of all sub-devices under the gateway. If greater than 255 bytes, the list data will be sent in packets.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1C
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 0x00
Command 1 0x1C
Data length 2 None
Data Depend on specific data
  • Data example: id(1byte)+sub_num(1byte)+sub1_len(1byte)+sub1_id+….. subn_len(1byte)+subn_id(1byte)
  • Parameter description
    • id:
      • 07:
        • false: all sub-device addresses have been sent
        • true: more sub-device addresses will be sent in the next data packet
      • 00 to 06: packet number starting from 0
    • sub_num: the number of sub-devices included in this packet
    • sub1_len: length of sub-device ID
    • sub1_id: the ID of the sub-device
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Remote upgrade service

The IoT Platform provides visualized configuration options, allowing users to choose the upgrade method. The module only serves as a data transmission channel that supports MCU upgrades and does not perform any data analysis.

Note: After all the upgrade packets are sent, the Wi-Fi module sends the command 0x01 to query product information. The MCU shall reply with the software version number and the upgraded MCU software version number in the product information within one minute. The version number shall be consistent with that configured and upgraded on the Tuya IoT Platform.

  • MCU remote upgrade methods:

    • App notification upgrade: You choose to upgrade or not when the app receives an upgrade prompt.
    • App forced upgrade: There is an upgrade prompt on the app. You are required to upgrade the device before you continue to use it.
    • App detects update: There is no upgrade prompt on the app. You must detect the relevant firmware version on the app and upgrade.
  • Auto upgrade (former silent upgrade): The app does not prompt the user to upgrade. The upgrade detection will be performed within one minute after the firmware is powered on. If a higher version upgrade packet is detected, it will be automatically downloaded and installed. Since the first power-on, upgrade detection will be performed every 24 hours.

  • MCU upgrade flowchart:

    MCU Integration Protocol for Gateway

MCU starts upgrade

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1D
Data length 2 0x0004
Data 4 Upgrade file size in the big-endian mode
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 0x00
Command 1 0x1D
Data length 2 0x0001
Data 1 Upgrade packet transmission size:
  • 0x00: default value, 256 bytes (compatible with old firmware)
  • 0x01: 512 bytes
  • 0x02: 1024 bytes
  • 0x03: 128 bytes
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

MCU upgrade packet transmission

  • The data format of upgrade packet transmission: packet offset (unsigned short) + packet data.
  • If MCU receives the frame with data length equal to 4 and the upgrade packet offset is equal to or greater than the size of firmware, the packet transmission ends.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1E
Data length 2 0x0004+m in which m is the offset byte
Data offset_addr (4 bytes)+ pack (m bytes) offset_addr: packet offset address
pack: packet content
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, the file to be upgraded has 530 bytes. Under this circumstance, the MCU can skip the response to the last data packet.

  • For the first packet data, packet offset is 0x00000000, and the data packet length is 256.

    0x55aa 00 1e 0104 00000000 xx…xx XX

  • For the second packet data, packet offset is 0x00000100, and data packet length is 256.

    0x55aa 00 1e 0104 00000100 xx…xx XX

  • For the second to last packet data, packet offset is 0x00000200, and data packet length is 18.

    0x55aa 00 1e 0016 00000200 xx…xx XX

  • For the last packet data, packet offset is 0x00000212, and data packet length is 0.

    0x55aa 00 1e 0004 00000212 XX

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1E
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

A sub-device starts upgrade

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1F
Data length 2 None
Data Depend on specific data
  • Data example: id_len(1byte) + sub_id(nbyte)+ file_size(4byte)
  • Parameter description
    • id_len: length of sub-device ID
    • sub_id: the ID of the sub-device
    • file_size: Upgrade file size in the big-endian mode
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 0x00
Command 1 0x1F
Data length 2 0x0001
Data 1 Packet size of the upgrade packet:
0x00: 256 bytes by default (compatible with old firmware)
0x01: 512 bytes
0x02: 1,024 bytes
0x03: 128 bytes
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Sub-device upgrade packet transmission

  • The data format of upgrade packet transmission: packet offset (unsigned short) + packet data.
  • If MCU receives the frame with data length equal to 4 and the upgrade packet offset is equal to or greater than the size of firmware, the packet transmission ends.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x20
Data length 2 None
Data Depend on specific data
  • Data example: id_len(1byte) + sub_id(nbyte)+ offset_addr(4byte)+ pack(mbyte)
  • Parameter description
    • id_len: length of sub-device ID
    • sub_id: the ID of the sub-device
    • offset_addr: packet offset address
    • pack: data packet
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Example: sub_id is 1234, the file size to be upgraded is 530 bytes. Under this circumstance, the MCU can skip the response to the last data packet.

  • For the first packet data, packet offset is 0x00000000, and the data packet length is 256.

    0x55aa 00 20 0109 04 31 32 33 34 00000000 xx…xx XX

  • For the second packet data, packet offset is 0x00000100, and data packet length is 256.

    0x55aa 00 20 0109 04 31 32 33 34 00000100 xx…xx XX

  • For the second to last packet data, packet offset is 0x00000200, and data packet length is 18.

    0x55aa 00 20 001B 04 31 32 33 34 00000200 xx…xx XX

  • For the last packet data, packet offset is 0x00000212, and data packet length is 0.

    0x55aa 00 20 0009 04 31 32 33 34 00000212 XX

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x20
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

Query the version number of a sub-device

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x21
Data length 2 None
Data Depend on specific data
  • Data example: {"sub_id":"xxx"}
  • Parameter description: sub_id is the ID of the sub-device.
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 0x00
Command 1 0x21
Data length 2 None
Data Depend on specific data
  • Data example: {"sub_id":"xxx", "ver":"xx.xx.xx"}
  • Parameter description
    • sub_id: the ID of the sub-device
    • ver: firmware version number of the sub-device
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Send commands to control the group (with sub_id)

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x22
Data length 2 None
Data Depend on specific data
  • Data example: grp_len(1byte) + grp_id(nbyte)+ sub_len(1byte) + sub_id(mbyte)+ datapoint
  • Parameter description
    • grp_len: length of group ID
    • grp_id: group ID
    • sub_len: length of the specified sub-device ID in the group
    • sub_id: the ID of the sub-device
    • datapoint: a collection of control command data points
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 0x00
Command 1 0x22
Data length 2 0000
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

Pairing through the serial port (integrated)

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x23
Data length 2 None
Data Depend on specific data
  • Data example: { "s":"xxx", "p":"yyy", "t":"zzz" }
  • Parameter description
    • s: SSID
    • p: password
    • t: token, generated by the app
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 0x00
Command 1 0x23
Data length 2 0x0001
Data None
  • 0x00: success
  • 0x01: not in the pairing status
  • 0x02: Illegal JSON data
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Pass-through pairing through the serial port (distributed)

Wi-Fi sends a broadcast packet

The data packet is passed from the Wi-Fi module to the MCU module for broadcast.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x24
Data length 2 None
Data Depend on specific data Broadcast packet data
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 0x00
Command 1 0x24
Data length 2 0x0002
Data 2 Return status:
data[0]:
0x00: success
0x01: failure
data[1]:
0: success
fail: failure reason
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU sends pairing information

Data packets are transparently transmitted to Wi-Fi by the app through the MCU.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x25
Data length 2 None
Data data Encryption data
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 0x00
Command 1 0x25
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

Wi-Fi reports pairing information

Data packets are transparently transmitted to the app by the Wi-Fi through the MCU.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x26
Data length 2 N
Data Depend on specific data Encryption data
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 0x00
Command 1 0x26
Data length 2 0x0000
Data None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

MCU connection status

The MCU will actively push the connection status with the mobile phone to the Wi-Fi module.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x27
Data length 2 0x0001
Data 1 Connection status:
0x00: disconnected
0x01: connection established
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Wi-Fi module is disconnected actively

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x28
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 MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x28
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

Query the DP status

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x29
Data length 2 N
Data Depend on specific data
  • Data example: { "sub_id":"xxx", "dpid":[xx,xx,xx] }
  • Parameter description
    • sub_id: the device ID
    • dpid: the corresponding DPID array
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 status report.

Update online/offline status of the sub-device

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2A
Data length 2 N
Data Depend on specific data
  • Data example: {"all":0,"cids":["xxx","xxx"],"state":1} or {"all":1,""state":1}
  • Parameter description
    • all:
      • 0: contains only data of cids
      • 1: contains all sub-devices, without the cdis field
    • cids: an ID collection of devices
    • state:
      • 0: offline
      • 1: online
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 0x00
Command 1 0x2A
Data length 2 0x0001
Data 1 0x00: success
0x01: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Get the MAC address of the module

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2B
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 0x00
Command 1 0x2B
Data length 2 0x0007
Data Depend on specific data
  • data[0]: Whether the MAC address is got successfully.
    • 0x00: success
    • 0x01: failure
  • data[1]–data[6]: MAC address of the module
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Real-time reporting of record type status (with time)

  • For record type sub-devices such as door locks, when reporting the DP status, the timestamp that generated these records shall be included.
  • This is a synchronous upstream interface. After the MCU data is reported, the MCU waits for the module to return information to determine whether the sending operation is successful.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2C
Data length 2 None
Time 7
  • Data[0]: Whether the data transmission has a time flag
    • 0x00: without the time, the module regards the data to be invalid and will not process
    • 0x01: report the local time (date format)
    • 0x02: report the Greenwich Mean Time (GMT, date format)
    • 0x03: time data bit timestamp, precision to seconds
  • When Data[0] is 0x01 or 0x02
    • Data[1]: the year, for example, 0x00 indicates the year of 2000
    • Data[2]: the month, ranging from 1 to 12
    • Data[3]: the day, ranging from 1 to 31
    • Data[4]: the hour, ranging from 1 to 23
    • Data[5]: the minute, ranging from 1 to 59
    • Data[6]: the second, ranging from 1 to 59
  • When Data[0] is 0x03:
    • data[1]–data[4]: 4-byte timestamp in big-endian mode
    • data[5]–data[6]: filled with 0
Data Depend on specific data
  • Data example: { id_len(1byte)+sub_id(nbyte)+datapoint}
  • Parameter description
    • id_len: length of sub-device ID.
    • sub_id: the ID of the sub-device. When sub_id is 0000, it means the DPs of the gateway (master device) are reported.
    • datapoint: a collection of status command data points.
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 0x00
Command 1 0x2C
Data length 2 0x0001
Data 1 0: success
1: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Query the binding status of sub-devices

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2D
Data length 2 None
Data Depend on specific data
  • Data example: {"sub_id":"xxx", "d_link":x "e_val":"xxx"}
  • Parameter description
    • d_link: whether dual-link is available, that is, whether the sub-device supports both mobile phone and gateway binding.
      • 0: not supported
      • 1: supported
    • e_val: encrypted value, optional field.
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 0x00
Command 1 0x2D
Data length 2 0x0007
Data Depend on specific data
  • Data example: {"sub_id":"xxx", "ret":x}
  • Parameter description
    • sub_id: the ID of the sub-device
    • ret: current binding status of the sub-device
      • 0: successful binding with the gateway
      • 1: there is a sub-device record in the gateway but it is not bound (the sub-device is being bound or there is no such sub-device record in the cloud)
      • 3: bind to the mobile phone, but not to the gateway
      • 4: not bound to the gateway, and the binding to the mobile phone is unknown
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Query the information of sub-devices in the group

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2E
Data length 2 N
Data Depends on specific data
  • Data example: { "gid":"xxx", "idx":xx}
  • Parameter description
    • gid: group ID.
    • idx: query the serial number of the sub-device. For example, 0 means to query the first sub-device.
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 0x00
Command 1 0x2E
Data length 2 None
Data Depend on specific data For example, {"gid":"xxx","sub_id":"xxxx" }
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Report DPs locally changed in group

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2F
Data length 2 N
Data Depend on specific data
  • Data example: {"gid":"xxx", "dpid":xx}
  • Parameter description
    • gid: group ID
    • dpid: There is a locally changed DPID in the group. After receiving the DP, the module will query the latest status of the DP in the group device.
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 0x00
Command 1 0x2F
Data length 2 0x0001
Data 1
  • 0: success
  • 1: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Infrared (IR) functions

Send IR control code

  • A single packet of IR code sent contains a maximum of 1,024 bytes.
  • For scenarios where multiple control codes need to be sent, such as voice control or TV control, the module will output the current number of sent codes. After receiving the IR code, the MCU needs to wait for the module to send the next IR code. If it is not received within 250 ms, the currently received IR code will be sent.
  • The default sending frequency of IR codes is 38 kHz.
  • The module that sends the IR code shall wait for the MCU to respond with an acknowledge timeout of 1 second.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x30
Data length 2 None
Data Depend on specific data
  • Sub-command: 1 byte, 0x00.
  • num: 1 byte.
    • High 4 bits: the number of control codes sent.
    • Lower 4 bits: the serial number of the currently sent control code. 0 means the first control code.
  • Repeat time: 1 byte, the number of retransmissions.
  • Freq: 4 bytes, the frequency of the current IR code.
  • Code len: 2 bytes, the total length of the current IR code. The code is counted with 2 bytes as a unit.
  • Offset: 2 bytes. To send long control codes, an offset notification is required. The offset of the first packet is 0.
  • IR code: 2 bytes are counted as a unit.
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 0x00
Command 1 0x30
Data length 2 0x0002
Data 2
  • Sub-command: 0x00
  • MCU status of receiving control codes:
    • 01: success
    • 02: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Learn IR control code

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x31
Data length 2 0x0002
Data 2
  • Sub-command: 0x00
  • Learning timeout: only supports 30 seconds by default, which is 1E.
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 0x00
Command 1 0x31
Data length 2 N
Data Depend on specific data
  • Sub-command: 1 byte, 0x00.
  • Freq: 4 bytes, the frequency of the current IR code.
  • Code len: 2 bytes, the total length of the current IR code. The code is counted with 2 bytes as a unit.
  • Offset: 2 bytes. To send long control codes, an offset notification is required. The offset of the first packet is 0.
  • IR code: 2 bytes are counted as a unit.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Example:

The module sends the following command:

55 AA 00 31 00 02 00 1E 50

The MCU returns the following command:

55 AA 00 31 00 75 00 00 00 94 FC 00 36 00 00 236f 236f 068e 0226 068e 0226 068e 0226 0226 0226 0226 0226 068e 0226 0226 0226 0226 0226 0226 0226 068e 0226 068e 0226 068e 0226 0226 0226 068e 0226 068e 0226 068e 0226 068e 0226 0226 0226 0226 0226 0226 0226 068e 0226 0226 0226 0226 0226 a9cf 236f 08ce 0226 82d5 82d5 85

Cancel learning

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x32
Data length 2 0
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 MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x32
Data length 2 0x0001
Data MCU status of receiving control codes:
  • 01: success
  • 02: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Extended function

Weather service

  • Weather service refers to obtaining weather data of the city where the device is activated, and currently supports 7-day weather forecast.
  • After the MCU actively obtains and activates the weather service of the module, the module actively notifies the MCU regularly.
  • For example, if request parameters are w.temp,w.pm25 and only w.temp is returned, the return parameters are less than the request parameters. In this case, check whether the request parameter name is correct. For more information, see the detailed parameter description of weather service.
  • For the field value of w.condition, see Weather UTF-8 code table.

Example:

w.humidity: 69, w.temp: 32, w.pm25: 10, w.condition: cloudy (UTF-8 code E5A49A E4BA91)

55 AA 00 21 00 40 01 0A 77 2E 68 75 6D 69 64 69 74 79 00 04 00 00 00 45 06 77 2E 74 65 6D 70 00 04 00 00 00 20 06 77 2E 70 6D 32 35 00 04 00 00 00 10 0B 77 2E 63 6F 6E 64 69 74 69 6F 6E 01 06 E5 A4 9A E4 BA 91 1E

  • Input parameter: {"codes":"w.temp","w.humidity", "w.sunRise", "w.sunSet", "t.local","w.date.3"}

  • Return: {"codes": "w.temp.0":13,"w.humidity.0":100, "w.sunRise.0":2019-12-28 06:54,""w.sunSet.0":2019-12-28 17:05,"w.temp.1":13,"w.humidity.1":100, "w.sunRise.1":2019-12-28 06:54,""w.sunSet.1":2019-12-28 17:05,"w.temp.2":13,"w.humidity.2":100,"w.sunRise.2":2019-12-28 06:54,""w.sunSet.2":2019-12-28 17:05,}

The module regularly updates the weather service

Enable to get the weather data

Enable to get the weather data. The update cycle is set by the MCU. The minimum update interval is 10 minutes, while the recommended standard update interval is 60 minutes. Considering the real-time nature of weather data, the maximum interval is 240 minutes.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 (1+1+(L+K)+(L+K)…)
Data Depend on specific data
  • Sub-command: 1 byte, 0x00.
  • Regular update interval: 1 byte.
    • 0x00: the default value, the update interval is 60 minutes.
    • 0xFF: the update interval is 24 hours.
    • Others: the specific interval time in minutes. For example, 0x1E means update every 30 minutes.
  • L: 1 byte, indicating the length of K. For example, L:0x06.
  • K: the request parameter name. For example, K:w.temp.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Example: 55 AA 00 33 00 2C 00 00 06 77 2E 74 65 6D 70 0A 77 2E 68 75 6D 69 64 69 74 79 0A 77 2E 70 72 65 73 73 75 72 65 06 77 2E 70 6D 32 35 05 77 2E 73 6F 32 B0

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 0x0003
Data 3
  • Sub-command: 1 byte, 0x00.
  • Data[0]:
    • 0x00: the MCU failed to receive information. For specific error reasons, see the error code in Data[1].
    • 0x01: the MCU received information successfully.
  • Data[1]:
    • 0x00: no error.
    • 0x01: Illegal data format.
    • 0x02: exception.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder
Send weather data

After the weather data function is enabled, the module regularly sends the weather data. After the function is enabled, the data sending will be triggered immediately, and the data will be sent subsequently at the set time interval.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 (1+(LKTLV)+(LKTLV)+…)
Data Depend on specific data
  • Sub-command: 1 byte, 0x00.
  • MCU receiving status:
    • Failed to receive, with 2 bytes:
      • 0x00: failure.
      • 0x01: error code, indicating that the parameter service is not authorized. Confirm whether the parameter service has been purchased.
    • Successfully received, with 1 byte, which is 0x00.
  • L: 1 byte, indicating the length of K. For example, L:0x06.
  • K: the request parameter name. For example, K:w.temp.
  • T: parameter type.
    • 0x00: integer.
    • 0x01: string.
  • L: field name length.
  • V: field value.
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 0x00
Command 1 0x33
Data length 2 0x0001
Data 1 Sub-command: 0x01
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU gets weather service

  • When the MCU actively gets the weather service, the MCU carries the required weather service data content.
  • The frequency of using this command cannot be less than one minute, and multiple requests within one minute are processed only once.
  • This command is used to confirm the data request. The data is still sent through command 0x3301.

The MCU sends the following command:

Field Length Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 (1+1+(L+K)+(L+K)…)
Data Depend on specific data
  • Sub-command: 1 byte, 0x02.
  • L: 1 byte, indicating the length of K. For example, L:0x06.
  • K: the request parameter name. For example, K:w.temp.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Example: 55 AA 00 33 00 2B 02 06 77 2E 74 65 6D 70 0A 77 2E 68 75 6D 69 64 69 74 79 0A 77 2E 70 72 65 73 73 75 72 65 06 77 2E 70 6D 32 35 05 77 2E 73 6F 32 B1

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 0x0002
Data 1 Sub-command: 0x02
1 Result:
0x00: success
0x01: failure
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Send the time data with time zone system (GMT)

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 0x0001
Data 1 Command: 0x03
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 00 33 00 01 03 36

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x33
Data length 2 1+2+1+7
Data 11
  • Sub-command: 1 byte, 0x03.
  • Time zone: 2 bytes. For example, -750 means 7.5°W.
  • Daylight saving time (DST):
    • 0x00: none
    • 0x01: DST
  • Time data, 7 bytes:
    • Data[0]: whether to obtain the time successfully. 0 indicates failure and 1 indicates success.
    • Data[1]: the year, for example, 0x00 indicates the year of 2000
    • Data[2]: the month, ranging from 1 to 12
    • Data[3]: the day, ranging from 1 to 31
    • Data[4]: the hour, ranging from 1 to 23
    • Data[5]: the minute, ranging from 1 to 59
    • Data[6]: the second, ranging from 1 to 59
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Heartbeat query management

    For scenarios that do not require heartbeat query, you can use this command to pause the heartbeat query.

    The MCU sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x33
    Data length 2 0x0002
    Data 1 Sub-command: 0x04
    1 Heartbeat query status
    0x01: recover heartbeat query
    0x00: Disable heartbeat query
    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 00 33 00 02 04 00 38

    The module returns the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x33
    Data length 2 1
    Data 1 Sub-command: 0x04
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Security and sensor extension protocol

    This protocol contains security-related function commands, which only describes their content. For the detailed integration process, download the Connection Process of Security Gateway on the IoT Platform.

    Set the arming mode

    Set the current arming and disarming mode.

    • After entering the arming mode, disarm and then set the arming mode again.
    • At present, the arming delay time set by this command is invalid. The arming delay time is subject to the app settings. Pass 0 for the arming delay field data.

    The MCU sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC0
    Data length 2 1+N
    Data Depend on specific data
    • Sub-command: 0x00
    • For example, { mode:xxx, sub_id:xxxxx, delay:xx}
    • Parameter description
      • mode: arming mode
        • 0: disarming
        • 1: arming at home
        • 2: arming away from home
      • sub_id: the ID of the sub-device
      • delay: delay arming time
        • 0: read the time set by the smartphone
        • Others:Delay time, only supports setting 30, 60, 90, 120, 150, 180; the unit is second
    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 0x00
    Command 1 0xC0
    Data length 2 2
    Data 1 Sub-command: 0x00
    1 Result:
    00: success
    Others: failure
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Get the current security information

    Get the current security information.

    The MCU sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC0
    Data length 2 1
    Data 1 Sub-command: 0x01
    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 0x00
    Command 1 0xC0
    Data length 2 1+N
    Data 1 Sub-command: 0x01
    Depend on specific data
    • For example, {operation result} + {mode:xxx, alarm:x, countdown:x}
    • Parameter description
      • Action result:
        • 0: success
        • 1: failure
      • mode: arming mode
        • 0: disarming
        • 1: arming at home
        • 2: arming away from home
      • alarm: alarm status
        • 0: alarm delay, alarming
        • Non-0: no alarm
      • countdown: arming delay status
        • 0: arming delaying
        • Non-0: no alarming delay
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Synchronize security information

    After the security information is set through the app, the module synchronizes the status to the MCU through this command.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC0
    Data length 2 1+N
    Data 1 Sub-command: 0x02
    Depend on specific data
    • Data example: {“mode”:“xxx”, “delay”:xx, “sound”:x}
    • Parameter description
      • mode: arming mode
        • 0: disarming
        • 1: arming at home
        • 2: arming away from home
      • delay: delay arming time
        • 0: no delay
        • Non-0: delay time in seconds
      • sound: whether to play sound
        • 0: play sound
        • Non-0: not play sound
    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 0x00
    Command 1 0xC0
    Data length 2 1
    Data 1 Sub-command: 0x02
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Synchronize device security events

    The security event module synchronizes the status to the MCU through this command.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC0
    Data length 2 1+N
    Data Sub-command 0x03
    Depend on specific data
    • For example, { “status”:x, “data”:“xxx” }
    • Parameter description
      • status: event
        • 0: disarming
        • 1: enter arming
        • 2: there is an ignorable event that triggers sound
        • 3: start countdown
      • data: event information
        • 0: no countdown
          Note: Currently, the countdown time is only returned when the alarm countdown is enabled.
    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 0x00
    Command 1 0xC0
    Data length 2 1
    Data Sub-command 0x03
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Alarm status setting

    In case of status change through the security standard DP32, the MCU shall synchronize the status to the module.

    The MCU sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC1
    Data length 2 2
    Data Sub-command 0x00
    Alarm status 0: normal.
    Non-0: alarming
    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 0x00
    Command 1 0xC1
    Data length 2 2
    Data Sub-command 0x00
    Action result 0: success
    Others: failure
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Cancel alarm status synchronization

    When the alarm is canceled through the app, the module synchronizes the status with this command to the MCU, and the MCU reports false through the security standard DP 2.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC1
    Data length 2 2
    Data 1 Sub-command: 0x01
    1 0: cancel the alarm
    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 0x00
    Command 1 0xC1
    Data length 2 1
    Data 1 Sub-command: 0x01
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Synchronize device alarm information

    When the environmental device DP or non-environmental device DP triggers a device alarm, the module uses this command to synchronize the alarm information to the MCU, and the MCU reports it through the security standard DP 26.

    • Non-environmental device: It is related to arming and disarming, and only alarms when arming.
    • Environmental device: It is irrelevant to arming and disarming. As long as it is triggered, it will alarm.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC1
    Data length 2 1+N
    Data Sub-command 0x02
    Depend on specific data
    • For example, { “type”:x, “sub_id”:“xxx”,“dp_inf”:“xxx”}
    • Parameter description
      • type: the type of the device that triggered the alarm
        • 0: non-environmental device
        • 1: environmental device
      • sub_id: the device ID
      • dpinf: information of the DP that triggers the alarm, in the format of cJSON string
    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 0x00
    Command 1 0xC1
    Data length 2 1
    Data 1 Sub-command: 0x02
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Synchronize device alarm delay status

    When the device is in the alarm delay status, the alarm delay status will be synchronized to the MCU through this command.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC1
    Data length 2 2
    Data 1 Sub-command: 0x03
    1 Alarm delay status
    0: alarm delay is not created
    1: alarm delay is in progress
    2: alarm delay is over
    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 0x00
    Command 1 0xC1
    Data length 2 1
    Data 1 Sub-command: 0x03
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Synchronize the new device alarm information

    This command is to synchronize the new device alarm information. It is enabled with the bit 0 of the A field in the 01 command. After enabled, the security 0xc101 and 0xc102 commands do not need to be processed.

    • There is currently no GP field.
    • Non-environmental device: the device is not related to environmental monitoring.
    • Environmental device: the device is related to environmental monitoring.
    • This command is used for alarm information synchronization. The data content sent by the module is not fixed, and the supported field data will be sent according to the available device functions.

    Currently, fields for multi-zone gateway function are reserved. The field could not be returned.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC1
    Data length 2 1+N
    Data 1 Sub-command: 0x04
    Depend on specific data
    • For example, {
      “type”:x,
      “sub_id”:“xxx”,
      “dp_inf”:“xxx”,
      “gp”:“xxxx”
      }
    • Parameter description
      • type: the type of the device that triggered the alarm
        • 0: non-environmental device
        • 1: environmental device
      • sub_id: the device ID
      • dpinf: information of the DP that triggers the alarm, in the format of cJSON string
      • gp: reserved for multi-zone function to synchronize the zone to which the alarm device belongs.
    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 0x00
    Command 1 0xC1
    Data length 2 1
    Data Sub-command 0x04
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Synchronize the new device alarm status

    This command is to synchronize the new device alarm information. It is enabled with the bit 0 of the A field in the 01 command.

    The module sends the following command:

    Field Length (byte) Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0xC1
    Data length 2 2
    Data 1 Sub-command: 0x05
    Data 0: cancel the alarm
    1: alarm in progress
    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 0x00
    Command 1 0xC1
    Data length 2 1
    Data 1 Sub-command: 0x05
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

    Appendix 1. Weather UTF-8 code table of condition

    Text Hexadecimal Text Hexadecimal
    Sunny E699B4 Heavy rain E5A4A7 E99BA8
    Thunderstorm E99BB7 E69AB4 Sandstorm E6B299 E5B098 E69AB4
    Light snow E5B08F E99BAA Snow E99BAA
    Freezing fog E586BB E99BBE Rainstorm E69AB4 E99BA8
    Isolated showers E5B180 E983A8 E998B5 E99BA8 Dust E6B5AE E5B098
    Thunder and lightning E99BB7 E794B5 Light showers E5B08F E998B5 E99BA8
    Rain E99BA8 Sleet E99BA8 E5A4B9 E99BAA
    Dust devil E5B098 E58DB7 E9A38E Ice pellet E586B0 E7B292
    Strong sandstorm E5BCBA E6B299 E5B098 E69AB4 Sand blowing E689AC E6B299
    Light to moderate rain E5B08F E588B0 E4B8AD E99BA8 Mostly clear E5A4A7 E983A8 E699B4 E69C97
    Fog E99BBE Showers E998B5 E99BA8
    Heavy showers E5BCBA E998B5 E99BA8 Heavy snow E5A4A7 E99BAA
    Extraordinary rainstorm E789B9 E5A4A7 E69AB4 E99BA8 Blizzard E69AB4 E99BAA
    Hail E586B0 E99BB9 Light to moderate snow E5B08F E588B0 E4B8AD E99BAA
    Partly cloudy E5B091 E4BA91 Light snow shower E5B08F E998B5 E99BAA
    Moderate snow E4B8AD E99BAA Overcast E998B4
    Needle ice E586B0 E99288 Downpour E5A4A7 E69AB4 E99BA8
    Thundershower and hail E99BB7 E998B5 E99BA8 E4BCB4 E69C89 E586B0 E99BB9 Freezing rain E586BB E99BA8
    Snow showers E998B5 E99BAA Light rain E5B08F E99BA8
    Haze E99CBE Moderate rain E4B8AD E99BA8
    Cloudy E5A49A E4BA91 Thundershower E99BB7 E998B5 E99BA8
    Moderate to heavy rain E4B8AD E588B0 E5A4A7 E99BA8 Heavy to rainstorm E5A4A7 E588B0 E69AB4 E99BA8

    Appendix 2. Detailed parameter description of weather service

    Weather data parameter Description Mainland China Outside mainland China Forecast Hexadecimal value
    w.temp Atmospheric temperature Yes Yes 7-day forecast in mainland China 77 2e 74 65 6d 70
    w.thigh The highest temperature No Yes 7-day forecast 77 2e 74 68 69 67 68
    w.tlow The lowest temperature No Yes 7-day forecast 77 2e 74 6c 6f 77
    w.humidity Air humidity Yes Yes 7-day forecast 77 2e 68 75 6d 69 64 69 74 79
    w.condition Weather conditions, such as sunny day, rain, and snow Yes Yes 7-day forecast 77 2e 63 6f 6e 64 69 74 69 6f 6e
    w.conditionNum Weather conditions, indicated by digital codes Yes Yes 7-day forecast 77 2e 63 6f 6e 64 69 74 69 6f 6e 4e 75 6d
    w.pressure Atmospheric pressure No Yes 7-day forecast 77 2e 70 72 65 73 73 75 72 65
    w.realFeel Apparent temperature No Yes 7-day forecast 77 2e 72 65 61 6c 46 65 65 6c
    w.uvi Ultraviolet index No Yes 7-day forecast 77 2e 75 76 69
    w.sunRise Sunrise Yes Yes 7-day forecast 77 2e 73 75 6e 52 69 73 65
    w.sunSet Sunset Yes Yes 7-day forecast 77 2e 73 75 6e 53 65 74
    t.unix Greenwich Mean Time (GMT), used with sunrise and sunset time 74 2e 75 6e 69 78
    t.local Local time, used with sunrise and sunset time 74 2e 6c 6f 63 61 6c
    w.windSpeed Wind speed Yes Yes 7-day forecast 77 2e 77 69 6e 64 53 70 65 65 64
    w.windDir Wind direction Yes No 7-day forecast 77 2e 77 69 6e 64 44 69 72 2e 6e
    w.windLevel Wind scale Yes No 7-day forecast 77 2e 77 69 6e 64 4c 65 76 65 6c
    w.aqi Air quality index Yes No Only data of the day 77 2e 61 71 69
    w.tips Notify live weather and professional live conditions with one sentence. Yes No Only data of the day 77 2e 74 69 70 73
    w.rank Detailed AQI status and national ranking Yes No Only data of the day 77 2e 72 61 6e 6b
    w.pm10 PM10 (inhalable particulate matter) Yes No Only data of the day 77 2e 70 6d 31 30
    w.pm25 PM2.5 (fine particulate matter) Yes No Only data of the day 77 2e 70 6d 32 35
    w.o3 Ozone concentration Yes No Only data of the day 77 2e 6f 33
    w.no2 Nitrogen dioxide concentration Yes No Only data of the day 77 2e 6e 6f 32
    w.co Carbon monoxide concentration Yes No Only data of the day 77 2e 63 6f
    w.so2 Sulfur dioxide concentration Yes No Only data of the day 77 2e 73 6f 32
    w.date.n (n means the number of days to be forecasted, 1 ≤ n ≤ 7) The number of days to forecast Yes Yes 77 2e 64 61 74 65 2e 6e

    Update history

    Version Date Description
    1.1.9 September 25, 2020
    • Added a low power consumption type in heartbeat detection.
    • Added display information and alarm status synchronization in the security products.
    • Added ota and channel fields in the sub-device.
    • Added weather service function.
    • Added the command to get the GMT time.
    • Added heartbeat management.
    1.1.8 July 9, 2020
    • Added infrared functions.
    • Added security capability selection field in product information
    • Heartbeat function description.
    1.1.7 April 23, 2020
    • Added the AP and SmartConfig coexistence pairing status.
    • Unified some fields in the security sensor extension protocol.
    1.1.6 April 9, 2020
    • Added the security gateway function protocol.
    1.1.5 February 20, 2020
    • In the basic protocol, added 3.37, 3.38, and 3.39 commands.
    • In the dual-link extension protocol, added 4.2.2, 4.2.3, 4.2.4, 4.2.5, and 4.2.6 commands.
    • In the 3.19 command, added the optional key field.
    • Added 04 status in 3.24.
    • Added 3.38 and 3.39 commands.
    • Deleted the set heartbeat time in the heartbeat reply frame.
    1.1.4 September 12, 2019
    • Added p field to product information.
    • Heartbeat interval changed from 60 seconds to 180 seconds.
    1.1.3 September 2, 2019
    • Added the tp field to product information.
    • Added the dual-link extention protocol and sub-device synchronization.
    • Updated the online/offline status of sub-devices.
    • Add the cancel heartbeat mechanism flag in the cap field.
    • Added the command to get mac.
    • Added record type real-time reporting interface.
    • Change the minimum heartbeat interval from 30 seconds to 60 seconds.
    1.1.2 July 13, 2019
    • Added serial port pairing commands (integrated).
    • Added serial port transparent transmission pairing commands (split).
    • Added the command to query DP status.
    • Added the sigmesh command to clear sub-device information.
    • Added the sigmesh command to get local ID.
    • Added the sigmesh command to update the group address.
    • The sub-package of the serial port update is compatible with 128 bytes.
    1.1.1 May 29, 2019
    • Added the group control command with sub_id information.
    • Added the command to get dev_key.
    • Described restoring the factory defaults locally.
    • Added the group control command with sub_id flag in product information.
    • Added devkey when the gateway is SIG mesh gateway and a sub-device is being deleted.
    1.1.0 May 20, 2019
    • Added bit4 of cap to check whether there is MCU OTA function.
    • Added the remote service command.
    • Added the frame to get Wi-Fi status.
    • Added the frame to locally delete a sub-device.
    • Added the frame to query sub-device list.
    • Added the frame to restore factory defaults locally.
    • Added the command to report removal status.
    • Added the command to get source node through SIG mesh.
    1.0.9 April 13, 2019
    • Added bit3 of cap to identify internal SIG mesh.
    • Added network information pull frame.
    • Added the frame to apply for a network node.
    • Added the frame to add a SIG mesh sub device.
    • Added the frame to locally enable/disable the adding of a sub-device.
    • Added the frame to get the module memory.
    1.0.8 March 19, 2019
    • Modify the response after adding sub-devices.
    1.0.7 January 18, 2019
    • Added the group control frame.
    • Changed 3.19 command of returning the batch adding device result to 0x13.
    • Added the group control command 0x014.
    • Added the production test command 0x15.
    1.0.6 January 11, 2019
    • Added the reading of the time (GMT and local time).
    • Added the batch adding of sub-devices.
    • Added the return result of batch adding of sub-devices.
    • sub_id 0000 represents the gateway itself.
    • The heartbeat interval is at least 30 seconds.
    1.0.5 November 7, 2018
    • Added return result set of group operation.
    1.0.4 November 7, 2018
    • Added the function to add sub-devices to local groups, and remove sub-devices from groups.
    • Modified the command to query product information and added the function to return the device capability (whether it supports local groups and local scenarios).
    1.0.3 October 30, 2018
    • Deleted the PID information in the product information.
    • Limit the port in 3.2 to A-D.
    1.0.2 October 27, 2018
    • Added the command to query product information.
    • Added the command to query MCU working mode.
    • Added the command to report device network status.
    • Added the command to reset Wi-Fi.
    • Added the command to reset Wi-Fi and select configuration mode.
    • Adjusted each command code.
    1.0.1 October 25, 2018
    • Modified the 3.3 sub-device adding protocol and added the heartbeat time setting.
    1.0.0 October 18, 2018
    • The first release.