Skip to content

Zigbee2MQTT Setup

What You'll Learn

How to set up Zigbee2MQTT in Docker alongside Home Assistant for reliable, local Zigbee device management without cloud dependencies.

Why Zigbee2MQTT?

Zigbee2MQTT bridges your Zigbee devices to MQTT, giving you full local control without proprietary hubs. Combined with Home Assistant, it provides a powerful and reliable smart home foundation.

Benefits over alternatives:

  • No cloud dependency — everything runs locally
  • Supports 2000+ devices from hundreds of manufacturers
  • Full control over your Zigbee network
  • MQTT gives you flexibility to integrate with anything

Prerequisites

  • A Zigbee coordinator (e.g., SONOFF Zigbee 3.0 USB Dongle Plus)
  • Docker and Docker Compose
  • An MQTT broker (Mosquitto)
  • Home Assistant instance

Docker Compose Stack

docker-compose.yml
services:
  mqtt:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    restart: unless-stopped

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    depends_on:
      - mqtt
    ports:
      - "8081:8080"
    volumes:
      - ./zigbee2mqtt/data:/app/data
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # Your Zigbee coordinator
    environment:
      - TZ=America/Chicago
    restart: unless-stopped

Finding Your Coordinator

Use ls -la /dev/serial/by-id/ to find the stable device path for your Zigbee coordinator. Using /dev/serial/by-id/... is more reliable than /dev/ttyUSB0 which can change on reboot.

Configuration

zigbee2mqtt/data/configuration.yaml
homeassistant: true
permit_join: false  # Only enable when pairing new devices
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mqtt:1883
serial:
  port: /dev/ttyUSB0
frontend:
  port: 8080
advanced:
  network_key: GENERATE  # Will auto-generate on first run
  log_level: info

Home Assistant Integration

Once Zigbee2MQTT is running and connected to MQTT, add the MQTT integration in Home Assistant:

  1. Go to Settings → Devices & Services → Add Integration
  2. Search for MQTT
  3. Enter your broker details (mosquitto hostname if on same Docker network)
  4. Devices paired in Zigbee2MQTT will auto-discover in Home Assistant

Pairing Devices

# Temporarily enable pairing (or use the Z2M frontend)
mosquitto_pub -h localhost -t zigbee2mqtt/bridge/request/permit_join \
  -m '{"value": true, "time": 120}'

Then put your device in pairing mode. Check the Zigbee2MQTT frontend at http://<host>:8081 to see it appear.

Troubleshooting

Common Issues

  • Device not pairing: Make sure permit_join is enabled and the device is in pairing mode. Try moving closer to the coordinator.
  • Coordinator not found: Check the device path with ls -la /dev/serial/by-id/. Ensure the Docker container has access to the device.
  • MQTT connection refused: Verify Mosquitto is running and the hostname/port are correct.

More Z2M tips and device-specific notes will be added over time.