ZHA Device Handlers are custom quirks implementations for Zigpy, the library that provides the Zigbee support for the ZHA component in Home Assistant.
ZHA device handlers bridge the functionality gap created when manufacturers deviate from the ZCL specification, handling deviations and exceptions by parsing custom messages to and from Zigbee devices. Zigbee devices that deviate from or do not fully conform to the standard specifications set by the Zigbee Alliance may require the development of custom ZHA Device Handlers (ZHA custom quirks handler implementation) to for all their functions to work properly with the ZHA component in Home Assistant.
Custom quirks implementations for zigpy implemented as ZHA Device Handlers are a similar concept to that of Hub-connected Device Handlers for the SmartThings Classics platform as well that of Zigbee-Herdsman Converters / Zigbee-Shepherd Converters as used by Zigbee2mqtt, meaning they are virtual representation of a physical device that expose additional functionality that is not provided out-of-the-box by the existing integration between these platforms. See Device Specifics for details.
For specific Zigbee debugging instructions on capturing logs and more, see the contributing guidelines in the CONTRIBUTING.md file:
If you are looking to make your first code contribution to this project then we also suggest that you follow the steps in these guides:
- https://github.com/firstcontributions/first-contributions/blob/master/README.md
- https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md
- Contact Sensor: CentraLite 3300-S
- Motion Sensor: CentraLite 3305-S
- Dimmer Switch: CentraLite 3130
- Water Sensor: CentraLite 3315-S
- Contact Sensor: CentraLite 3320-L
- Motion Sensor: CentraLite 3325-S
- Motion Sensor: CentraLite 3326-L
- Contact Sensor: CentraLite 3321-S
- Temperature / Humidity Sensor: CentraLite 3310-S
- Smart Button: CentraLite 3460-L
- Thermostat: CentraLite 3157100
- Cube: lumi.sensor_cube.aqgl01
- Button: lumi.sensor_switch.aq2
- Vibration Sensor: lumi.vibration.aq1
- Contact Sensor: lumi.sensor_magnet.aq2
- Motion Sensor: lumi.sensor_motion.aq2
- Temperature / Humidity Sensor: lumi.weather
- Water Leak: lumi.sensor_wleak.aq1
- US Plug: lumi.plug.maus01
- EU Plug: lumi.plug.mmeu01
- CN Plug: lumi.plug
- Arrival Sensor: tagv4
- Motion Sensor: MotionV4
- Multi Sensor: MultiV4
- Temperature / Humidity / Pressure Sensor: LUMI RS-THP-MP-1.0
- Connected Bulb Remote: Lutron LZL4BWHL01 Remote
- Water Sensor: leakSMART Water Sensor V2
- XBee Series 2: xbee
- XBee Series 3: xbee3
- TS0601 switch: Tuya-based 1-gang switches with neutral (e.g. Lerlink, Lonsonho)
- Update Home Assistant to 0.85.1 or a later version.
NOTE: Some devices will need to be unpaired and repaired in order to see sensor values populate in Home Assistant.
- All supported devices report battery level
- Dimmer Switch publishes events to Home Assistant
- Dimmer Switch temperature sensor is removed because it is non functional
- 3321-S reports acceleration
- 3310-S reports humidity
- Dimmer Switch publishes events to Home Assistant and reports battery level
- Dimmer Switch temperature sensor is removed because it is non functional
- All supported devices report battery level
- All supported devices report temperature but I am unsure if it is correct or accurate
- Vibration sensor exposes a binary sensor in Home Assistant that reports current vibration state
- Vibration sensor sends
tiltanddropevents to Home Assistant - Cube sends the following events:
flip (90 and 180 degrees),rotate_left,rotate_right,knock,drop,slideandshake - Motion sensor exposes binary sensors for motion and occupancy.
- Button sends events to Home Assistant
- All supported plugs report power consumption and can be toggled
- All supported devices report battery level
- tagV4 exposed as a device tracker in Home Assistant. The current implementation will use batteries rapidly
- MultiV4 reports acceleration
- Connected bulb remote publishes events to Home Assistant
- leakSMART water sensor is exposed as a binary_sensor with DEVICE_CLASS_MOISTURE
- Some functionality requires a coordinator device to be XBee as well
- GPIO pins are exposed to Home Assistant as switches
- Analog inputs are exposed as sensors
- PWM output on XBee3 can be controlled by writing 0x0055 (present_value) cluster attribute with
zha.set_zigbee_cluster_attributeservice - Outgoing UART data can be sent with
zha.issue_zigbee_cluster_commandservice - Incoming UART data will generate
zha_eventevent. - PWM can be controlled with
zha.set_zigbee_cluster_attributeservice
Please refer to xbee.md for details on configuration and usage examples.
- All supported devices report battery level
Testing a new release of the zha-quirks package before it is released in Home Assistant.
If you are using Supervised Home Assistant (formerly known as the Hassio/Hass.io distro):
- Add https://github.com/home-assistant/hassio-addons-development as "add-on" repository
- Install "Custom deps deployment" addon
- Update config like:
where 0.0.38 is the new version
pypi: - zha-quirks==0.0.38 apk: [] - Start the addon
If you are instead using some custom python installation of Home Assistant then do this:
- Activate your python virtual env
- Update package with
pippip install zha-quirks==0.0.38
If you are using Supervised Home Assistant (formerly known as the Hassio/Hass.io distro) you will need to get access to the home-assistant docker container. Directions below are given for using the portainer add-on to do this, there are other methods as well not covered here.
-
Install the portainer add-on (https://github.com/hassio-addons/addon-portainer) from Home Assistant Community Add-ons.
-
Follow the add-on documentation to un-hide the home-assistant container (https://github.com/hassio-addons/addon-portainer/blob/master/portainer/DOCS.md)
-
Stage the update quirk in a directory within your config directory
-
Use portainer to access a console in the home-assistant container:
-
Access the quirks directory
- on HA > 0.113: /usr/local/lib/python3.8/site-packages/zhaquirks/
- on HA < 0.113: /usr/local/lib/python3.7/site-packages/zhaquirks/
-
Copy updated/new quirk to zhaquirks directory:
cp -a /config/temp/NEW_QUIRK ./ -
Remove the pycache folder so it is regenerated
rm -rf ./__pycache__/ -
Close out the console and restart HA.
-
Note: The added/update quirk will not survive a HA version update.
- Special thanks to damarco for the majority of the device tracker code
- Special thanks to Yoda-x for the Xioami attribute parsing code
- Special thanks to damarco and Adminiuga for allowing me to bounce ideas off of them and for listening to me ramble
zigpy is Zigbee protocol stack integration project to implement the Zigbee Home Automation standard as a Python 3 library. Zigbee Home Automation integration with zigpy allows you to connect one of many off-the-shelf Zigbee adapters using one of the available Zigbee radio library modules compatible with zigpy to control Zigbee based devices. There is currently support for controlling Zigbee device types such as binary sensors (e.g., motion and door sensors), sensors (e.g., temperature sensors), lightbulbs, switches, locks, fans, covers (blinds, marquees, and more). A working implementation of zigpy exist in Home Assistant (Python based open source home automation software) as part of its ZHA component
zha-map project allow building a Zigbee network topology map for ZHA component in Home Assistant.
zha-network-visualization-card is a custom Lovelace element for visualizing the Zigbee network map for ZHA component in Home Assistant.
zha-network-card is a custom Lovelace card that displays ZHA network and device information in Home Assistant
zigpy-deconz-parser project can parse Home Assistant ZHA component debug log using zigpy-deconz library if you have ConBee or RaspBee hardware.