{"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":"python","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":[{"wrong":"from zigpy.quirks import Device","symbol":"Device","correct":"from zhaquirks import CustomDevice"}],"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,"search_vec":"'1.1.1':53 'allianc':40 'allow':42 'assist':24,49,63 'autom':20 'conform':36 'continu':55 'correct':46 'custom':10 'devic':12,31,59,69,74 'device-support':68 'expand':57 'fulli':35 'function':45 'handler':13 'home':19,23,48,62 'home-assist':61 'implement':9 'integr':21 'iot':66,73 'iot-devic':72 'librari':8 'mani':29 'provid':26 'python':7 'quirk':2,4,14,71 'smarthom':67 'specif':41 'support':27,60,70 'version':52 'within':47 'zha':1,3,17,64 'zigbe':18,30,39,65 'zigpi':11","created_at":"2026-04-16T14:17:19.508820+00:00","updated_at":"2026-04-16T14:17:19.508820+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zigpy/zha-device-handlers","docs":null,"changelog":null,"pypi":"https://pypi.org/project/zha-quirks/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","http-networking","llm-agents","devops","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}