How to Set Up and Use Zigbee2MQTT

What Is Zigbee2MQTT

Zigbee2MQTT is an open-source Zigbee gateway that bridges Zigbee devices to Home Assistant via MQTT. Unlike ZHA, which runs inside Home Assistant, Zigbee2MQTT runs as a separate process (typically a Home Assistant add-on) and communicates through an MQTT broker. This architecture gives you a dedicated web frontend for Zigbee management, deeper configuration options, and independence from Home Assistant’s update cycle.

Zigbee2MQTT is recommended for advanced users who need fine-grained control over device configuration, custom converter support, or who prefer to manage Zigbee separately from Home Assistant.

Zigbee2MQTT supports a wide range of USB coordinators including the SONOFF ZBDongle-P (CC2652P), ZBDongle-E (EFR32MG21), ConBee II/III, and the Home Assistant SkyConnect/Connect ZBT-1/ZBT-2.

Initial Setup

Prerequisites

• A supported USB Zigbee coordinator connected to your Home Assistant host (use a USB extension cable of at least 1 meter to avoid USB 3.0 interference).
• An MQTT broker. If you do not already have one, install the Mosquitto MQTT Broker add-on first — see the Mosquitto installation guide .
• Home Assistant with the MQTT integration configured and connected to the broker.

Install Zigbee2MQTT Add-on

1. Go to Settings → Add-ons → Add-on Store.
2. Open the three-dot menu, select Repositories, and add the Zigbee2MQTT repository if not already present: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
3. Search for Zigbee2MQTT and select Install.
4. After installation, enable Show in sidebar, Start on boot, and Watchdog.

Configure the Add-on

Before starting Zigbee2MQTT, configure the essential settings:

1. Go to the add-on’s Configuration tab.
2. Set the serial port to your coordinator. The add-on will list detected USB devices. Select the one matching your coordinator (e.g., /dev/ttyUSB0 or /dev/ttyACM0).
3. Configure the MQTT connection:

mqtt:
  server: mqtt://core-mosquitto:1883
  user: your_mqtt_user
  password: your_mqtt_password

1. Set the Zigbee channel. Use channel 15, 20, or 25 for minimal WiFi overlap. Add this under the advanced section if not already present:

advanced:
  channel: 15

1. Select Save and then Start.

Verify the Installation

1. Open Zigbee2MQTT from the sidebar.
2. The dashboard should show the coordinator as online with its firmware version.
3. Check the Log tab for any errors. A healthy startup shows “Zigbee2MQTT started” with the coordinator details.

Pairing Devices

Enable Permit Join

1. In the Zigbee2MQTT frontend, toggle Permit Join in the top-right corner. This opens the network for new devices for a configurable duration (default 254 seconds).
2. Put your Zigbee device into pairing mode according to its manual.
3. The device should appear in the device list within 30 seconds. Zigbee2MQTT identifies the device model, manufacturer, and supported features automatically.

Tips for Reliable Pairing

• Pair mains-powered routers first to build out the mesh before adding battery-powered end devices.
• Pair at the installed location when possible. If pairing fails there, pair near the coordinator and wait 24–48 hours for the mesh to settle.
• Check the supported devices list at zigbee2mqtt.io/supported-devices before purchasing or pairing. If a device is not on the list, it may still work but could require a custom converter.

Rename Devices

After pairing, rename devices immediately through the Zigbee2MQTT frontend:

1. Select the device from the device list.
2. Select the Settings tab (gear icon).
3. Change the Friendly Name to something descriptive (e.g., kitchen_motion_sensor).
4. The MQTT topic and Home Assistant entity update automatically.

Day-to-Day Operations

Network Map

Zigbee2MQTT provides a network visualization similar to ZHA but with more detail.

1. In the Zigbee2MQTT frontend, select the Map tab.
2. The map shows:
   • Solid lines: Direct parent-child relationships.
   • Dashed lines: Known neighbor relationships.
   • Green nodes: Router devices (mains-powered).
   • Blue nodes: End devices (battery-powered).
   • Link quality (LQI) values displayed on connection lines — higher numbers indicate stronger connections.
