Zigbee2MQTT Installation for Smart Devices

Zigbee2MQTT bridges your Zigbee smart devices to an MQTT broker, eliminating proprietary hubs and giving you full local control. This guide covers coordinator hardware selection, Zigbee2MQTT installation on Linux, device pairing, and Home Assistant integration via MQTT.

Prerequisites

  • Linux server (Ubuntu 20.04+ or Debian 11+)
  • A running MQTT broker (Mosquitto recommended)
  • A Zigbee coordinator USB dongle
  • Node.js 18+ installed
  • sudo or root access

Install Mosquitto if not already present:

sudo apt update && sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto

Choosing a Zigbee Coordinator

The coordinator is the USB dongle that communicates with your Zigbee devices. Recommended options:

  • Sonoff Zigbee 3.0 USB Dongle Plus (CC2652P) - best value, widely supported
  • SMLIGHT SLZB-06 - network-based coordinator (no USB required)
  • ConBee II - popular alternative

Flash the coordinator with the latest firmware from the Zigbee2MQTT supported devices page before use.

Identify the coordinator's serial port:

# List USB devices
ls /dev/ttyUSB* /dev/ttyACM*

# Get more detail
dmesg | grep -E 'ttyUSB|ttyACM' | tail -10

Installing Zigbee2MQTT

# Install Node.js 18 if needed
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Create directory and user
sudo mkdir -p /opt/zigbee2mqtt
sudo adduser --system --no-create-home --group zigbee2mqtt
sudo usermod -aG dialout zigbee2mqtt  # access to serial port

# Clone the repository
sudo git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R zigbee2mqtt:zigbee2mqtt /opt/zigbee2mqtt

# Install dependencies
cd /opt/zigbee2mqtt
sudo -u zigbee2mqtt npm ci

Configuration

# Create the configuration file
sudo cp /opt/zigbee2mqtt/data/configuration.example.yaml /opt/zigbee2mqtt/data/configuration.yaml
sudo nano /opt/zigbee2mqtt/data/configuration.yaml

Minimal working configuration:

# /opt/zigbee2mqtt/data/configuration.yaml
homeassistant: true          # Enable Home Assistant discovery
permit_join: false           # Disable joining by default (enable when pairing)
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883
  # user: mqtt_user
  # password: mqtt_password
serial:
  port: /dev/ttyUSB0         # Your coordinator's serial port
  adapter: zstack            # Use 'deconz' for ConBee II
advanced:
  network_key: GENERATE      # Auto-generate on first run
  log_level: info
  pan_id: GENERATE
frontend:
  port: 8080                 # Web UI port

Running as a Systemd Service

# Create systemd service file
sudo tee /etc/systemd/system/zigbee2mqtt.service << 'EOF'
[Unit]
Description=Zigbee2MQTT
After=network.target mosquitto.service

[Service]
Type=simple
User=zigbee2mqtt
WorkingDirectory=/opt/zigbee2mqtt
ExecStart=/usr/bin/node index.js
StandardOutput=journal
StandardError=journal
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now zigbee2mqtt
sudo systemctl status zigbee2mqtt

Check logs:

journalctl -u zigbee2mqtt -f

Pairing Zigbee Devices

Enable joining temporarily via the web UI at http://your-server:8080 or via MQTT:

# Enable pairing for 254 seconds
mosquitto_pub -t "zigbee2mqtt/bridge/request/permit_join" \
  -m '{"value": true, "time": 254}'

# Put your Zigbee device into pairing mode (usually triple-click)
# Monitor the log to confirm pairing
journalctl -u zigbee2mqtt -f

# Disable pairing when done
mosquitto_pub -t "zigbee2mqtt/bridge/request/permit_join" -m '{"value": false}'

After pairing, rename the device via the web UI or configuration:

# In configuration.yaml, add device-specific settings
devices:
  '0x00158d0001234567':
    friendly_name: 'living_room_temp'

Home Assistant Integration

With homeassistant: true in your config, Zigbee2MQTT auto-discovers devices in Home Assistant via MQTT discovery.

In Home Assistant, go to Settings > Devices & Services > Add Integration > MQTT and connect to your broker.

Alternatively, add to configuration.yaml in Home Assistant:

mqtt:
  broker: 192.168.1.100
  port: 1883
  username: mqtt_user
  password: mqtt_password

Devices will appear automatically after pairing. Verify topics:

# Listen to all Zigbee2MQTT messages
mosquitto_sub -t "zigbee2mqtt/#" -v

OTA Firmware Updates

Zigbee2MQTT supports over-the-air firmware updates for many devices:

# Enable OTA updates in configuration.yaml
# ota:
#   update_check_interval: 1440  # Check daily
#   disable_automatic_update_check: false

# Check for updates via MQTT
mosquitto_pub -t "zigbee2mqtt/bridge/request/device/ota_update/check" \
  -m '{"id": "living_room_temp"}'

# Perform the update
mosquitto_pub -t "zigbee2mqtt/bridge/request/device/ota_update/update" \
  -m '{"id": "living_room_temp"}'

Monitor the update progress in logs:

journalctl -u zigbee2mqtt -f | grep -i ota

Docker Deployment

# docker-compose.yml
version: '3.8'
services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    container_name: zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Amsterdam
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    group_add:
      - dialout

docker compose up -d
docker compose logs -f zigbee2mqtt

Troubleshooting

Serial port not found or permission denied:

# Add your user to the dialout group
sudo usermod -aG dialout $USER
ls -la /dev/ttyUSB0  # Verify permissions

Device won't pair:

  • Ensure permit_join: true is active
  • Reset the device to factory settings (consult the Zigbee2MQTT supported devices list)
  • Move the coordinator closer to the device during pairing

MQTT connection refused:

# Test the broker
mosquitto_pub -h localhost -t test -m hello
mosquitto_sub -h localhost -t test

# Check Mosquitto is running
systemctl status mosquitto

Coordinator not recognized:

# Check if the adapter type matches your hardware
# In configuration.yaml, try adapter: auto
# Or specify: zstack (CC2652), deconz (ConBee), ezsp (HUSBZB-1)

Conclusion

Zigbee2MQTT gives you full local control over your Zigbee smart devices through a unified MQTT bridge, removing dependency on proprietary clouds. With Home Assistant discovery and OTA update support, it provides a production-grade foundation for a local-first smart home. Keep Zigbee2MQTT updated regularly as the supported device list and bug fixes ship frequently.