Zigbee2MQTT

From Domoticz
Jump to navigation Jump to search

Open Source Zigbee Gateway with zigbee2mqtt


Buy Hardware

For Zigbee you need a Zigbee Coordinator. Mostly this is a USB stick. For supported coordinators see website Supported Adapters | Zigbee2MQTT

Install and run Zigbee2MQTT

Prerequisites:

Installing docker compose

If you do not have docker compose already installed, follow the below steps to do so 

sudo apt-get update && sudo apt-get upgrade

sudo apt-get install -y make git

curl -fsSL test.docker.com -o get-docker.sh && sh get-docker.sh
sudo usermod -aG docker ${USER}
sudo systemctl enable docker
sudo reboot

Docker compose hardly does take any system resources and is a great way to install packages/services.

This is because it runs in its separate system and can use certain system resources (like hdd, serial ports)

It is advised to install all docker compose containers in their own folder (do this in the /opt folder, like /opt/domoticz or /opt/zigbee2mqtt)

You want your settings/data folders on your local system, so you can map local folders/files to the docker container.

This is called 'volumes'. You can make volumes/links globally, but I advise to keep all folders/files in the docker folder itself.

This way it is easy to make backups, you just copy the folder.


A quick tutorial, you start a docker compose container with 

docker compose up -d

(The -d means, run in the background). To stop a docker compose you issue 

docker compose down

If you want to see what's going on you start the docker compose container without the -d flag, when done, press control-c to stop (the docker compose container is stopped)

MQTT Broker

Zigbee2MQTT communicates via MQTT with Domoticz. (Zigbee2MQTT <---> MQTT <---> Domoticz)

So, for this to work you need to have a MQTT broker up and running. And this is the hardest part in this setup process. 

sudo su -
git clone https://github.com/vvatelot/mosquitto-docker-compose /opt/mosquitto
cd /opt/mosquitto
make setup-project
docker compose up -d

For more information have a look on this page

There is one additional step we need to be doing, we want the MQTT broker to restart when the system starts or reboots.

For this you have to edit the file docker-compose.yaml in /opt/mosquitto and add the following line underneath 'mosquitto:' 

    restart: unless-stopped

Make sure it aligns with spaces at the same start as the line below (build:) so it looks like: 

services:
  mosquitto:
    restart: unless-stopped
    build:
      context: .

Next restart the docker compose container with 

docker compose down
docker compose up -d

MQTT should now be available on port 1883. You can also use an application like 'MQTT Explorer' to connect to your new broker

You should enter the machine's IP address (like 192.168.2.3), not localhost and not 127.0.0.1!

See also Wiki page MQTT#Add_hardware MQTT_Auto_Discovery_Client_Gateway

Install Zigbee2MQTT

Next install the Zigbee2MQTT Docker image with the following instruction: https://www.zigbee2mqtt.io/guide/installation/02_docker.html#creating-the-initial-configuration

NOTE: If you use the frontend of Zigbee2MQTT be sure to change the port to for example 8090 as the default port 8080 is also the default port of Domoticz Web UI.

There are other installation methods, see instructions on Installation | Zigbee2MQTT

Domoticz and zigbee2mqtt

Alternative 1: Use Domoticz MQTT Autodiscover

The preferred method as since release 2022.1 MQTT Autodiscover is implemented in Domoticz.

