Tuya quirks library

What is this?

tuya-device-handlers is a "quirks" library used by Home Assistant's Tuya integration to fix or normalise misbehaving Tuya devices. A quirk is matched against a device's product_id and patches its datapoints (function/status_range/local_strategy) before Home Assistant builds entities from them.

The library is shipped to end users via Home Assistant — you do not install it directly.

Writing a quirk

1. Find your device's product_id and datapoints

In Home Assistant: Settings → Devices & services → Tuya → your device → Download diagnostics. The JSON contains the product_id, the cloud-reported function / status_range maps, and the current status values. Use these to decide what needs patching.

2. Create a quirk file

Drop a Python file into your Home Assistant config folder at <config>/tuya_quirks/<category>_<product_id_lowercased>.py. The <category> prefix follows Tuya's official category codes (e.g. cz for plug/socket, wk for thermostat, cl for curtain).

Quirks are built using a fluent DeviceQuirk builder. Minimal example — redefine one datapoint and remove another:

from tuya_device_handlers import TUYA_QUIRKS_REGISTRY
from tuya_device_handlers.builder import DeviceQuirk
from tuya_device_handlers.const import DPMode

(
    DeviceQuirk()
    .applies_to(product_id="abcdEFGHijkl1234")
    .add_dpid_integer(
        dpid=18,
        dpcode="cur_current",
        dpmode=DPMode.READ,
        unit="mA",
        min=0,
        max=30000,
        scale=0,
        step=1,
    )
    .remove_dpid(dpid=22, dpcode="phantom_dp")
    .register(TUYA_QUIRKS_REGISTRY)
)

Each quirk file should contain exactly one DeviceQuirk()...register(...) chain at module top level — the file path is captured for reload tracking. Available builder methods include add_dpid_boolean, add_dpid_bitmap, add_dpid_enum, add_dpid_integer, and remove_dpid. For more complex needs (custom value scaling, platform-specific definitions), see the in-tree examples under src/tuya_device_handlers/devices/.

New to this and not a programmer? For a fully worked, copy-paste walkthrough of one of the most common fixes — a device sending ENUM values (e.g. extra mode presets) that Home Assistant rejects as Found invalid ENUM value ... — see Recipe: add missing ENUM values. It covers writing the quirk, testing it live, and opening a PR end to end.

Entities missing — all of them, or just some? A quirk can only rewrite a device's datapoints; turning them into entities is Home Assistant's job, and it can only do that for a category and a DPCode it knows. If a datapoint is absent from the diagnostics, a quirk can add it; if it's present but never becomes an entity, the fix belongs in core. See Recipe: missing entities.

3. Test it inside Home Assistant

1. Restart the Tuya integration (Settings → Devices & services → Tuya → ⋮ → Reload). Quirks under <config>/tuya_quirks/ are reloaded each time, so you don't need to restart Home Assistant itself.
2. Watch the logs — you should see Loading custom quirk module … followed by Loaded custom quirks. Please contribute them to https://github.com/home-assistant-libs/tuya-device-handlers. If the import fails, the traceback is logged.
3. Verify the device's entities reflect your changes (download diagnostics again to confirm the patched function/status_range maps).

Contributing your quirk

Once your quirk works, please open a pull request so other Home Assistant users benefit.

1. Fork and clone this repository, then run uv sync.

2. Move your quirk file from <config>/tuya_quirks/ to src/tuya_device_handlers/devices/<category>/. The filename should match <category>_<product_id_lowercased>.py.

3. Add a device fixture JSON at tests/fixtures/devices/<category>_<product_id>.json. Build it from your Home Assistant diagnostics download: keep only the contents of the top-level data property (the captured device payload), then remove its id, terminal_id, and home_assistant keys. Name the file from the payload's own category and product_id fields. For example:

   python3 -c "
   import json
   d = json.load(open('diagnostics.json'))['data']
   for k in ('id', 'terminal_id', 'home_assistant'):
       d.pop(k, None)
   name = f\"tests/fixtures/devices/{d['category']}_{d['product_id']}.json\"
   with open(name, 'w') as f:
       json.dump(d, f, indent=2, ensure_ascii=False)
       f.write('\n')
   print(name)
   "
   

4. Add a test under tests/devices/<category>/ covering the patched behaviour.

5. Run the test suite locally:

   uv run pytest --cov tuya_device_handlers tests
   

6. Open a pull request.

For broader contributor guidelines (issue reporting, dev setup, pre-commit hooks), see the Contributor Guide.

License

Distributed under the terms of the MIT license, Tuya quirks library is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.