3. Use the map to identify weak links. An LQI below 50 on a connection suggests the device is at the edge of range.

Groups

Zigbee groups in Zigbee2MQTT work the same way as in ZHA — commands are sent at the Zigbee protocol level for instant, synchronized control.

How to create a group:

1. In the Zigbee2MQTT frontend, go to the Groups tab.
2. Select Add Group and name it (e.g., living_room_lights).
3. Open the group and add member devices.
4. A corresponding group entity appears in Home Assistant via MQTT discovery.

Advanced group configuration can be done in the Zigbee2MQTT configuration.yaml file:

groups:
  '1':
    friendly_name: living_room_lights
    devices:
      - '0x00158d0001234567/1'
      - '0x00158d0007654321/1'

Bindings

Bindings in Zigbee2MQTT are configured through the frontend or the configuration.yaml.

How to create a binding via the frontend:

1. Select the source device (e.g., a remote or button).
2. Go to the Bind tab.
3. Select the target device or group and the cluster to bind (e.g., “genOnOff” for on/off control, “genLevelCtrl” for dimming).
4. Select Bind. The devices now communicate directly without going through Home Assistant or the MQTT broker.

Device-Specific Configuration

One of Zigbee2MQTT’s strengths is per-device configuration. Many devices expose settings that are not accessible through ZHA.

1. Select a device and go to the Settings (specific) tab.
2. Available options vary by device but can include:
   • Motion sensor sensitivity and timeout.
   • LED indicator on/off.
   • Power-on behavior (restore last state, always on, always off).
   • Reporting intervals for sensors.
3. Changes are sent directly to the device over Zigbee.

OTA Firmware Updates

Zigbee2MQTT maintains its own firmware index and supports OTA updates for a wide range of manufacturers.

1. In the Zigbee2MQTT frontend, go to the OTA tab.
2. Select Check for Updates. Devices with available updates will be listed.
3. Select Update next to the device. OTA updates can take 30–60 minutes. Do not power cycle the device during the update.

To enable automatic update checks, add to configuration.yaml:

ota:
  update_check_interval: 1440  # Check every 24 hours (in minutes)
  disable_automatic_update_check: false

External Converters

For devices not yet in the Zigbee2MQTT supported devices list, you can write or install external converters — JavaScript files that tell Zigbee2MQTT how to interpret the device’s Zigbee clusters.

1. Find or write a converter file (.js). The Zigbee2MQTT community frequently shares converters for new devices on GitHub and the Home Assistant forums.
2. Place the file in the Zigbee2MQTT data directory (typically /config/zigbee2mqtt/ when using the HA add-on).
3. Reference it in configuration.yaml:

external_converters:
  - my_custom_device.js

1. Restart Zigbee2MQTT. The device should now be recognized.

Coordinator Firmware Updates

Keep the coordinator firmware updated for improved stability and device compatibility.

• SONOFF ZBDongle-P/E: Flash using the manufacturer’s tool or via the Zigbee2MQTT add-on’s built-in flasher (if supported by your version).
• ConBee II/III: Use the deCONZ firmware update tool.
• SkyConnect / Connect ZBT-1 / ZBT-2: Update through Settings → System → Hardware → Firmware in Home Assistant.

After updating coordinator firmware, restart Zigbee2MQTT. Devices do not need to be re-paired — the network keys are preserved.

Backup and Migration

Zigbee2MQTT stores its configuration and network data in the data directory. A standard Home Assistant backup includes this directory when using the add-on.

Key files to preserve:

• configuration.yaml — Your Zigbee2MQTT configuration.
• coordinator_backup.json — Automatically generated network backup including the network key, PAN ID, and extended PAN ID.
• database.db — Device database with pairing data, names, and settings.

To migrate to a new coordinator:

1. Stop Zigbee2MQTT.
2. Replace the USB coordinator.
3. Update the serial port in the add-on configuration if it changed.
4. Start Zigbee2MQTT. It will detect the new coordinator and restore the network from coordinator_backup.json.
5. Allow 10–30 minutes for all devices to re-associate with the new coordinator.