Zigbee Connectivity Specifications
Last Updated on : 2024-11-20 08:51:43download
To connect a Zigbee device to the Tuya Developer Platform and mobile apps, your development must follow a set of end-to-end specifications. This topic describes these specifications and provides examples for better understanding.
Terms
The following core concepts guide you through the understanding of the specifications.
| Terms | Description |
|---|---|
| PID | Refers to product ID (PID). A product is an abstract representation of a collection of physical devices that have the same configurations and properties. Each product created on the Tuya Developer Platform is assigned a unique PID. |
| Data point (DP) | The data model of a product, which denotes product functions. |
| Firmware key | The identifier of firmware associated with a PID. |
| License | The license is also called production certificate, which serves as the authentication information for device connection to the Tuya Developer Platform. |
| Pairing | The process where a device is added to a mobile app to interact with the Tuya Developer Platform through a gateway. |
| Endpoint | An endpoint is the contact point through which clients can obtain access to a service provided by a server. It is a collection of clusters, each of which is distinct from the others, yet the items inside each cluster are broadly similar. |
| OEM firmware | Different PIDs that belong to one product category can share the same OEM firmware. |
| Mode ID | A convention used to allow a Zigbee gateway to quickly identify the type of Zigbee device that has joined the network. |
| Attribute | An attribute is a variable or a set of variables that represent the functional state of the cluster. |
| Cluster | A cluster is a related collection of commands and attributes, which together define an interface to specific functionality. |
| Device ID | An identifier assigned to each Zigbee device. |
| Battery-powered devices | The Zigbee specifications define the battery-powered device as the end device. They interact with their parent node to receive or transmit data and are intended to sleep periodically. An end device can be a source or destination for data packets but cannot route packets. |
| Mains-powered devices | The Zigbee specifications define the mains-powered device as the router. They can participate in routing packets. |
Network architecture
As shown in the diagram above, Zigbee devices can be connected to the cloud through a Zigbee gateway and then be controlled with a mobile app. Acting as a mediator, the cloud enables connectivity and interoperability across protocols such as Bluetooth Low Energy (LE) mesh and Zigbee.
For example, users can set up the linkage between the Zigbee switch 1 and the Bluetooth LE mesh light 1 by using the mobile app.
- After the Zigbee switch 1 reports ON state, the Bluetooth LE mesh light 1 will come on.
- After the Zigbee switch 1 reports OFF state, the Bluetooth LE mesh light 1 will come off.
PID
The unique identifier of a product created on the Tuya Developer Platform. The Tuya Cloud identifies products by PID and then sends data to a specified mobile app for display. The PID is the vital information of a product, which is typically written to the firmware code.
The PID of a Zigbee device must be stored in the manufacturer name attribute in the basic cluster.
Data point (DP)
The data model of a product, which denotes product functions and serves for the communication between a device and the cloud. Tuya provides two types of product functions.
- Standard Functions: The most common functions of a product category, which can be selected as needed.
- Custom Functions: If the standard functions cannot address your needs, you can add and edit a custom function to implement a required function.
DP ID is a unique identifier assigned to each function (a DP). The bidirectional communication between Zigbee devices and the cloud is based on DP data.
Firmware key
The identification information of firmware, which is generated after you Add Custom Firmware on the Tuya Developer Platform. The firmware key is associated with the PID and contains information including firmware identifier, firmware version, chipset platform, firmware type, update channel, and more.
Generally, you do not need to take care of the firmware key. But when multiple PIDs share the same firmware, you must specify the firmware key in your code and enable OEM settings.
| Fields | Description |
|---|---|
| Firmware identifier | The written firmware name when you use the script to compile code. |
| Firmware type | It depends on the product type. Select Bluetooth Firmware if you use the Bluetooth protocol. |
| Chipset platform | It is automatically generated based on your selected module. |
| Firmware version | The firmware version is written when you use the script to compile code. This information is required when you upload firmware for production on the Tuya Developer Platform. |
You must use the information of the firmware key specified on the Tuya Developer Platform for code compilation, including firmware identifier, firmware type, chipset platform, and firmware version. Otherwise, the flashing and authorization using Tuya’s host will fail.
License
The license serves as the authentication information for device connection to the Tuya Developer Platform, which must be written to the chip in production.
In the pairing process, when a device attempts to connect to the cloud over a wireless router for registration, it sends the license to the cloud for authentication.
Tuya provides three options for license delivery based on flashing requirements.
| License name | Description |
|---|---|
| Production certificate | Production certificate is the delivery mode for the combined firmware flashing and authorization solution. Tuya flashes the encrypted license to the chip using its proprietary host. The information of the firmware key will be verified to avoid writing any incorrect firmware information. This solution is recommended, but note that it supports Tuya standard chips only. |
| Production certificate - authorization only | Production certificate - authorization only is the delivery mode for the independent firmware flashing and authorization solution. Tuya flashes the encrypted license to the chip using its proprietary host. The information of the firmware key will not be verified. This solution applies to authorizing non-Tuya standard chips. |
| License list | License list provides the plaintext of the license, which is not recommended. You must develop a host to flash the license to your chip. |
OEM firmware
Generally, when a PID is written to firmware code, the compiled firmware only applies to this PID.
If several PIDs have identical functions, they can share the same firmware. Therefore, we can use the OEM logic without compilation per each PID.
For the OEM firmware, only the firmware key is written without PID. The compiled firmware can apply to different PIDs that belong to one product category.
Mode ID
The mode ID is a convention used to allow a Zigbee gateway to quickly identify the type of Zigbee device that has joined the network.
It is stored in the mode ID attribute in the basic cluster. For example, if mode ID is TS0505B, it represents a white and colored light.
Switches
| Device name | Mode ID |
|---|---|
| 1-gang switch (with neutral) | TS0001 |
| 2-gang switch (with neutral) | TS0002 |
| 3-gang switch (with neutral) | TS0003 |
| 4-gang switch (with neutral) | TS0004 |
| 5-gang switch (with neutral) | TS0005 |
| 6-gang switch (with neutral) | TS0006 |
| 7-gang switch (with neutral) | TS0007 |
| 1-gang switch (no neutral) | TS0011 |
| 2-gang switch (no neutral) | TS0012 |
| 3-gang switch (no neutral) | TS0013 |
| 4-gang switch (no neutral) | TS0014 |
| 5-gang switch (no neutral) | TS0015 |
| 6-gang switch (no neutral) | TS0016 |
| 7-gang switch (no neutral) | TS0017 |
| 1-gang scene switch | TS0021 |
| 2-gang scene switch | TS0022 |
| 3-gang scene switch | TS0023 |
| 4-gang scene switch | TS0024 |
| 5-gang scene switch | TS0025 |
| 6-gang scene switch | TS0026 |
| 7-gang scene switch | TS0027 |
| 8-gang scene switch | TS0028 |
| 9-gang scene switch | TS0029 |
| 9-gang scene remote control | TS002A |
| 1-gang wireless switch (battery-powered) | TS0041 |
| 1-gang wireless scene switch (battery-powered) | TS0041A |
| 2-gang wireless switch (battery-powered) | TS0042 |
| 2-gang wireless scene switch (battery-powered) | TS0042A |
| 3-gang wireless switch (battery-powered) | TS0043 |
| 3-gang wireless scene switch (battery-powered) | TS0043A |
| 4-gang wireless switch (battery-powered) | TS0044 |
| 4-gang wireless scene switch (battery-powered) | TS0044A |
| 5-gang wireless switch (battery-powered) | TS0045 |
| 5-gang wireless scene switch (battery-powered) | TS0045A |
| 6-gang wireless switch (battery-powered) | TS0046 |
| 7-gang wireless switch (battery-powered) | TS0047 |
| 8-gang wireless switch (battery-powered) | TS0048 |
| Proprietary smart switch module | TS000F |
| Proprietary 3-gang wireless switch (with mode switch) | TS004F |
| Proprietary 1- to 6-gang scene switch | TS002F |
Sockets
| Device name | Mode ID |
|---|---|
| 1-gang 10A 5-pin in-wall socket (no energy metering) | TS0101 |
| 1-gang 10A energy metering socket (with switch module) | TS0102 |
| 1-gang 16A socket (no energy metering) | TS0103 |
| 1-gang 16A energy metering socket (with switch module) | TS0104 |
| 1-gang 10A energy metering socket (no switch module and button) | TS0105 |
| 1-gang 16A energy metering socket (no switch module and button) | TS0106 |
| 2-gang 10A 5-pin in-wall energy metering socket with USB charger (no button) | TS0107 |
| 2-gang 10A energy metering socket (with switch module) | TS0108 |
| 2-gang 16A socket with switch module (no energy metering) | TS0109 |
| 2-gang 16A energy metering socket (with switch module) | TS010A |
| 1-gang OEM socket (no energy metering) | TS0111 |
| 2-gang OEM socket (no energy metering) | TS0112 |
| 3-gang OEM socket (no energy metering) | TS0113 |
| 4-gang OEM socket (no energy metering) | TS0114 |
| 5-gang OEM socket (no energy metering) | TS0115 |
| 1-gang OEM energy metering socket | TS0121 |
| 2-gang 10A socket with switch module (no energy metering) | TS0122 |
| 1- to 8-gang socket | TS011F |
Sensors
| Device name | Mode ID |
|---|---|
| Temperature and humidity sensor | TS0201 |
| PIR sensor | TS0202 |
| Contact sensor | TS0203 |
| Gas detector | TS0204 |
| Smoke detector | TS0205 |
| Emergency call button (low energy) | TS0206 |
| Water detector | TS0207 |
| Sound alarm | TS0208 |
| Photoelectric alarm | TS0209 |
| Vibration sensor | TS0210 |
| SOS alarm button | TS0211 |
| Carbon monoxide detector | TS0212 |
| Emergency call button (mains-powered) | TS0213 |
| Night light | TS0214 |
| Security remote control | TS0215 |
| Proprietary SOS button | TS0215A |
| SOS remote control (mains-powered) | TS0215B |
| Siren alarm | TS0216 |
| Air quality sensor | TS0217 |
| Proprietary siren alarm | TS0219 |
| PM2.5 sensor | TS0221 |
| Luminance sensor | TS0222 |
Curtain
| Device name | Mode ID |
|---|---|
| Curtain motor | TS0301 |
| 1- to N-gang curtain switch (new version) | TS130F |
Controller
| Device name | Mode ID |
|---|---|
| 6-gang graphical scene panel | TS0303 |
| 6-gang scene switch | TS0304 |
| 9-gang scene remote control | TS002A |
| Air conditioner | TS0305 |
| Ventilation system | TS0306 |
| Underfloor heating | TS0307 |
| Thermostat | TS0308 |
| Air conditioning system | TS0309 |
| Fresh air ventilator | TS030A |
| Underfloor heating controller | TS030B |
Door locks
| Device name | Mode ID |
|---|---|
| Fingerprint lock | TS0401 |
| Residential lock | TY0A01 |
| Business lock | TY0A02 |
| Hotel lock | TY0A03 |
Lights
| Device name | Mode ID |
|---|---|
| Dimmable light | TS0501B |
| Warm to cool white light | TS0502B |
| Colored light | TS0503B |
| Cool white and colored light | TS0504B |
| White and colored light | TS0505B |
UART interfacing
| Device name | Mode ID |
|---|---|
| Mains-powered devices | TS0601 |
| Battery-powered devices | TS0601 |
| Mains-powered scenes | TS0602 |
| Battery-powered scenes | TS0602 |
| Three-level UART interfacing | TS0603 |
| Offline voice control | TS0604 |
Switch and scene combo devices
| Device name | Mode ID |
|---|---|
| 1 switch + 3 scenes | TS0701 |
| 2 switches + 2 scenes | TS0702 |
| 3 switches + 1 scene | TS0703 |
| 1 to 6 switches + 1 to 6 scenes | TS0716 |
| 1 to 6 configurable scene switch | TS0726 |
Special switches
| Device name | Mode ID |
|---|---|
| Hotel key card switch | TS0801 |
| Smart gas valve | TS0802 |
Remote controls
| Device name | Mode ID |
|---|---|
| Proprietary remote control dimmer | TS1001 |
Switch and scene combo devices
| Device name | Mode ID |
|---|---|
| Proprietary white dimmer switch | TS1101 |
| Proprietary warm to cool white dimmer switch | TS1102 |
| Proprietary versatile dimmer switch | TS110E |
| Proprietary versatile light dimmer | TS110D |
Universal remote controls
| Device name | Mode ID |
|---|---|
| IR remote control with button | TS1200 |
| IR remote control without button | TS1201 |
Firmware version
The firmware version number is stored in the application version attribute in the basic cluster. The data type is 8-bit unsigned integer.
Assume that 0100 0011 represents version number 1.0.3. As shown in the following figure, the value of the application version is 67, which is 0100 0011 in binary, hence denoting version number 1.0.3.
Heartbeat mechanism
-
Gateway heartbeat: The gateway dynamically adjusts the interval of heartbeat packets sent to each Zigbee device. It reads the application version attribute of a Zigbee device to determine if it is online.
-
Zigbee device heartbeat: The Zigbee device sends a heartbeat packet to the gateway at a random interval between 150 to 180 seconds. The heartbeat payload is the application version attribute. If your gateway supports heartbeat checking, you do not need to implement this feature on the Zigbee device.
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback
