How to Setup Zigbee2MQTT in Home Assistant

Zigbee2MQTT is one of the most popular ways to connect Zigbee devices to Home Assistant. Instead of relying on each manufacturer’s hub, it lets you bring everything together under one system, giving you more control, better compatibility, and fewer headaches.

What makes it especially powerful is how well it works with devices that other platforms sometimes struggle with, including newer or less common products. By running it with a Mosquitto broker, you can manage your smart home from a single dashboard without juggling multiple apps or bridges.

In this guide, I’ll walk you through setting up Zigbee2MQTT in Home Assistant step by step. Whether you’re new to Home Assistant or just getting started with Zigbee, this will help you build a more reliable and flexible smart home.

Step 1: Prepare Home Assistant and Zigbee Coordinator

_{Image Source: Home Assistant Community}

Setting up your hardware properly will give a solid foundation before you start installing Zigbee2MQTT. This setup will help your smart home devices communicate reliably after configuration.

Check Home Assistant version compatibility

Make sure your Home Assistant installation is current. Zigbee2MQTT performs best with recent Home Assistant versions that support MQTT integration. Good compatibility between these systems helps your Zigbee devices communicate smoothly with your Home Assistant dashboard.

Running an older version of Home Assistant? You should update to the latest stable release. Updates give you better performance and compatibility with Zigbee2MQTT. You can update easily through the Home Assistant Supervisor panel.

Choose your Zigbee adapter (USB or Ethernet)

Your Zigbee coordinator acts as the brain of your Zigbee network. It manages all devices and arranges communication to keep everything running smoothly. A better coordinator means a more reliable smart home network.

You can pick from three types of Zigbee coordinators:

• USB Zigbee coordinators: These connect directly to your Home Assistant device through a USB port. They’re the easiest option – just plug in and start.
• Ethernet/LAN Zigbee coordinators: These connect through Wi-Fi or Ethernet, so you can place them anywhere in your home.
• Hybrid PoE Zigbee coordinators: These are the most flexible. They work with USB, Wi-Fi, or Ethernet and can use USB or Power-over-Ethernet.

Beginners should start with USB coordinators like the Sonoff ZigBee 3.0 USB Dongle Plus. Your Home Assistant server’s location matters though. A basement location with poor wireless signals might need an Ethernet-based coordinator placed centrally.

Look for models based on zStack (Texas Instruments) or EmberZNet (Silicon Labs) when choosing your coordinator. These work best with Zigbee2MQTT and provide great compatibility and performance.

Ensure coordinator is connected and powered

Placing your coordinator correctly makes a big difference. Your coordinator needs to be:

1. Centrally located to reach all your devices effectively
2. Away from interference sources like Wi-Fi routers, microwave ovens, or Bluetooth devices
3. Properly powered – USB coordinators need reliable power

USB coordinators connected to your Home Assistant device might need a USB extension cable to reduce interference. This simple fix often solves device connection problems. Moving the Zigbee radio away from computer hardware helps avoid signal interference.

Ethernet-based coordinators need a static IP address on your network. This prevents connection issues from IP address changes by your router.

Users with virtualized Home Assistant installations on platforms like Proxmox might find Ethernet-based coordinators more reliable than USB devices passed through to virtual machines.

Your coordinator’s position affects your Zigbee mesh network’s quality. Good placement creates a strong foundation for adding more devices later.

Step 2: Install MQTT Broker in Home Assistant

Your Zigbee coordinator is ready, and now you’ll need to set up the system that connects your Zigbee devices to Home Assistant. MQTT (Message Queuing Telemetry Transport) acts as a messenger between your devices and smart home hub. Picture it as a postal service that delivers messages between your Zigbee devices and Home Assistant.

Install Mosquitto Broker from Add-on Store

Mosquitto works reliably with Home Assistant as the recommended MQTT broker for Zigbee2MQTT. The installation process is simple:

1. Open your Home Assistant dashboard
2. Go to Settings → Add-ons
3. Click on the Add-on Store button
4. Type “Mosquitto broker” in the search bar
5. Click on the Mosquitto broker add-on
6. Click the Install button and wait until it finishes

Mosquitto broker runs light on resources, which makes it ideal for systems with limited capacity. The installation will reveal additional configuration options.

Create MQTT user credentials