Setup:

  • Zigbe22MQTT settings:
    • In your Zigbee2MQTT configuration.yaml set homeassistant: true (link) , nano /opt/zigbee2mqtt/data/configuration.yaml or use the User interface:


  • If you use MQTT Autodiscover also for another MQTT Gateway (eg Zwave-JS-UI) then is it advised to set the HomeAssistant_discovery_topic (default homeassistant) in Zigbee2MQTT In your Zigbee2MQTT configuration.yaml (link) to something else (eg zigbeeAD) for easier debugging and maintenance. This also forces to create a second MQTT hardware gateway specially for Zigbee2MQTT. This is easier for debugging multiple AutoDiscover gateways.
    • NOTE: Do not make the discovery_topic name the same as the normal topic (deafult: zigbee2mqtt) as that confuses Domoticz.
  • Add Domoticz MQTT Client gateway (menu Setup - Hardware), see also wiki page MQTT
    • To use it add the build in hardware "MQTT Auto Discover Client Gateway with LAN interface"
    • Enter the MQTT broker details real IP address (do not use localhost or 127.0.0.1) and port (eg 1883)
    • Set Auto Discovery topic field, (default = homeassistant) or as set in HomeAssistant_discovery_topic in Zigbee2MQTT settings earlier.
    • Click on Add to add the MQTT Client Gateway configured to Zigbee2MQTT.
  • After adding/updating the MQTT Client Gateway for zigbee2MQTT the Zigbee devices will be automatically added in the Domoticz device list if discovered by Zigbee2MQTT. Domoticz devices will be created once data is received. So especially for battery operated devices it can take some time to have this data received. Sometimes it is possible to activate these sensors manually by pushing a button.

See the MQTT page for more information: MQTT Add Hardware

For questions about Domoticz MQTT Autodiscover go to the forum: https://domoticz.com/forum/viewforum.php?f=82


Add Zigbee2MQTT frontend to Domoticz Custom menu

Optional you can add the frontend User interface of Zigbee2MQTT as a custom menu in Domoticz.

Make a file Zigbee2MQTT.html in domoticz/www/templates

Contents 

<IFRAME SRC="http://IPAddress:8090/" height="800" width="100%"></IFRAME>

Rename IPAddress to the real IP address of your domoticz server. Also change the port of the frontend ifchanged in setup.

Restart Domoticz and you will have another Zigbee2MQTT entry in custom menu.

See also wiki page Custom Menu

Migrating from Plugin to AutoDiscover

1. Disable (not delete!) Plugin from Domoticz. Reboot system or restart Domoticz

2. Add Domoticz "MQTT Auto Discover Client Gateway with Lan interface" according instruction above and wait for all New devices to appear in Domoticz

3. Rename new devices to old names if used in scripts or modify scripts to use new names.

4. To keep history of the old devices use the function replace device (wiki https://www.domoticz.com/wiki/Managing_ ... ace_device )

NOTE: To see the devices of the disabled Zigbee2MQTT plugin during replacement action go to menu Setup - Settings and disable setting "Hide disabled hardware devices". Enable it again when you are done.

5. Delete the Plugin hardware, this will also remove all the corresponding old devices. Keeping these devices with same names will lead to dzVents errors!! So deleting is neccessary.


Alternative 2: Install the Domoticz Zigbee2MQTT Python plugin (not maintained!)

Warning: This method is not the prefereed method as the plugin is not maintained for 2 years (feb 2025)

Clone repository into your domoticz plugins folder 

cd domoticz/plugins
git clone https://github.com/stas-demydiuk/domoticz-zigbee2mqtt-plugin.git zigbee2mqtt

Restart Domoticz Go to “Hardware” page and add new item with type “Zigbee2MQTT” Set your MQTT server address and port to plugin settings

Once plugin receive any message from zigbee2mqtt server it will try to create appropriate device.

Debug MQTT

For General MQTT message debugging see wiki page MQTT

For Zigbee2MQTT specific check the Zigbee2MQTT FAQ pages

Thanks to

koenkk and all contributors for mqtt2zigbee project and stas–demydiuk for the Domoticz Pyton plugin. github: https://github.com/stas-demydiuk/domoticz-zigbee2mqtt-plugin forum discussion topic: http://www.domoticz.com/forum/viewtopic.php?f=65&t=24975 Original gadget-freakz zigbee article: https://gadget-freakz.com/diy-zigbee-gateway/

Retrieved from "https://wiki.domoticz.com/index.php?title=Zigbee2MQTT&oldid=18784"