Zigbee Connection Standard for Smart Dimmer Switch

The Zigbee smart dimmer switch (no neutral wire required) is a controlled device that uses a thyristor to realize switching and dimming actions. It can accept switch and dimming commands to act on dimming lights.

Use the Dimmer Light device in the Zigbee 3.0 standard to achieve this feature.

Terms and definitions

Term	Description
Zigbee SDK	The Zigbee SDK is developed based on the Silicon Labs Zigbee 3.0 protocol stack and tailored, optimized, and encapsulated to create a Tuya Zigbee module SDK.
Attribute	A data value that reflects the physical quantity or status.
Cluster	Each cluster contains one or more attributes.
Endpoint	The entry point for the application layer of the protocol stack. Each endpoint can be regarded as the location where the application object exists. It is defined as a cluster that is used to implement a device description.
Device ID	The serial number that is defined for each Zigbee device.
TYZS13 Zigbee Module	A Zigbee module suitable for developing smart switches (no neutral wire required).
ELV (extra-low voltage) device	A battery-powered device, which is called a sleep end device in the Zigbee protocol.
Electrical device	A mains electricity-powered device that is called an end device in the Zigbee protocol.
Product ID (PID)	It represents product ID. Each product created in the Tuya IoT Console will generate a unique product identifier. This ID is associated with specific data points of the product, app control panel, shipping information, and other information related to the product.
SoC	SoC (System On Chip): The hardware does not have an MCU, and the control program is written into the cloud module.
SDK	A software development kit (SDK) contains the documents, examples, and tools required to develop software. In order to encourage developers to use their system or language, many SDKs are provided for free, such as Tuya.
Firmware	The programs that are written to the erasable programmable read-only memory (EROM) or electrically erasable programmable read-only memory (EEPROM). Firmware is used to drive programs that are embedded in devices, such as CD-ROM and CD-R. The firmware enables operating systems to drive devices based on standard device drivers. Firmware is the software that completes the most basic bottom-layer tasks of a system.
OTA	It means firmware update over the air. Tuya supports OTA. Firmware updates can be implemented through wireless or wired connections. Firmware over-the-air (FOTA) is a wireless method to update the firmware.

Functional description of Zigbee devices

Zigbee protocol version

name	ID
Profile ID	0x0104
Device ID	0x0101

Endpoint

Endpoint	Description
1	The first gang.

Supported clusters

Dimmer light (0x0101)
Input cluster (server)	Output cluster (client)
Basic (0x0000)	OTA (0x0019)
Identify (0x0003)	-
Group cluster (0x0004)	-
Scene cluster (0x0005)	-
On/Off cluster (0x0006)	-
Level control cluster (0x0008)	-
Level control max min (0xFC00)	-
Level control bulb type (0xFC02)	-
Level control scr state (0xFC03)	-
Level control current percentage (0xFC04)	-
Level control min percentage (0xFC05)	-

Supported attributes and commands

Basic cluster

Attribute:

ID	Name	Data Type	Range	Defualt value
0x0000	ZCLVersion	uint8 -0x20	0x00 - 0xff	0x01
0x0001	Application version	uint8 -0x20	0x00 - 0xff	For example, 0b 01 00 0001 = 1.0.1, where 0x41 is 1.0.1.
0x0002	StackVersion	uint8 -0x20	0x00–0xFF	2
0x0003	Hardware version	uint8 -0x20	0x00–0xFF	0x01
0x0004	Manufacturer name	string -0x42	0-32 bytes	XXX…XXX (16 bytes in length, including an 8-byte prefix and an 8-byte PID). No. 0-7 bytes: TZ3000 and No. 8-16 bytes: PID (created on the Tuya IoT Platform). The PID for 1-gang dimmer switch: 9v86hx9o.
0x0005	Module identifier	string -0x42	0-32 bytes	TS1101. This field is used by the gateway to quickly identify the device type and improve the experience.
0x0007	PowerSource	enum8-0x30	0x00–0xFF	0x01
0xFFFD	Cluster revision	uint16 -0x21	0x0000 - 0xffff	0x0001

Commands:

ID	name	Direction	Description
0x00	Reset to factory defaults	C->S	-

Identify cluster

Attribute:

ID	Name	Data type	Range	Defualt value
0x0000	IdentifyTime	uint16 -0x21	0x0000 - 0xffff	0x0000
0xFFFD	Cluster revision	int16 -0x29	0x0000 - 0xffff	0x0001

