{"id":7879,"library":"zha-quirks","title":"ZHA Quirks","description":"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.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/zigpy/zha-quirks","tags":["home-assistant","zha","zigbee","iot","smarthome","device-support","quirks","iot-device"],"install":[{"cmd":"pip install zha-quirks","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for Zigbee protocol and device handling.","package":"zigpy","optional":false}],"imports":[{"note":"Common base class for defining new device quirks.","symbol":"Device","correct":"from zigpy.quirks import Device"},{"note":"Base class for defining custom ZCL clusters for devices.","symbol":"CustomCluster","correct":"from zigpy.quirks import CustomCluster"},{"note":"Provides Zigbee Home Automation profile constants (e.g., PROFILE_ID, DeviceType).","symbol":"zha","correct":"from zigpy.profiles import zha"}],"quickstart":{"code":"import logging\nfrom zigpy.profiles import zha\nfrom zigpy.quirks import CustomCluster, Device\nfrom zigpy.zcl.clusters.general import Basic, Identify\nfrom zigpy.zcl.clusters.measurement import TemperatureMeasurement\n\n_LOGGER = logging.getLogger(__name__)\n\nclass MyCustomTemperatureCluster(CustomCluster, TemperatureMeasurement):\n    cluster_id = TemperatureMeasurement.cluster_id\n    # Add any specific attributes or commands for this custom cluster if necessary\n\nclass MyCustomDeviceQuirk(Device):\n    \"\"\"Custom quirk for a hypothetical MyManufacturer Temp Sensor.\"\"\"\n\n    signature = {\n        # The 'signature' must exactly match the device's reported model_id and manufacturer.\n        # This determines if the quirk is applied to a discovered device.\n        \"model_id\": \"MyTempSensor\",\n        \"manufacturer\": \"MyManufacturer\",\n        # Endpoint configuration is defined in 'replacement', not directly in 'signature'.\n    }\n\n    replacement = {\n        1: zha.Endpoint(\n            profile_id=zha.PROFILE_ID,\n            device_type=zha.DeviceType.TEMPERATURE_SENSOR,\n            input_clusters=[\n                Basic.cluster_id,\n                MyCustomTemperatureCluster, # Use your custom cluster or a standard one\n                Identify.cluster_id,\n            ],\n            output_clusters=[]\n        )\n    }\n\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        _LOGGER.info(f\"MyCustomDeviceQuirk detected: {self.model_id} from {self.manufacturer}\")\n\n# To make this quirk functional within Home Assistant's ZHA integration:\n# 1. Save this code as a .py file (e.g., `my_custom_sensor.py`) in a dedicated directory, \n#    for example, `/config/custom_zha_quirks/` within your Home Assistant configuration.\n# 2. Add the following to your Home Assistant `configuration.yaml`:\n#    `zha: \n#      custom_quirks_path: /config/custom_zha_quirks/`\n# 3. Restart Home Assistant.\n# 4. If the device was previously paired, you might need to 'Reconfigure device' from its \n#    ZHA device page or, in some cases, remove and re-pair the device to apply the quirk.\n\n# Replace `MyManufacturer`, `MyTempSensor`, and cluster definitions with your device's actual details.","lang":"python","description":"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."},"warnings":[{"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.","message":"Strict Python version requirements. Ensure your Python environment meets the requirements for the installed `zha-quirks` version.","severity":"breaking","affected_versions":"All versions (e.g., <1.1.1 required 3.8+, 3.10+; 1.1.1 requires >=3.12)"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The `zha-quirks` library is not installed in the Python environment utilized by Home Assistant's ZHA integration.","error":"No module named 'zhaquirks' (or similar import error appearing in Home Assistant startup logs)"},{"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`.","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).","error":"Device shows as 'Unknown ZHA device' or only generic clusters after pairing or restarting Home Assistant."},{"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.","cause":"Incompatibility between versions of `zha-quirks`, `zigpy`, and potentially Home Assistant itself, often due to breaking changes in underlying libraries or API modifications.","error":"TypeError: 'int' object is not callable (or other unexpected API errors within ZHA/zigpy logs after an update)"}]}