Zigbee Connectivity Specifications

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

To connect a Zigbee device to the Tuya IoT Development 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 IoT Development 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 IoT Development Platform.
Pairing The process where a device is added to a mobile app to interact with the Tuya IoT Development 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

Zigbee Connectivity Specifications

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 IoT Development Platform. The Tuya IoT 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.

Zigbee Connectivity Specifications

The PID of a Zigbee device must be stored in the manufacturer name attribute in the basic cluster.

Zigbee Connectivity Specifications

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.

Zigbee Connectivity Specifications

Firmware key

The identification information of firmware, which is generated after you Add Custom Firmware on the Tuya IoT Development 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.

Zigbee Connectivity Specifications

Zigbee Connectivity Specifications

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 IoT Development Platform.

You must use the information of the firmware key specified on the Tuya IoT Development 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 IoT Development 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.

Zigbee Connectivity Specifications

Zigbee Connectivity Specifications

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.

Zigbee Connectivity Specifications

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.