A Zigbee device can expose different features in ZHA and Zigbee2MQTT. The hardware has not changed, but the software interpreting its messages has. Each project maintains its own device support, and an implementation in one does not automatically become an implementation in the other.
A ZHA quirk and a Zigbee2MQTT converter can both supply missing device knowledge. Their roles overlap, but they are not exact equivalents: ZHA can handle many standard devices without a quirk, while Zigbee2MQTT’s definitions and converters also describe ordinary standards-based devices. Understanding that difference makes compatibility checks much less confusing. For the wider platform decision, see our ZHA and Zigbee2MQTT comparison.
How their roles overlap
ZHA uses zigpy and Python device handlers. Its quirks can correct a device’s unusual cluster layout, parse proprietary messages, adjust reporting behaviour or expose manufacturer-specific features that the standard integration does not provide. A quirk may compensate for a standards deviation, but an extra vendor feature is not automatically evidence of defective firmware.
Zigbee2MQTT uses zigbee-herdsman and the JavaScript/TypeScript zigbee-herdsman-converters package. A device definition identifies the hardware, declares its features and connects the appropriate message conversions and configuration. Those conversions can handle standard Zigbee attributes as well as vendor-specific data.
A quirk is usually an addition to ZHA’s generic handling. A Zigbee2MQTT definition is part of how that platform describes supported hardware. Counting quirk files against converter definitions would not give a fair device-support comparison.
The files are not interchangeable. A Python quirk cannot be loaded as a Zigbee2MQTT external converter, and ZHA cannot load a Zigbee2MQTT converter file as a quirk. Developers can reuse knowledge of the protocol, but they have to express it through the receiving project’s APIs and check the result there.
What a ZHA quirk actually does
The zha-device-handlers project describes its purpose as bridging functionality gaps around deviations, exceptions and custom messages. Older v1 quirks commonly match a device signature and replace its device or cluster classes. The newer v2 builder approach can also declare entity metadata and device-specific behaviour with less repeated setup code. The implementation depends on the device; it is not always a simple renaming of an attribute.
A standard light or sensor may work through ZHA’s normal cluster handling without any device-specific quirk. Conversely, missing entities do not prove that no quirk exists. The installed release may predate the implementation, a similar-looking variant may have a different signature, the relevant entity may be disabled, or pairing, reporting or a regression may be involved.
Start by checking the device’s manufacturer, model and diagnostic signature, together with the quirk actually applied in ZHA. Then compare the missing feature with the supported behaviour. A successful join only establishes network membership; it does not demonstrate that every advertised function has been mapped to a Home Assistant entity.
What a Zigbee2MQTT converter actually does
A Zigbee2MQTT device definition normally matches a zigbeeModel or a more specific fingerprint. It provides branding, feature descriptions called exposes, message conversion and, where needed, setup such as binding and reporting configuration. Modern extend helpers bundle much of this work for common features. The conversion package interprets the device; Zigbee2MQTT publishes the resulting state over MQTT and handles Home Assistant discovery separately.
The current new-device guide also describes feature discovery and generated external definitions. These can provide a starting point for standard clusters, but cannot reliably discover every proprietary feature. For Tuya devices, the reported manufacturer identifier and data-point mapping may be more informative than a shared retail name or a generic TS0601 model string.
| ZHA quirk | Zigbee2MQTT definition/converters | |
|---|---|---|
| Where it lives | zha-device-handlers, using Python and zigpy APIs | zigbee-herdsman-converters, using JavaScript/TypeScript and herdsman APIs |
| Typical role | Adjust generic handling or add device-specific features and entities | Identify hardware, declare features, convert messages and configure the device |
| Standard devices | May work without a quirk | Can use standard converters and modern extends |
| Can the other platform load the file? | No | No |
| What to compare | Applied quirk, standard handling, installed version and required features | Exact matching definition, exposes, installed version and required features |
Why support can differ between platforms
The projects have separate implementations, reviewers, release schedules and bug fixes. A contributor may have added one device to Zigbee2MQTT before anyone worked on its ZHA support, or the reverse. A feature can also be supported differently: one platform might offer a configuration entity while another exposes an action or requires a different setup step.
Absence of a matching file is only one possible explanation. A fully standard device may need no ZHA quirk, and a firmware variant may need changes to an existing definition rather than a new one. Before choosing a platform around a single missing feature, establish the exact hardware identity and whether the implementation has reached the version you actually run.
These projects do not provide a shared drop-in device-handler format. Reading the other implementation can help, but copying its file into the wrong integration does not add support. Any port still needs matching identifiers, correct units and commands, and testing of the intended features.
Our guide to the “no converter available” message covers the Zigbee2MQTT side of that investigation. For Tuya hardware in particular, matching the specific manufacturer/model combination matters more than assuming every device labelled TS0601 speaks the same application protocol.
Using a Zigbee2MQTT converter to develop a ZHA quirk
The Tuya v2-quirk guide and the project’s current Tuya contributor instructions show a useful development route: obtain the device’s data-point mappings from an existing herdsman converter, then implement them with TuyaQuirkBuilder. Another documented route is to obtain those data points through Tuya’s developer tools.
That makes a working converter useful reference material. A developer may already have the data-point IDs, scales, enumeration values and command behaviour instead of starting with unknown messages. They still need to check that the reference covers the same manufacturer and firmware variant, choose suitable ZHA entities and verify what the target device actually does.
This is an example of knowledge shared between projects, rather than the defining purpose of every v2 quirk. The builder supports more than ports from Zigbee2MQTT, and a reference implementation does not promise that someone will make a port or when it will be released. Home Assistant’s documentation explicitly notes that volunteer device-support requests do not guarantee a new quirk.
How to check the features you need
For a device you already own, make the comparison around the features you need rather than a general reputation for supporting more brands. These checks are useful on both sides:
- Record the exact model, reported Zigbee model and manufacturer, regional variant and firmware when available. Rebrands can share an enclosure while using different electronics.
- Look up the exact device on Zigbee2MQTT’s supported-device list, read its exposes and notes, and check that the implementation is included in your installed version.
- For ZHA, read the official compatibility guidance. ZHA has no complete official supported-device list. Check standard support, relevant quirks and specific feature reports rather than treating an absent quirk as an automatic failure.
- Compare controls, measurements, actions and settings individually. If something is missing, check diagnostics and reporting before assuming a platform switch is required.
If both platforms provide the features you need, choose around your existing setup, MQTT preferences, automations and maintenance habits. If only one currently provides an essential proprietary feature, that is a concrete reason to choose it. An open pull request or an implementation in a development branch is useful information, but it should not be treated as functionality already shipped in a stable release.
For contributors, implementing the missing quirk or converter remains an option. Keep a clear distinction between the protocol facts learned from another project and the code, matching rules and tests required by the target integration.
FAQ
Can I use a Zigbee2MQTT converter file in ZHA? No. ZHA needs a Python handler built for its own APIs. A converter can supply protocol information for a port, not a directly loadable quirk.
Why are entities missing on one platform? Device-specific support can differ, but also check the exact variant, installed versions, applied handler, disabled entities and successful configuration. The symptom alone does not identify the cause.
Are quirks and converters doing the same thing? They overlap when translating proprietary behaviour or adding features. A converter also handles ordinary supported Zigbee messages, while a standard device may work in ZHA without a quirk.
Can a ZHA quirk use a Zigbee2MQTT implementation as a reference? Yes. The Tuya contributor guides describe using herdsman data-point mappings with TuyaQuirkBuilder. It still requires implementation and validation in ZHA, and the builder is not limited to this workflow.
Will switching platforms change the device’s features? It can change the available entities, actions and settings, even on the same physical device. Compare the exact features first and allow for re-pairing and rebuilding affected automations.
Sources and scope
The distinctions here follow the device-handler project, its Tuya implementation guide, Home Assistant’s ZHA documentation and Zigbee2MQTT’s new-device workflow. They establish how support is implemented, not a measured ranking of brand coverage. Normal Zigbee message handling runs locally in either stack; downloads, OTA sources, optional integrations and the wider Home Assistant installation have their own connectivity requirements. No device was paired for this explainer.