The most home automation systems like Zeegbee2MQTT, deCONZ or HomeAssistant ZHA have basic support only for generic functions of PTVO devices (switches, light control, simple temperature sensors). But they cannot receive and process data from analog external sensors.

The custom external converter for Zeegbee2MQTT, DDF file for deCONZ, or ZHA Device Handler, for your configuration of the firmware. The custom converter allows you to implement and control all functions in a high-level system.

The converter includes “exposes” or “handlers” for supported features, and Z2M frontend or HomeAssistant provide the correct user interface controls for your device.

Additionally, it provides smooth integration with other high-level systems based on Z2M like HomeAssistant, ioBroker, and others.


You should place the generated file in the “data” folder of your Z2M installation and add a link to it in the Z2M’s configuration. Note: Custom converters are available in the Z2M version 1.18.2 and higher.

HomeAssistant + Zigbee2MQTT add-on

It is similar to the case above. You’ll need to find the “data” folder for the Z2M add-on.

HomeAssistant + ZHA add-on

You should enable support of custom quirks in ZHA (look at the “Configuration – YAML” paragraph).

Enabling quirks

After this, upload the created file with the “.py” extension to a folder specified in the “custom_quirks_path” parameter. After adding or updating a quirk, you should reload the ZHA add-on. If you change the device configuration, you should delete and re-join the device too.

The properly detected Zigbee device with a custom quirk should have the corresponding info in the “Zigbee info” field.

Reloading ZHA add-on
Reloading ZHA add-on
Zigbee device with custom quirk
Zigbee device with custom quirk


Follow this link.

Note: the following example is written for deCONZ on Windows 10. If you use Linux or other OS, you should find and use the corresponding folder and files in your OS.

Harvey Specter
Posted at 19:56 February 14, 2024
Mats Rosenberg

Hello, when I try to enable quirks for Home Assitant ZHA with the following parameters, ZHA is not starting anymore – could anyone help? Possibly the database_path is wrong – I don’t know what this should be and the HA documentation does not really help…

# Enables Zigbee quirk configurations
database_path /config/
enable_quirks true
custom_quirks_path /config/zhaquirks

    Harvey Specter
    Posted at 13:00 February 15, 2024

    1. Do not specify the “database_path” parameter (if it was not added before).
    2. Check formatting (leading spaces and colons).
    I’ve updated the page, please look at the screenshot.

Leave a Reply