Your MQTT broker needs protection with username and password authentication:

1. You’ll create a dedicated MQTT user during Mosquitto setup
2. Head to Configuration → Users in your Home Assistant interface
3. Click the “Add User” button
4. Set up a username and password specifically for MQTT connections

The Mosquitto add-on configuration tab lets you configure users directly. Here’s what your configuration might look like:

{
  "logins": [
    {
      "username": "mqtt_user",
      "password": "secure_password"
    }
  ],
  "anonymous": false,
  "customize": {
    "active": false,
    "folder": "mosquitto"
  },
  "certfile": "fullchain.pem",
  "keyfile": "privkey.pem",
  "quiet_logs": true
}

Set “anonymous” to false to enhance security. This step prevents unauthorized access to your smart home data.

Enable Watchdog and auto-start options

Watchdog works like a guardian for your MQTT broker. It monitors and restarts the broker automatically if issues arise. The auto-start option makes sure your MQTT broker runs each time Home Assistant boots up.

Here’s how to enable these reliability features:

1. Find the Configuration tab on the Mosquitto broker add-on page
2. Save your user configuration and return to the Info tab
3. Switch on the Watchdog option
4. Turn on the Start on boot option (sometimes called “Auto-start”)
5. Hit Start to launch the broker

These settings will keep your smart home running even if the MQTT service hits a snag. Without Watchdog, your devices might stop responding if the MQTT broker fails.

Your MQTT broker stands ready for action after completing these steps. The broker handles all communication between your Zigbee devices and Home Assistant. A properly configured MQTT broker lays the groundwork since Zigbee2MQTT needs it to work.

The next section covers adding the Zigbee2MQTT add-on and connecting it to this MQTT broker. This setup allows your Zigbee devices to blend naturally with Home Assistant.

Step 3: Add and Configure Zigbee2MQTT

Your MQTT broker runs smoothly now. Let’s install the Zigbee2MQTT add-on. This add-on works as a translator between your smart gadgets and Home Assistant hub.

Add Zigbee2MQTT repository

Home Assistant needs to know where to find Zigbee2MQTT:

1. Navigate to Settings → Add-ons in your Home Assistant dashboard
2. Click the Add-on Store button in the bottom right corner
3. Click the three dots (⋮) in the top right corner
4. Choose Repositories
5. Add this address: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
6. Click Add and then Close

Refresh your browser page. New options should appear in your add-on store.

Install the Zigbee2MQTT add-on

The repository offers two options:

• Zigbee2MQTT – A stable version perfect for most users
• Zigbee2MQTT Edge – A beta version with newest features but less stability

New users should pick the regular Zigbee2MQTT option:

1. Select Zigbee2MQTT (not the Edge version)
2. Click the Install button
3. The installation takes several minutes, so be patient

Hold off on starting the add-on – setup comes first!

Configure MQTT settings (server, user, password)

Now connect Zigbee2MQTT to your MQTT broker:

1. Head to the Configuration tab after installation
2. Find the mqtt section
3. Update these values:
   • server: mqtt://core-mosquitto:1883
   • user: (your MQTT username)
   • password: (your MQTT password)
   • base_topic: zigbee2mqtt (usually pre-configured)

These settings enable communication between Zigbee2MQTT and your MQTT broker.

Set serial port and adapter type

Zigbee2MQTT needs to locate your Zigbee coordinator:

1. Locate the serial section in the configuration page
2. The port setting depends on your Zigbee adapter connection:
   • USB adapters show up under Settings → System → Hardware
   • Look for paths like /dev/ttyUSB0 or /dev/ttyACM0
   • Use the full path for better reliability: /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00
3. Pick the right adapter type:
   • Common choices include zstack or ember
   • Sonoff Zigbee 3.0 USB Dongle Plus needs zstack
4. Save your settings

Review all settings one last time. Click Start on the Info tab. A correct configuration means Zigbee2MQTT starts up ready for device pairing.

The logs help identify problems if Zigbee2MQTT doesn’t start. Wrong serial port details or adapter types cause most issues.

Step 4: Pair Zigbee Devices and Test

Let’s dive into the exciting part after setting up Zigbee2MQTT – connecting your smart devices to your home network! Here’s a simple guide that walks you through connecting and testing your Zigbee devices.

