English
English
简体中文
Contact Us
Register
Log In
layoutIndex

Door Locks

Last Updated on : 2022-06-06 17:05:15download

How it works

A smart lock is built with a bunch of features. However, feature definition can vary depending on manufacturers, which cannot be addressed with the ZCL standard clusters. In this case, the manufacturer-specific clusters can be used to define features for their specific needs.

The Zigbee module acts as a mediator that connects the MCU and the Zigbee gateway. It converts the data received from the gateway into a format defined in Tuya-specific serial communication protocol and sends the converted data to the MCU through the serial port. In the other direction, the Zigbee module converts the data received from the MCU into the format defined in the Zigbee Cluster Library (ZCL) and sends the converted data to the gateway that exchanges data with the cloud. In a nutshell, you can use the Zigbee network to connect the MCU to cloud services and thus make your product IoT-enabled.

Door Locks

Zigbee specification

Zigbee basics

Parameter Value
Profile ID 0x0104
Device ID 0x000a
Endpoint Description
1 The endpoint used for application data exchange.

Supported clusters, attributes, and commands

SMART_PLUG (0x0051) Output clusters (client)
Basic (0x0000) OTA upgrade (0x0019)
Time (0x000A) /
Private cluster (0XEF00) /

Basic cluster

Attributes:

ID Name Data type (ID) Range Default
0x0000 ZCLVersion uint8 (0x20) 0x00 to 0xff 0x03
0x0001 ApplicationVersion uint8 (0x20) 0x00 to 0xff For example, 0b 01 00 0001 indicates 1.0.1, that is, 0x41 represents version 1.0.1. This attribute is used for OTA updates. When an OTA update is initiated, the gateway reads the version number of the update and pushes it to the Zigbee device. After the Zigbee device is restarted after the update, the gateway reads the current version to check for the update result. The firmware can only be updated to a higher version.
0x0002 StackVersion uint8 (0x20) 0x00 to 0xff 0x02
0x0003 HWVersion uint8 (0x20) 0x00 to 0xff 0x01
0x0004 ManufacturerName string (0x42) 0 to 32 bytes The value of this attribute is 16 bytes in length, consisting of 8-byte prefix and 8-byte PID. 0 to 7 bytes: _TZF320_.
8 to 16 bytes: The PID, the unique identifier of the Zigbee product you create on the Tuya IoT Development Platform.
0x0005 ModelIdentifier string (0x42) 0 to 32 bytes TY0A02, used for the gateway to identify the device type.
0x0007 PowerSource enum8 (0x30) 0x00 to 0xff It depends on your product.
0xfffd ClusterRevision uint16 (0x21) 0x0000 to 0xffff 0x0001

Commands

ID Name Direction Description
0x00 Reset to factory default Client to server C: Stands for client.
S: Stands for server.

Private cluster

To achieve the communication between the Zigbee module and the MCU, use the private cluster to define a class of private cluster commands to transmit data.

In the application support sublayer (APS):

  • Destination Endpoint: 0x01.
  • Cluster ID: 0xEF00.
  • Profile ID: 0x0104.
  • Source Endpoint: 0x01.

In the ZCL layer, the private command ID is used to identify commands. Define private frame in the ZCL payload in the format sequence number (2 bytes) + user data.

Door Locks

The following table lists the ZCL header format.

Field Length (bit) Value Description
Frame type 2 01 Command is specific to a cluster.
Manufacturer specific 1 0 The manufacturer code field is not included in the ZCL frame.
Direction 1 0/1 0: Gateway to Zigbee device.
1: Zigbee device to gateway.
Disable default response 1 0/1 The value defaults to 0. It defaults to 1. It is set to 0 only when the Zigbee device proactively reports data to the gateway. The gateway returns a response to indicate successful reporting.
Reserved 3 000 Reserved

Private command ID

Command enumerations Value Description
TY_DATA_ REQUEST 0x00 The gateway sends data to the Zigbee module.
TY_DATA_RESPONE 0x01 The MCU responds to data requests.
TY_DATA_REPORT 0x02 The MCU proactively reports status.
TUYA_MCU_VERSION_REQ 0x10 The gateway sends a query to the Zigbee module for the MCU firmware version.
TUYA_MCU_VERSION_RSP 0x11 The Zigbee module returns the MCU firmware version, or the MCU proactively reports its firmware version.
TUYA_MCU_OTA_NOTIFY 0x12 The gateway notifies the Zigbee module of MCU firmware updates.
TUYA_OTA_BLOCK_DATA_REQ 0x13 The Zigbee module requests to download the MCU firmware update.
TUYA_OTA_BLOCK_DATA_RSP 0x14 The gateway returns the update package to the Zigbee module.
TUYA_MCU_OTA_RESULT 0x15 The Zigbee module returns the result of MCU firmware updates to the gateway.
TUYA_DYNA_PWD_KEY 0x20 Dynamic password key. (Two-way messaging)
TUYA_REPORT_LOG 0x23 Report status of time-dependent DPs. (Two-way messaging).
TUYA_MCU_SYNC_TIME 0x24 Time synchronization. (Two-way messaging)
TUYA_INTERNET STATUS 0x25 Network status of the gateway.
TUYA_ZCL_INTERNET_STAT_ACK 0x26 The MCU confirms receipt of network status of the gateway.
TUYA_ZCL_SESSIONE_KEY_REQ 0x40 The Zigbee module requests sessionKey from the gateway.
TUYA_ZCL_SESSIONE_KEY_RSP 0x41 The gateway sends the ciphertext HMA_RA+AES_RB to the Zigbee module.
TUYA_ZCL_SESSIONE_KEY_ACK 0x42 The gateway sends HMAC_RB, and the Zigbee module returns a response.
TUYA_ZCL_DYNA_PWD_REQ 0x43 The Zigbee module requests the dynamic password key from the gateway.

