Door Locks
Last Updated on : 2023-04-24 07:09:52download
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.
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.
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
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.
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedbackMarketing Cooperation
Business Cooperation
Customer Service
Media Inquiry
© 2024 Tuya Inc.