Zigbee for Domoticz plugin wiki

The Zigbee for Domoticz plugin (ZigBeeForDomoticZ, Z4D) connects a Zigbee coordinator to Domoticz: your Zigbee devices become Domoticz widgets, entirely locally, with no cloud.

This English wiki is under review (October 2026) and is the only maintained version. The French and Dutch wikis are obsolete.

Before you start

What the current plugin requires. Check this before installing or upgrading.

• stable9 (9.1.xxx) is the production branch of the plugin. stable8 and older branches are out of support: if you are still on one of them, upgrade to stable9: from stable8 or from stable7.
• We recommend Domoticz 2026.3. stable9 requires Domoticz 2025.1 or newer and Python 3.11 or newer.
• Running several instances of the plugin (several coordinators) with Domoticz 2026.x and Python 3.11 doesn’t work because of a Python 3.11 problem (domoticz/domoticz#6763): use Python 3.12 or newer.

1. Getting started

New to the plugin? What it does, which coordinator to buy, which devices work.

• Getting started
• Compatible coordinators
• Compatible objects and certified devices

2. Installation

Install the plugin, declare it in Domoticz and open its WebUI, in four steps.

• Step 1: Plugin installation
  • With Docker
  • With Docker on a Synology NAS
  • On a DUSUN IoT gateway
  • Python virtual environment for Domoticz
• Step 2: Plugin settings — declare the plugin hardware in Domoticz
• Step 3: Plugin configuration — open the WebUI and check the settings
• Step 4: Plugin integration — open the WebUI from the Domoticz menu

3. Using the plugin

Everyday tasks: add and remove devices, set them up, use groups and bindings.

• Build a Zigbee mesh network — pair in the right order, routers first
• Add a new device
• Remove a device
• Replace a device while keeping its Domoticz history — Domoticz’s own Replace doesn’t work with the plugin
• Device parameters — per-device options (LEDs, sensitivity, power-on state, polling…)
• Manage Zigbee groups
• Bind two devices — let a switch command a light directly
• Change the Zigbee channel
• Change the coordinator transmit power
• Update device firmware — over-the-air updates

4. The WebUI

The plugin’s own web interface, at http://<Domoticz server>:9440/z4d/: one page per menu.

• General presentation — the menu bar, the indicators
• Dashboard — the state of the plugin and the devices at a glance
• Management — devices and groups
• Network — topology and interference level
  • Mesh graph — the Zigbee mesh, its relationships, routes and parent/child tree
• Admin — pairing, group scan, coordinator, plugin upgrade, device firmware
• Settings — every plugin setting
• Tools — commands, reporting, binding, debug, errors
  • Use the plugin tools — the data buttons and the REST API
• Manufacturer — only shown when a CASA.iA, ZLinky, TICmeter or Chameleon device is paired
• About

5. Keeping it running

Updates, backups, and what to do when the coordinator changes.

• Plugin update — routine updates of stable9, going back to a previous release, the plugin branches
• Upgrading from stable8 to stable9 — one-way switch for users still on stable8
• Upgrading from stable7 to stable9 — for users still on stable7, including old distributions and the move to a Python virtual environment
• Backup and restore — what to back up (plugin files and the Domoticz database), the backup scripts, reinstalling the plugin
• The scripts of the Tools folder — upgrade, clean-up, repair, watchdog, https certificate, OTA file checks
• Back up a zigpy coordinator — automatic backups, zigpy-cli
• Replace or migrate the coordinator
• Form a network with a zigpy coordinator — when Initialize Coordinator fails

6. Device-specific notes

Devices that need a specific setup or have known limits, by brand.

• Aqara
• BlitzWolf
• Danfoss
• Develco / Frient Intelligent Keypad
• Eurotronics
• Gamma Troniques TICmeter
• Ikea Tradfri
  • Ikea remote control as a pure remote
  • Ikea motion sensor
• Legrand Netatmo
  • Get the Legrand firmware for your device
• Livolo
• Müller Licht Tint
• Philips Gledopto
• Profalux
• Schneider Wiser
  • Schneider Wiser setup

7. When something goes wrong

A device doesn’t pair, doesn’t report, or the plugin shows errors: start here.

• Troubleshooting pairing or connection
• Dealing with a non-optimized device
• Deal with plugin errors
• Debug mode
• Plugin FAQ
• Getting help and reporting a problem — where to ask, expected logs, debug parameters, what to attach
• Ask on the English forum or the French forum, with the relevant part of the Domoticz log.

8. Advanced

For users who want to go further: describe a device yourself, reach the WebUI from outside, script, or look under the hood.

• Make a device work better:
  • Get devices well integrated with the plugin (device customization)
  • Integrate Tuya TS0601 devices
  • Model name resolution and Conf/Local-Devices precedence
• Reach the WebUI from outside:
  • Reverse proxy with Caddy
  • Reverse proxy with Apache 2
  • Dashboard access with basic authentication over https
• Scripts — community dzVents scripts: battery levels, lost devices, automation examples
• Technical information — REST API, plugin internals, device configuration files, protocol notes

Reference

• Zigbee and Wi-Fi — choosing a channel away from your Wi-Fi
• Firmware list — where to find firmware for coordinators and devices
• Widgets switch selector mapping
• Usage statistics — what the plugin sends anonymously, and how to opt out
• External reading:
  • Understanding a Zigbee network
  • A guide to wireless range and repeaters
  • Pairing Aqara/Xiaomi devices and keeping them connected, including with other brands

Legacy ZiGate

ZiGate coordinators are no longer supported by the plugin: we advise moving to a Texas Instruments, Silicon Labs or deCONZ coordinator (see Compatible coordinators). These pages are kept for existing ZiGate users and are not maintained.

• FAQ ZiGate
• ZiGate limitations
• Upgrading the ZiGate firmware (archived)
• Configure a ZiGate as a Zigbee sniffer
• PiZigate installation
• ZiGate internals
• In French, on zigate.fr: ZiGate backup & restore, ZiGate firmware update

Contribute and support

The plugin and this wiki are made on spare time. Any help is welcome:

• Translate the WebUI: it is available in English, French, German, Spanish, Italian and Dutch. Each language is a JSON file in the Domoticz-Zigbee-UI repository: copy en-US.json, translate the texts and open a pull request.
• Improve the wiki: report a mistake or a missing page in the wiki issues, or propose a change with a pull request.
• Contribute to the code: report bugs, test new versions, or propose changes on the plugin repository.
• Fund the project: even 5 € helps to buy new devices to test, integrate and certify, via PayPal.

Questions are welcome on Keybase or the forum.