Tuya Zigbee devices: same model ID, different datapoints

Symptom

A cheap Zigbee sensor, thermostat valve or curtain motor pairs fine but shows as unsupported, exposes the wrong features, or a device that "is supported" behaves differently from the one in the documentation, although the label and model name are identical.

Why

• Many Tuya devices don't use standard Zigbee clusters for their functions. They tunnel everything through the manufacturer-specific manuSpecificTuya cluster as datapoints (DPs): a DP ID, a data type and a value, one per function.
• Many Tuya devices share the same modelID but use different datapoints. The distinguishing field is the manufacturerName, e.g. _TZE200_d0yu2xgi. White-label products under different brands can be the same device, and one brand's "model" can hide several different devices.

So support is per manufacturerName + modelID fingerprint, not per product name.

What to do

1. Before buying, look up the exact manufacturerName (from reviews, forums or the stack's device list), not just the product name.
2. After pairing, read the device's manufacturerName and modelID in Zigbee2MQTT or ZHA and compare with the supported-devices entry.
3. Unsupported:
   • Zigbee2MQTT: write an external converter (JavaScript in the external_converters folder next to configuration.yaml) that maps DPs to exposed features; once it works, contribute it upstream so it becomes built-in.
   • ZHA: support comes through ZHA Device Handlers ("quirks"), device-specific Python scripts.
4. Expect firmware variants: the same fingerprint can change behavior after a vendor firmware change.

Tuya devices are often good value, but budget time for this when the exact variant isn't listed yet.