Tuya Zigbee with ZHA and Zigbee2MQTT: why Zigbee 3.0 devices behave differently

Pairing is not the same as complete support

A device can advertise “Zigbee 3.0,” join the network successfully, and still expose only part of its functions in Home Assistant. This is common with white-label Tuya devices. The radio and network layers may work correctly while the coordinator software lacks a definition for the exact model, manufacturer identifier, endpoint layout, or vendor-specific command.

The slogan “Tuya Zigbee is not real Zigbee 3.0” is therefore inaccurate. Tuya documents Zigbee 3.0 device profiles, while many products also use vendor-specific clusters and data points. Both can exist in one device.

Zigbee 3.0 is not a universal driver

Zigbee defines networking and standardized clusters for common functions. A basic switch can expose the standard On/Off cluster, while additional modes use vendor extensions. A gateway can therefore pair a device without understanding every feature.

Certification likewise does not promise that every controller will map every product-specific function. The Connectivity Standards Alliance certifies products for conformance, while ZHA and Zigbee2MQTT still need software support for the exact hardware and firmware variant.

In this article, ZHA means Home Assistant's Zigbee integration, not the older “Zigbee Home Automation profile” term.

Tuya clusters and data points

Many Tuya devices use manufacturer-specific cluster 0xEF00, called manuSpecificTuya in Zigbee2MQTT, to transport Data Point IDs (DPs or DPIDs). A DP may represent a switch, temperature, mode, or setting. The number is not globally standardized across products: the same DPID can mean different things on different devices.

Other Tuya models use standard clusters for basic functions and vendor-specific extensions only for extras. The brand name alone is therefore not a compatibility test.

Typical symptoms include missing entities, incorrect scaling, apparently identical products with different manufacturer strings, or unknown DPs in the log.

How ZHA and Zigbee2MQTT differ

ZHA is built on zigpy. A ZHA Device Handler, commonly called a quirk, can replace an incomplete device description or translate non-standard behavior.

Zigbee2MQTT uses definitions and converters from zigbee-herdsman-converters. Generic model IDs such as TS0601 or TS0726 cover many unrelated products, so definitions also match the manufacturer string and sometimes a fuller fingerprint. The converter determines the published “exposes.”

Neither platform is universally better. Support depends on the exact model ID, manufacturer ID, endpoints, firmware, and the current project version.

Practical case: BSEED EC-GL86ZPCS21

Two BSEED EC-GL86ZPCS21 two-gang switches are installed in the bedroom. The tested units report model ID TS0726 and manufacturer _TZ3002_zjuvw9zf.

In this installation, ZHA did not separate the two channels correctly: controlling one channel affected both, and a tested quirk did not fix it. After migration to Zigbee2MQTT, the channels appeared separately and could be evaluated independently. This is a personal result for these units, not a claim about every BSEED or Tuya device.

Zigbee2MQTT currently documents the model with state_l1 and state_l2, countdowns, power-on behavior, backlight and indicator modes, per-channel switch/scene modes, and scene_1/scene_2 actions. Project history shows support being added for _TZ3002_zjuvw9zf. Other hardware batches and manufacturer IDs exist, so the shop model name alone is insufficient.

Virtual two-way switching

Only the actual load path is wired to the local relay in this setup. Zigbee2MQTT publishes the second control, Node-RED maps it to the desired Home Assistant entity, and the automation switches the target. This creates a logical two-way control path, not a conventional hard-wired two-way circuit.

If Home Assistant, Zigbee2MQTT, MQTT, Node-RED, or the mesh is unavailable, the logical control path fails. The locally wired path must be evaluated separately. Prefer an explicit target state over blind toggle where lost or duplicated messages could invert the result, and prevent a flow from reacting to its own state change.

No universal Node-RED import is included because entity IDs and the device's published event format are installation-specific.

Check compatibility before buying

1. Identify the exact variant. Record modelID and manufacturerName; appearance and retail name are weak identifiers.

2. Check Zigbee2MQTT exposes. Confirm that the exact functions you need are documented, not merely that the product name appears.

3. Check ZHA separately. Zigbee2MQTT support does not prove ZHA support, or vice versa.

4. Verify certification. Search the CSA database for the actual end product, not just a radio module or platform.

5. Keep a return option. Pair and test before the return period ends, especially for in-wall equipment.

Troubleshooting incomplete pairing

1. Save model ID, manufacturer ID, firmware, and full device signature.

2. Inspect endpoints, entities, and exposes.

3. Re-pair near the coordinator.

4. Review logs for unknown clusters, commands, or DPs.

5. Search the exact manufacturer string in the official converter and quirk repositories.

6. Back up Home Assistant and the Zigbee network before changing definitions or firmware.

Do not probe unknown writeable DPs with arbitrary values. On motors, thermostats, and mains actuators, an incorrect command can cause movement, unsafe limits, or unexpected switching.

Mains-voltage safety

In-wall switches normally operate at mains voltage. Device selection, installation, protective measures, and testing must follow the product instructions and be performed by appropriately qualified people. An unwired relay output is not automatically a safe scene button. Confirm that the exact device supports a detached or scene mode; otherwise the relay may still switch physically.

Conclusion

The practical issue is not “Tuya versus Zigbee 3.0.” It is application-level interoperability for a specific fingerprint. The BSEED case shows that a current Zigbee2MQTT definition can map one variant more completely than the tested ZHA handler, while also showing the reliability trade-off of a server-dependent virtual switch path.

Sources and technical documentation

• Tuya: Zigbee generic interfaces and private cluster 0xEF00
• Zigbee2MQTT: support new Tuya devices
• Zigbee2MQTT: find Tuya data points
• Zigbee2MQTT: BSEED EC-GL86ZPCS21
• Zigbee2MQTT issue: _TZ3002_zjuvw9zf support history
• Home Assistant: ZHA
• Connectivity Standards Alliance: certified products
• Node-RED documentation