Frame of command ID

Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks
Door Locks

DP data format
Data segment Length (byte) Description
DPID 1 The ID of a DP.
type It indicates the specific data type of a DP defined on the Tuya IoT Development Platform, which is represented by the Value.
Type Value Length (byte) Description
Raw 0x00 N Represents a DP of raw data type. The data is passed through the module to the cloud.
Boolean 0x01 1 The valid values are 0x00 and 0x01.
Value 0x02 4 Represents a DP of integer data type, in big-endian format.
String 0x03 N Represents a DP of string data type.
Enum 0x04 1 Represents a DP of enum data type, ranging from 0 to 255.
Bitmap 0x05 1/2/4 Data greater than one byte is transmitted in big-endian format.
len 2 The length is the number of bytes of a value.
Value 1/2/4/N Represented in hexadecimal format. Data greater than one byte is transmitted in big-endian format.

Over the Air Upgrade

Attributes:

ID Name Data type (ID) Range Default
0x0000 UpgradeServerID EUI64 (0xF0) / 0xffffffffffffffff
0x0001 FileOffset uint32 (0x23) / 0x00000000
0x0002 CurrentFileVersion uint32 (0x23) / 0x00000000
0x0006 ImageUpgradeStatus enum8 (0x30) / 0x00
0x0007 Manufacturer ID uint16 (0x21) / 0x1002
0x0008 Image Type ID uint16 (0x21) / 0x1602
0x0009 MinimumBlockPeriod uint16 (0x21) / 0x0000
0xfffd ClusterRevision int16 (0x29) 0x0000 to 0xffff 0x0001

Commands

ID Name Direction
0x00 Image Notify Server to client
0x01 Query Next Image Request Client to server
0x03 Image Block Request Client to server
0x06 Upgrade End Request Client to server

Serial communication protocol

A frame for serial communication comprises header (front), version (ver), command (cmd), data length (length), data (data), and checksum (check). The frame is formatted as illustrated in the following table:

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

Frame format description

Field Description
Header (front) A 2-byte leader character, fixed to 0x55aa.
Version (ver) The version of the serial protocol, used for protocol updates or extensions. The current version is 0x03.
Sequence number (seq) Valid values range from 1 to 0xfff0.
Command (cmd) See the following table for specific serial communication commands.
Data length (length) The payload length.
Data (data) The payload data.
Checksum (check) Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Commands

Command ID Description Direction
0x00 The Zigbee module wakes up the MCU or vice versa. Zigbee module to MCU or vice versa
The MCU responds to wake-up command or vice versa MCU to Zigbee module or vice versa
0x01 Query product information. Zigbee module to MCU
Return product information. MCU to Zigbee module
0x02 Query product information. Zigbee module to MCU
The Zigbee module responds to a status query. Zigbee module to MCU
0x03 Reset a Zigbee device. MCU to Zigbee module
The Zigbee module responds to reset command. Zigbee module to MCU
0x04 Send a command. Zigbee module to MCU
Respond to a command. MCU to Zigbee module
0x05 Report data. Zigbee module to MCU
Respond to data reporting. Zigbee module to MCU
0x06 The Zigbee module notifies the MCU of events. Zigbee module to MCU
0x07 Request dynamic password. MCU to Zigbee module
Response to a dynamic password request. Zigbee module to MCU
0x08 The MCU reports an offline password. Zigbee module to MCU
Respond to offline password reporting. MCU to Zigbee module
0x09 Test Zigbee module functionality. MCU to Zigbee module
Test responses Zigbee module to MCU
0x0a The Zigbee module requests the MCU version. Zigbee module to MCU
MCU responds. MCU to Zigbee module
0x0b Notify of an available OTA update. Zigbee module to MCU
MCU responds. MCU to Zigbee module
0x0c Request downloading the update file over OTA. MCU to Zigbee module
Zigbee module responds. Zigbee module to MCU
0x0d Return the update result. MCU to Zigbee module
Zigbee module responds. Zigbee module to MCU
0x23 Request the format for reporting time-dependent status with timestamp. MCU to Zigbee module
Respond to the format request. Zigbee module to MCU
0x24 Request time sync. MCU to Zigbee module
Respond to time sync request. Zigbee module to MCU

For more information, see Serial Communication Protocol.