How to setup local ZHA quirks

Hi Everybody, I have use HA for a while and recently decided to move from deconz to ZHA to see if that would increase stability. Stability has improved, but I have one device which does not show up correctly in ZHA.

I would really appreciate if someone could explain which files (, etc) to put where locally on my RPI such that I can use a local quirk for that device.

The steps as I understand them:

  1. Create a custom quirk dir in HA, e.g., /config/custom_zha_quirks
  2. In configuration.yaml, point to this directory:
  custom_quirks_path: /config/custom_zha_quirks/
  1. in this directory, create the python file with content of the quirk

Hi guys, did this work? Did you manage to have the quirks work?

Yes custom quirks path directory with manually copied custom quirks work but are not need often unless got a rare odd device or a brand new device with specialized features or deviating from standard, see ZHA documentation and if possible help edit to improve those docs for other users:—yaml

1 Like
 1. Create a custom quirk dir in HA, e.g., /config/custom_zha_quir

is it mean to " make Dir in Rapberry pi"
my System is Raspberry pi 4 + zigbee Dongle E

FYI, I wrote a guide for adding a custom quirk to ZHA as a pull request for the ZHA integration docs but it was not accepted →

UPDATE #1 This is also its own thread here → Zigbee Guide: How-to setup local custom device handler quirks in ZHA integration

UPDATE #2 Now also submitted as a pull request for ZHA Device Handlers (zha-quirks) readme file → Add a how-to guide for how end-users can use a custom quirk in ZHA by Hedda · Pull Request #2419 · zigpy/zha-device-handlers · GitHub

Manually add and use a not yet merged custom ZHA quirk

If you have bought a non-standard Zigbee device that is not yet supported by ZHA but someone have written a ZHA “quirk” module (ZHA Device Handler/Zigbee Converter) that not get been merged into a “ZHA Device Handlers"” library release then you can add that manually as a custom ZHA quirk to your Home Assistant instance, (using something like File Editor or Samba share add-ons in Home Assistant).

  1. Get a copy of an existing custom ZHA quirk or code your own quirks. Tip is to search using Zigbee device signature Issues · zigpy/zha-device-handlers · GitHub
  2. Create a directory/folder for your custom quirks (for example /config/zha_quirks/)
  3. Copy or create a quirk file in this directory (called it for example “”). This file should contain the Python script for the quirk and its specific Zigbee device signature unique to it.
  4. Add configuration with the full path to the directory that now containing custom quirk module(s) that will override and take precedence over any built-in quirks matching any device that has the same Zigbee device signature. to Home Assistant’s config.yaml
     database_path: /config/zigbee.db
     enable_quirks: true
     custom_quirks_path: /config/zha_quirks/        
  1. Restart Home Assistant to make the quirk take effect.

thanks for the explanation. I’ve done this for the “”“Samjin Multi 2019 Refresh Quirk.”"" because I wanted the tilt data (accelerometer x, y and z) which was availabe when I used Deconz / Phascon prior to switch to ZHA.

I added the quirk after pairing the device, and after restarting HA, I still don’t see the accelerometer sensor. Do I need to remove, and repair the device?

Yes, you have to remove and add the device again in order to install it using the info from your Quirk.

hmm ok I have removed and re added, but still no accelerometer sensors.

Maybe I installed the quirk incorrectly? I put the python files from this github into a sub-folder “config/custom_zha_quirks”

and then added that folder to my config.yaml

1 Like

Try this:

  enable_quirks: true
  custom_quirks_path: /config/custom_zha_quirks

thanks for trying, and for the link, but still no luck. I’m not sure what to try now.

  1. Enable quirks with the yaml above in your configuration.yaml file
  2. Remove all devices that are supposed to use new quirks
  3. Restart Home Assistant
  4. Pair the devices again

Is this what you have tried? Are you sure you have appropriated quirks for your devices?

yes that’s exactly what I did. And I’m sure I have the appropriate quirk. Should the python files be in their own sub-direcory like it was when I downloaded the quirks zip file? I just moved them into the /custom_zha_quirks as per your advice.

In fact, if I look at the “Device info” panel for the device, it looks like its using the quirk. And when I click on the three dots menu, and choose “SmartThingsAccelCluster” I can read the x,y,z acceleration data in the zigbee message, its just not exposed as a sensor entity in home assistant.

Why are you expecting those values in entities and not as part of the event? Have you seen any instalation of this device & quirk where those values are assigned to individual entities?

By the way, don’t you have that info as attributes of your vibration sensor entity? I’m not saying I’m expecting this, just curious.

By the way, I have an Aqara vibration sensor connected thru ZHA and I don’t have any entity with X, Y and Z values.

Sorry I’m new to ZHA. I used to use the Deconz zigbee hub, and with the same multi-sensor device, there was a sensor entity that with a template, I could extrac the x, y, and z acceleration values. I’m not sure what you mean by getting the “values as part of the event”. Which event?

I don’t think there is a vibration sesnor entity. The “Workshop door” and “Accelerometer” are both binary sensors.

The binary-sensor called “Accelerometer” was the one I was referring to. Don’t you have attributes under that sensor?

no, it’s binary

When a Zigbee device (and many other integrations) send a message to Home Assistant informing it changed, that is an event. Here you can find more on what events are.

For your automations, you can have a trigger based on a event for this specific device, as described here.

And you can use the trigger’s variables to get information about those values on your event, as described here

You can go to Developer tools > Events and then start listening for zha_event, then move your sensor and you will have an event like this (this is a screens hot from my Aqara sensor’s event):

  • be aware that not all commands will provide the coordinates in the args, so maybe your automation will have to monitor for specific commands on events.

In this case, I probably will get the “X” coordinates under or, etc…

Why don’t you share what you are trying to achieve with those values (X, Y and Z) or perhaps share your existing automation developed for DeCONZ so the community can try to help you more?

1 Like

Binary sensors can also have attributes.
Take a look for this binary sensor (and perhaps any other entity within this device) under Developer tools > State and take a look for attributes. Maybe you have this info (X, Y, Z) there.

1 Like

thankyou so much, this is what I needed!