Owner
OwnerThe 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 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.
Firmware Configurator allows creating the custom external converter for Zeegbee2MQTT, DDF file for deCONZ, or ZHA Device Handler (quirk), for your configuration of the firmware. You can do it on the “Expert” tab, by clicking on the “Save custom converter” button. Of course, you can also adjust this converter for your needs, for example, change sensor’s descriptions.
Zigbee2MQTT
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.
Z2M V2. Now, the converter should be in the “external_converters” folder.
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).
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.
Deconz
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.
alainvtr
Hi !
I’m making tests with external_converter : should i use it or not ?
So, with the same device, one with and another without.
Without external_converter, since Z2M v2.0, i’ve lost all binary_sensors : state become “unknown”, so totally unusable.
I have to hide all and made template with MQTT.
With external_converter (1st PTVO of 2025) , i’ve plenty of entity in HA :
– i’ve recovered the binary_sensor with a huge difference : the default state should be off but it is on !
– i have select.xxxx_bind_command_xxxx entities with a “unknown” state
– i have select.xxxx_link_to_output_xxxx entities with a “unknown” state
– i have select.xxxx_switch_actions_xxxx entities with a “unknown” state
– i have select.xxxx_switch_type_xxxx entities with a “unknown” state
My questions are on what to modify in the converter to :
– reverse the result of the binary_sensor
– remove the unwanted entities
Thanks.
David Simon
Also, I noticed a bug in the ZHA quirk output from the program. I have some simple GPIO inputs on my device, and in the actual ZCL these endpoints have device type 0xFFFE. However, in the quirk, the signature is expecting the device types in the signature to be 0x0002 for the bound input and the 0x0006 for the unbound inputs; in other words, it’s expecting the signature to already match the replacement device types! After editing the .py to use PTVO_DEVICE_TYPE_GENERIC in the signature for all endpoints, the quirk was able to match.
Device configuration: https://pasteboard.co/JQYdr5CT9fWl.png
Owner
Please download the latest version of the firmware and try it. Note: it is better to report and discuss bugs on GitHub.
David Simon
It might be worth adding a paragraph to the start of this page explaining that the expert tab has a button for automatically generating external converters! It took me a while to notice that button, and until I saw it, I assumed that this page was just general advice on Zigbee2MQTT/ZHA/etc.
Owner
Thank you! Done.
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
zha:
database_path /config/
enable_quirks true
custom_quirks_path /config/zhaquirks
Owner
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.