HomeAssistant

How to Install Zigbee2MQTT on Home Assistant: Step-by-Step Guide

My 6th video on this channel was about how to install Zigbee2MQTT on HomeAssistant and I released in August of 2023. Just this week (1/7/25) there was an update to Zigbee2MQTT 2.0.0 that contained a breaking change. I wanted to update my write-up but noticed I never made one! Better late than never.

Chuck

07 Jan 2025 • 4 min read

Original Video: https://youtu.be/MFfC28WkYfE

2.0.0 Breaking Change:

If you've previously followed the above video, the only change is in the "Serial" section of the Zigbee2MQTT configuration. You need to add "adapter: zstack" after the port.

For my Sonoff ZB Dongle Folks use : "zstack"

For anyone using the HomeAssistant SkyConnect use: "ember"

Just add the following to the serial section of your Zigbee2MQTT Serial Settings under the Configuration Tab.

adapter: zstack

Step by Step

In this tutorial, I'll walk you through setting up Zigbee2MQTT on Home Assistant, including a list of recommended devices and optional tools for a smoother experience.

Step 1: Install the Mosquitto Broker Add-on

Navigate to Settings → Add-ons → Add-on Store in Home Assistant.
Search for the Mosquitto broker add-on, install it, and start it.
I recommend enabling the "Start on Boot," "Watchdog," and "Auto-Update" toggles.

Step 2: Add Zigbee2MQTT Repository

In the Add-on Store, click the 3-dot menu in the top-right corner and select "Repositories, then enter the repository URL and click "Add".

https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Click Add.

It's easier to click this link to populate it.

Click Add.

Step 3: Refresh the Add-on Store

Press the Check for Updates button in the Add-on Store.
If you don’t see the Zigbee2MQTT add-on, press Ctrl+F5 to refresh your browser cache.

Step 4: Install Zigbee2MQTT

Find Zigbee2MQTT in the Add-on Store and click Install.

Step 5: Connect the Zigbee Dongle

Connect your SONOFF Zigbee Dongle to the USB Extender and then plug the USB extender into your Home Assistant host.

Step 6: Identify the USB Port

Navigate to Settings → System → Hardware. Then click on "All Hardware".

Scroll through the list until you find a tty entry corresponding to your device (e.g., ttyUSB1).
Click on it to expand and copy the Device Path or ID.
1. I recommend using the ID for better reliability across USB port changes.

Step 7: Configure Zigbee2MQTT

Go back to Settings → Add-ons and open Zigbee2MQTT.
Navigate to the Configuration tab.
In the serial section, replace the port with your copied Device ID, like this:

port: [PASTE DEVICE ID HERE]
adapter: zstack

so, for me it looks like this (don't mind the ">-" it might automatically add that) :

port: >-
  /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_6696eb0d6499ec11b0aaffc844d80d13-if00-port0
adapter: zstack

💡

Note: Ensure that adapter: zstack is set, as it's required for Zigbee2MQTT version 2.0.0+.

Click Save.

Step 8: Start Zigbee2MQTT

Start the Zigbee2MQTT add-on and ensure that the Mosquitto broker is also running.
If you're running MQTT on a different host, you’ll need to configure the MQTT section:

mqtt:
  base_topic: zigbee2mqtt
  user: [YOUR_ADDON_USER]
  password: [YOUR_ADDON_USER_PASSWORD]
  server: mqtt://core-mosquitto:1883

Step 9: Verify Logs

Check the Zigbee2MQTT logs for any errors. If everything looks good, proceed.

Step 10: Open Zigbee2MQTT Web-UI

Click Open Web-UI to access the Zigbee2MQTT interface.

Step 11: Change Zigbee Channel (Optional)

To minimize interference with WiFi, you might want to change the Zigbee channel. For more detailed instructions, check the video at the 4:28 mark or refer to my other blog post.