Enable ‘Permit Join’ in Zigbee2MQTT

Your Zigbee network needs permission to accept new devices:

1. Access the Zigbee2MQTT dashboard from your Home Assistant sidebar
2. Spot the “Permit join” button at the top right corner
3. A single click opens your network for 254 seconds (about 4 minutes)

The network stays open temporarily so new devices can connect. The mode switches off automatically when time runs out, and with good reason too. A dropdown arrow sits next to this button that helps you select which specific router should accept the new device – this comes in handy when devices struggle to connect.

Put Zigbee device in pairing mode

Each device pairs differently, so your device’s manual should be your guide. Most devices fit into two main groups:

• Devices without pairing buttons: A factory reset puts them in pairing mode. They’ll try to join your network automatically after reset.
• Devices with pairing buttons: You’ll usually need to hold down a button until you see a flashing light.

The quickest way to pair successfully is keeping the device close to your Zigbee coordinator. You can move it where you want it later.

Rename and organize devices

The logs will show a success message when your device connects. Then:

1. Head to the Zigbee2MQTT dashboard where your new device shows up
2. Select the device to see its settings
3. Replace the default name (usually a long technical code) with something meaningful like “Living Room Light”

This makes finding and using devices in automations much easier. You can also group devices by room or area to manage them better.

Test device status and link quality

After naming your paired device:

1. Make sure the device responds by testing its state (for lights or switches)
2. Check the “Link Quality” value in device details – numbers above 100 mean strong connections
3. Low link quality (under 50) might mean you need more Zigbee router devices or should move the device closer to a router

Devices might respond slowly or disconnect when link quality suffers. Smart plugs that work as routers can help your network reach further.

Step 5: Integrate with Home Assistant Dashboard

Your Zigbee devices deserve a spot on your Home Assistant dashboard! The dashboard serves as your command center to monitor and control all smart home devices.

Verify devices in MQTT integration

Your paired devices should show up in the MQTT integration automatically. The verification process is straightforward:

1. Go to Settings > Devices & services
2. Find and click on the MQTT integration
3. Look for your newly added Zigbee devices in the list

The Zigbee2MQTT dashboard helps confirm successful device pairing. New devices might need a minute to appear in the MQTT integration.

Add Zigbee devices to Lovelace UI

Lovelace UI acts as your main control screen in Home Assistant. The setup process takes just a few clicks:

1. Go to your main Overview dashboard
2. Click Edit in the top right corner (looks like a pencil)
3. Select + ADD CARD at the bottom
4. Choose your Zigbee device from the list
5. Click ADD TO LOVELACE UI
6. Select DONE to save changes

Each device appears as an interactive card on your dashboard. A light switch card enables quick control with a simple tap.

Customize dashboard cards

The dashboard becomes more useful with personalized cards:

1. While in Edit mode, click on any card
2. Select the gear icon to open settings
3. Change the card name to something friendly like “Kitchen Light”
4. Try different card types by clicking the three dots (…) and selecting “Pick a different card”

Card positions can be adjusted through position numbers or drag-and-drop in the dashboard editor. This organization helps group devices by room or function, making your smart home control more intuitive.

Conclusion

Getting Zigbee2MQTT to work with Home Assistant isn’t as hard as you might think. Five simple steps will take you from hardware prep to adding devices on your dashboard. Your smart home trip begins here.

This setup shines because it’s flexible and works with tons of devices. You’ll have access to over 3,500 devices from 430 vendors, making your smart home options endless. The best part? Zigbee2MQTT lets you skip expensive manufacturer hubs and gateways. You’ll save money and get more control over your setup.

The Zigbee coordinator’s position matters a lot. Place it in the middle of your home, away from things that might interfere with signals. This creates a strong base for your network. Clear device names and room-based organization will help you manage everything better as your collection grows.

You might run into some bumps along the way, usually with device pairing or connections. Check the link quality if things aren’t working right. Smart plugs can work as network routers to boost your signal strength. Moving devices closer or adding these extenders fixes most connection issues.

You’ve got all you need to build a solid, flexible smart home that isn’t tied to just one brand. The original setup needs some patience, but the control you’ll get is worth the wait. Start small with a few devices, get used to how everything works, and grow your smart home at your own pace.

FAQs