Skip to content


Repository files navigation

Zigbee2MQTT - Domoticz Python Plugin

Python plugin for Domoticz to add integration with zigbee2mqtt project




You can use Plugins Manager for automatic installation or follow manual steps:

  1. Clone repository into your domoticz plugins folder
cd domoticz/plugins
git clone zigbee2mqtt
  1. Restart domoticz
  2. Make sure that "Accept new Hardware Devices" is enabled in Domoticz settings
  3. Go to "Hardware" page and add new item with type "Zigbee2MQTT"
  4. Set your MQTT server address and port to plugin settings
  5. Add the device "api_transport" in 'Setup -> Devices'. The device can be hidden by adding a "$" in front of the name.

Once plugin receive device list from zigbee2mqtt server it will create appropriate domoticz devices. You will find these devices on Setup -> Devices page.

Plugin update

  1. Go to plugin folder and pull new version
cd domoticz/plugins/zigbee2mqtt
git pull
  1. Restart domoticz

Note: if you did any changes to plugin files and git pull command doesn't work for you anymore, you could stash all local changes using

git stash

Plugin downgrade

  1. Go to plugin folder and pull older version
cd domoticz/plugins/zigbee2mqtt
git reset --hard f8c22fc330229b39f06ff11bbfcea38e3a492306
  1. Restart domoticz or disable and re-enable plugin in 'Setup -> Hardware' (clearing browser cache might be necessary!)

Zigbee groups support

Plugin supports zigbee groups. It is impossible to automatically identify what device should represent the group (OnOff switch, dimmer, etc.), so plugin relies on suffixes in zigbee group name. Currently following suffixes are supported:

Suffix Device Type Example
_dimmer Dimmer Switch mygroup_dimmer
_ct Dimmer Switch with Color Temperature mygroup_ct
_rgb RGB Switch mygroup_rgb
_rgbw RGBW Switch mygroup_rgbw

if no suffix will be found then On/Off switch will be created by default


Plugin uses internal configuration to associate physical zigbee devices to logical ones in Domoticz. Configuration is a plain JSON object with the following structure:

    "aliases": Alias[]

where Alias type is used to associate single zigbee device feature to Domoticz logical device and viceversa. It has the following structure

    "domoticz": {
        "device_id": String     // Domoticz Device ID (not idx) in Domoticz
        "legacy_alias": String  // Alias, legacy key that was used in zigbee2mqtt plugin <= 3.0, required to support logical devices that were created before
        "unit": Number          // Domoticz Device Unit
    "zigbee": {
        "address": String       // Zigbee IEEE Address
        "endpoint": String      // Zigbee endpoint (for devices that have multiple ones like switches with several buttons)
        "feture": String        // zigbee2mqtt feature name (power, state, temperature, etc.)

in case if you manually remove the device or want a custom association please make sure that you've updated the configuration accordingly