Commands:

ID	name	Direction	Description
0x00	Identify	C->S	-
0x01	Identify query	C->S	-

On/Off cluster

Attribute:

ID	name	Data type	Range	Defualt value
0x0000	onOff	bool-0x10	0x00 - 0x01	0x00

Commands:

ID	name	Direction	Description
0x00	Off	C->S	-
0x01	On	C->S	-
0x02	Toggle	C->S	-

Level control cluster

Attribute:

ID	Name	Data type	Range	Defualt value
0x0000	Current level	uint8 -0x20	0x01–0xFE	0xff

Commands:

ID	name	Direction	Description
0x00	Move to level	C->S	-
0x02	Step	C->S	-
0x04	Move to level（with on/off）	C->S	-

Private cluster

Attribute:

ID	Name	Data type	Range	Defualt value
0xFC00	Level control max min	uint16 -0x21	0x0000 - 0xffff	0x01ff
0xFC02	Level control bulb type	uint8 -0x20	0x00–0xFF	0x00
0xFC03	Level control scr state	uint8 -0x20	0x00–0xFF	0x01
0xFC04	Level control current percentage	uint8 -0x20	0x00–0xFF	0x01
0xFC05	Level control min percentage	uint8 -0x20	0x00–0xFF	0x01

OTA update cluster

Attribute:

ID	name	Data type	Range	Defualt value
0x0000	Update server ID	EUI64-0xF0	-	0xffffffffffffffff
0x0001	FileOffset	uint32-0x23	-	0x00000000
0x0002	CurrentFileVersion	uint32-0x23	-	0x21050002
0x0006	ImageUpgradeStatus	enum8-0x30	-	0x00
0x0007	Manufacturer ID	uint16 -0x21	-	0x1002
0x0008	Image type ID	uint16 -0x21	-	0x1602
0x0009	Min block request period	uint16 -0x21	-	0x0000
0xfffd	Cluster revision	uint16 -0x21	-	0x0001

Zigbee device management requirements

Networking

• Beacon request channels are scanned at an interval of greater than 150 ms. Important channels to be scanned in priority.

• The timeout value for each scanning task is 30s.

• If data reporting is required after Zigbee devices are networked, data is reported at a random interval of 5s, 10s, or more seconds.

Device restart after power off

• The device supports the power-off memory function. When power-off and power-on again, it is necessary to read the switch status, thyristor status (single and dual control), and brightness value before power-off.

Link maintenance

• The device version is continuously reported at a random interval of 150–180 seconds.

Data reporting

• If data retransmission is enabled for the application support sublayer (APS), we recommend that you set Disable Default Response to 1 to avoid excessive acknowledgments (ACKs).

• The Transaction Sequence Number attribute cannot be modified during data transmission.

• The retransmission interval must be greater than 250 ms. We recommend that you set the retransmission duration to less than three seconds.

• To process broadcast, multicast, and scene DPs, we recommend that you set the latency of data reporting to a random value from one minute to two minutes. If a unicast DP is received during the latency, the status data is immediately reported.

Special instructions

The Zigbee smart dimmer switch (no neutral wire required) uses a thyristor to realize switching and dimming actions. Use the above private attributes to store and communicate related information.

• 0xFC00 is used to store the current maximum and minimum brightness values.
• 0xFC02 is used to distinguish the bulb type.
• 0xFC03 is used to store the status of the thyristor.
• 0xFC04 is used to store the current dimming percentage.
• 0xFC05 is used to store the minimum brightness percentage.

The minimum brightness value is used to adapt to different types of LED lights with different wattages, and the thyristor status is used for dual control functions.

Development method

1. Developed based on Tuya Zigbee SDK:

   • You only need to modify the module model and hardware configuration of the demo sample to complete the above functions, including groups and scenes.
   • Tuya provides complete flashing, authorization, production testing process, software and hardware tools
     • Zigbee Chip SDK
     • Production Test Tools

2. Self-developed with non-Tuya Zigbee module:

   • Need to fully implement the above technical details
   • Complete device authorization

3. Authorize by using Tuya’s complete authorization tool

   • Through the module and the host computer serial communication authorization: See Production Test of Zigbee SDK.

   • Serial communication sample code: See Authorize by Using Tuya Authorization SDK.

4. Self-developed with Tuya Zigbee module:

   • Only need to implement firmware function details.
   • Purchase the authorized Tuya Zigbee module.