ZHA Quirks

1.1.1 · active · verified Thu Apr 16

ZHA Quirks is a Python library implementing custom Zigpy device handlers (quirks) for the ZHA (Zigbee Home Automation) integration in Home Assistant. It provides support for many Zigbee devices that do not fully conform to the Zigbee Alliance specifications, allowing them to function correctly within Home Assistant. As of version 1.1.1, it continues to expand its device support.

Common errors

```
No module named 'zhaquirks' (or similar import error appearing in Home Assistant startup logs)
```
cause The `zha-quirks` library is not installed in the Python environment utilized by Home Assistant's ZHA integration.

fix Access your Home Assistant core's virtual environment (e.g., via `ha core venv` if using Home Assistant OS/Supervised, or SSH into the container) and execute `pip install zha-quirks`.
```
Device shows as 'Unknown ZHA device' or only generic clusters after pairing or restarting Home Assistant.
```
cause The device's unique signature (manufacturer, model ID, endpoints) does not match any known quirk in `zha-quirks`, or a custom quirk is not being loaded correctly (e.g., incorrect path, signature mismatch).

fix First, ensure `zha-quirks` is updated to the latest version. If it's a newly released device, it might not be supported yet. For custom quirks, verify the `signature` in your quirk code matches the device info and that the `custom_quirks_path` is correctly configured in Home Assistant's `configuration.yaml`.
```
TypeError: 'int' object is not callable (or other unexpected API errors within ZHA/zigpy logs after an update)
```
cause Incompatibility between versions of `zha-quirks`, `zigpy`, and potentially Home Assistant itself, often due to breaking changes in underlying libraries or API modifications.

fix Update all related components: `zha-quirks`, `zigpy` (if manually installed), and Home Assistant itself to their latest stable versions. Review Home Assistant's release notes for specific ZHA/Zigbee-related breaking changes that might require configuration adjustments.

Warnings

breaking Strict Python version requirements. Ensure your Python environment meets the requirements for the installed `zha-quirks` version.
Fix: Upgrade your Python environment to the version required by `zha-quirks` and Home Assistant, or install a compatible `zha-quirks` version if downgrading Python is not an option. Check `requires_python` in PyPI metadata.
gotcha `zha-quirks` is an extension for `zigpy`. Ensure `zigpy` is also up-to-date and compatible with both `zha-quirks` and your Home Assistant version, as incompatibilities can lead to ZHA instability or device recognition failures.
Fix: Regularly update `zha-quirks` and `zigpy` together, typically by updating Home Assistant itself if using the core integration. If manually installing or managing a virtual environment, ensure `pip install --upgrade zha-quirks zigpy`.
gotcha After installing `zha-quirks` or adding/modifying custom quirks, existing paired devices might not immediately pick up the new quirk due to ZHA caching device information.
Fix: Restart Home Assistant. If the device still isn't recognized, try 'Reconfigure device' from the ZHA device page in Home Assistant or, as a last resort, remove and re-pair the device. For custom quirks, also ensure `custom_quirks_path` is correctly configured in `configuration.yaml`.
gotcha Device signatures (manufacturer and model ID) in a custom quirk definition must *exactly* match what the physical device reports during discovery for the quirk to be applied.
Fix: Verify the device's signature from the ZHA integration's device info (e.g., from 'Manage Clusters' under 'Basic' cluster attributes) and ensure your custom quirk's `signature` dictionary matches it precisely, including case sensitivity.

Install

pip install zha-quirks Install latest version

Imports

Device
```
from zigpy.quirks import Device
```
Common base class for defining new device quirks.
CustomCluster
```
from zigpy.quirks import CustomCluster
```
Base class for defining custom ZCL clusters for devices.
zha
```
from zigpy.profiles import zha
```
Provides Zigbee Home Automation profile constants (e.g., PROFILE_ID, DeviceType).

Quickstart

This quickstart demonstrates the structure for creating a custom ZHA quirk, which is the primary way developers interact with this library's capabilities. This Python code defines a device quirk class that Home Assistant's ZHA integration (via `zigpy`) can automatically discover and load. The code itself is not meant to be run standalone to 'do' something directly, but rather to be integrated into a Home Assistant setup as a module. Replace `MyManufacturer`, `MyTempSensor`, and cluster definitions with your device's actual signature and desired behavior.

import logging
from zigpy.profiles import zha
from zigpy.quirks import CustomCluster, Device
from zigpy.zcl.clusters.general import Basic, Identify
from zigpy.zcl.clusters.measurement import TemperatureMeasurement

_LOGGER = logging.getLogger(__name__)

class MyCustomTemperatureCluster(CustomCluster, TemperatureMeasurement):
    cluster_id = TemperatureMeasurement.cluster_id
    # Add any specific attributes or commands for this custom cluster if necessary

class MyCustomDeviceQuirk(Device):
    """Custom quirk for a hypothetical MyManufacturer Temp Sensor."""

    signature = {
        # The 'signature' must exactly match the device's reported model_id and manufacturer.
        # This determines if the quirk is applied to a discovered device.
        "model_id": "MyTempSensor",
        "manufacturer": "MyManufacturer",
        # Endpoint configuration is defined in 'replacement', not directly in 'signature'.
    }

    replacement = {
        1: zha.Endpoint(
            profile_id=zha.PROFILE_ID,
            device_type=zha.DeviceType.TEMPERATURE_SENSOR,
            input_clusters=[
                Basic.cluster_id,
                MyCustomTemperatureCluster, # Use your custom cluster or a standard one
                Identify.cluster_id,
            ],
            output_clusters=[]
        )
    }

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        _LOGGER.info(f"MyCustomDeviceQuirk detected: {self.model_id} from {self.manufacturer}")

# To make this quirk functional within Home Assistant's ZHA integration:
# 1. Save this code as a .py file (e.g., `my_custom_sensor.py`) in a dedicated directory, 
#    for example, `/config/custom_zha_quirks/` within your Home Assistant configuration.
# 2. Add the following to your Home Assistant `configuration.yaml`:
#    `zha: 
#      custom_quirks_path: /config/custom_zha_quirks/`
# 3. Restart Home Assistant.
# 4. If the device was previously paired, you might need to 'Reconfigure device' from its 
#    ZHA device page or, in some cases, remove and re-pair the device to apply the quirk.

# Replace `MyManufacturer`, `MyTempSensor`, and cluster definitions with your device's actual details.

view raw JSON →