Project: Zigbee devices in Domoticz with Zigbee2MQTT, Mosquitto and the MQTT Auto Discovery gateway

[ZerOne]

The current recommended route for Zigbee in Domoticz (per the wiki) is Zigbee2MQTT (Z2M) -> MQTT broker -> Domoticz, using the built-in MQTT Auto Discovery Client Gateway (available since Domoticz release 2022.1). This guide follows the Domoticz wiki pages for Zigbee2MQTT and MQTT and the official Z2M docs (Z2M 2.14.x, Domoticz 2026.4 at the time of writing). The same pattern also works for Zwave-JS-UI.

Architecture

Code: Select all

Zigbee devices <-> coordinator USB stick <-> Zigbee2MQTT <-> Mosquitto (MQTT broker) <-> Domoticz

1. Hardware

You need a Zigbee coordinator (usually a USB stick) from the Z2M supported adapters list, flashed with coordinator firmware. Plug it into the host running Z2M and find its stable path:

Code: Select all

ls -l /dev/serial/by-id

2. Install Mosquitto

The Domoticz wiki uses the vvatelot/mosquitto-docker-compose project and recommends restart: unless-stopped so the broker survives reboots. With Mosquitto 2.x you must configure a listener. The wiki's quick fix is:

Code: Select all

listener 1883
allow_anonymous true

That lets anything on your network use the broker. I'd rather use a password file instead (create it with mosquitto_passwd and set allow_anonymous false and password_file), then enter the same username and password in Z2M and in the Domoticz gateway.

3. Install Zigbee2MQTT

Use the official Docker instructions at zigbee2mqtt.io Docker guide (docker compose with your by-id device mapped in, the /app/data volume, and /run/udev:ro for auto-detection).

Important port clash: Z2M's frontend defaults to port 8080, which is also Domoticz's default web UI port. The wiki advises changing the Z2M frontend port, for example to 8090. In your Z2M configuration:

Code: Select all

frontend:
    enabled: true
    port: 8090
mqtt:
    base_topic: zigbee2mqtt
    server: mqtt://<BROKER_IP>:1883
    user: <user>
    password: <password>
homeassistant:
    enabled: true          # this is what turns on MQTT Auto Discovery messages

When running in Docker, remember to change the published port mapping as well (for example 8090:8090 if you also changed the port in the config - or keep the container on 8080 and map host port 8090 to it). Compare your full config with the official configuration docs.

4. Z2M settings for Domoticz

• Enable the Home Assistant integration in Z2M (as above). Domoticz reads the same discovery messages. Keep the discovery topic at its default, homeassistant.
• Do not make the discovery topic the same as the base topic (zigbee2mqtt) - the wiki says this confuses Domoticz and other applications.
• Confirm Z2M is connected to the broker (MQTT Explorer from mqtt-explorer.com is the easiest way to see the topics).

5. Add the gateway in Domoticz

1. Go to Setup > Hardware and add MQTT Auto Discovery Client Gateway with LAN interface.
2. Enter the broker's real IP address (the Z2M wiki says not to use localhost or 127.0.0.1, which matters when things run in different containers) and port 1883, plus username/password if you set them.
3. Set the Auto Discovery topic to homeassistant (or whatever you set in Z2M).
4. Click Add.

If Z2M and Mosquitto run as separate Docker containers and Domoticz is on the host (or vice versa), use the host's LAN IP rather than a container hostname.

6. Pair devices

In the Z2M frontend click Permit join (All) (254 seconds) and put the device in pairing mode (pairing guide). Zigbee devices are added to Domoticz automatically as discovery data arrives. Per the wiki, Domoticz creates a device once it receives state data, so battery sensors can take a while to appear - wake them up by pressing their button. Find them under Setup > Devices.

Optionally add the Z2M frontend as a Domoticz custom menu entry: create Zigbee2MQTT.html in domoticz/www/templates containing an iframe pointing at http://<ip>:8090/, then restart Domoticz.

7. A simple dzVents automation

A sketch to turn a hallway light on for five minutes when a Zigbee motion sensor triggers (change the device names to match yours; add it under Setup > More Options > Events as a dzVents script - menu wording may vary slightly by version):

Code: Select all

return {
    on = { devices = { 'Hall motion' } },
    execute = function(domoticz, device)
        if device.active then
            domoticz.devices('Hall light').switchOn().forMin(5)
        end
    end
}

Debugging and gotchas

• The wiki warns not to combine state topics with the discovery (config) topic, because that triggers a device scan on every state update and loads Domoticz.
• MQTT messages are logged at debug level since stable 2021.1. To see them you must enable hardware debug logging (the wiki shows the daemon arguments). I'd only do that temporarily.
• Coming from the old Z2M Domoticz Python plugin? The wiki has a migration path: disable the plugin, add the Auto Discovery gateway, rename the new devices to the old names (or edit scripts), use "replace device" to keep history, then delete the old plugin hardware - leaving duplicates with the same names causes dzVents errors.
• Do not expose the broker or the Z2M frontend to the internet.

Question for the group: are you using Domoticz with Zigbee2MQTT, and what coordinator/sensors? Any dzVents tricks for dealing with Zigbee battery sensors or button actions you can share?