Zigbee2MQTT Stack

intermediate

Zigbee2MQTT with MQTT broker for Zigbee device control.

Overview

Zigbee2MQTT is an open-source bridge that enables communication between Zigbee devices and MQTT networks without requiring proprietary vendor hubs. Originally created by Koen Kanters in 2017, this powerful tool translates Zigbee protocols into MQTT messages, allowing thousands of different Zigbee devices from various manufacturers to work together in a unified ecosystem. The project supports over 2000 devices and continues to expand, making it the most comprehensive Zigbee integration solution available. This stack combines Zigbee2MQTT with Eclipse Mosquitto MQTT broker to create a complete smart home automation backbone. Zigbee2MQTT handles the radio communication with sensors, switches, and smart devices using a USB Zigbee coordinator, while Mosquitto manages the MQTT message routing between devices and automation platforms like Home Assistant, Node-RED, or custom applications. The pairing eliminates vendor lock-in and creates a local, privacy-focused smart home network. Homelab enthusiasts, smart home developers, and privacy-conscious users will find this stack invaluable for building robust IoT networks. The combination offers professional-grade device management capabilities typically found in expensive commercial systems, while maintaining complete local control over device data and automation logic. Advanced users appreciate the extensive configuration options and real-time device state monitoring through the web interface.

Key Features

Web-based device pairing and management interface with real-time network topology visualization
Support for over 2000 Zigbee devices from 300+ manufacturers without vendor hubs
Advanced Zigbee mesh network optimization with automatic routing and healing
MQTT topic structure customization for seamless home automation platform integration
Device-specific configuration options including reporting intervals and sensitivity settings
OTA firmware update management for supported Zigbee devices
Network map visualization showing signal strength and routing paths
Comprehensive device binding and group management for complex automation scenarios

Common Use Cases

1Building a vendor-agnostic smart home with mixed Zigbee device brands
2Integrating legacy Zigbee devices with modern home automation platforms
3Creating a privacy-focused IoT network without cloud dependencies
4Developing commercial IoT solutions requiring reliable Zigbee connectivity
5Migrating from proprietary hubs like SmartThings or Wink to open solutions
6Prototyping industrial automation systems with wireless sensor networks
7Educational projects teaching IoT protocols and MQTT messaging patterns

Prerequisites

Compatible USB Zigbee coordinator dongle (CC2531, CC2652, ConBee II, or similar)
Docker host with USB device passthrough capabilities and privileged container support
Minimum 512MB RAM and 2GB storage space for device database and logs
Basic understanding of Zigbee networking concepts and MQTT message structure
Network access to MQTT port 1883 from automation platforms and client applications
Ability to identify correct USB device path for Zigbee coordinator mapping

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  mosquitto: 
3    image: eclipse-mosquitto:latest
4    container_name: mosquitto
5    restart: unless-stopped
6    ports: 
7      - "${MQTT_PORT:-1883}:1883"
8      - "9001:9001"
9    volumes: 
10      - mosquitto_data:/mosquitto/data
11      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
12    networks: 
13      - zigbee-network
14
15  zigbee2mqtt: 
16    image: koenkk/zigbee2mqtt:latest
17    container_name: zigbee2mqtt
18    restart: unless-stopped
19    ports: 
20      - "${Z2M_PORT:-8080}:8080"
21    volumes: 
22      - z2m_data:/app/data
23      - /run/udev:/run/udev:ro
24    devices: 
25      - ${ZIGBEE_DEVICE:-/dev/ttyUSB0}:/dev/ttyACM0
26    environment: 
27      - TZ=${TZ:-UTC}
28    depends_on: 
29      - mosquitto
30    networks: 
31      - zigbee-network
32
33volumes: 
34  mosquitto_data: 
35  z2m_data: 
36
37networks: 
38  zigbee-network: 
39    driver: bridge

.env Template

.env

1# Zigbee2MQTT
2Z2M_PORT=8080
3MQTT_PORT=1883
4ZIGBEE_DEVICE=/dev/ttyUSB0
5TZ=UTC

Usage Notes

1Zigbee2MQTT at http://localhost:8080
2Set correct Zigbee device path
3Create mosquitto.conf first
4Pair devices via frontend

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

mosquitto

mosquitto:
  image: eclipse-mosquitto:latest
  container_name: mosquitto
  restart: unless-stopped
  ports:
    - ${MQTT_PORT:-1883}:1883
    - "9001:9001"
  volumes:
    - mosquitto_data:/mosquitto/data
    - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
  networks:
    - zigbee-network

zigbee2mqtt

zigbee2mqtt:
  image: koenkk/zigbee2mqtt:latest
  container_name: zigbee2mqtt
  restart: unless-stopped
  ports:
    - ${Z2M_PORT:-8080}:8080
  volumes:
    - z2m_data:/app/data
    - /run/udev:/run/udev:ro
  devices:
    - ${ZIGBEE_DEVICE:-/dev/ttyUSB0}:/dev/ttyACM0
  environment:
    - TZ=${TZ:-UTC}
  depends_on:
    - mosquitto
  networks:
    - zigbee-network

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mosquitto:
5    image: eclipse-mosquitto:latest
6    container_name: mosquitto
7    restart: unless-stopped
8    ports:
9      - "${MQTT_PORT:-1883}:1883"
10      - "9001:9001"
11    volumes:
12      - mosquitto_data:/mosquitto/data
13      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
14    networks:
15      - zigbee-network
16
17  zigbee2mqtt:
18    image: koenkk/zigbee2mqtt:latest
19    container_name: zigbee2mqtt
20    restart: unless-stopped
21    ports:
22      - "${Z2M_PORT:-8080}:8080"
23    volumes:
24      - z2m_data:/app/data
25      - /run/udev:/run/udev:ro
26    devices:
27      - ${ZIGBEE_DEVICE:-/dev/ttyUSB0}:/dev/ttyACM0
28    environment:
29      - TZ=${TZ:-UTC}
30    depends_on:
31      - mosquitto
32    networks:
33      - zigbee-network
34
35volumes:
36  mosquitto_data:
37  z2m_data:
38
39networks:
40  zigbee-network:
41    driver: bridge
42EOF
43
44# 2. Create the .env file
45cat > .env << 'EOF'
46# Zigbee2MQTT
47Z2M_PORT=8080
48MQTT_PORT=1883
49ZIGBEE_DEVICE=/dev/ttyUSB0
50TZ=UTC
51EOF
52
53# 3. Start the services
54docker compose up -d
55
56# 4. View logs
57docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/zigbee2mqtt-stack/run | bash

Troubleshooting

Permission denied accessing /dev/ttyUSB0: Add user to dialout group and verify device permissions
Zigbee2MQTT fails to start with 'Adapter not found': Check USB device mapping and ensure coordinator firmware is compatible
Devices fail to pair or interview: Reset device according to manufacturer instructions and ensure coordinator has sufficient power
MQTT connection refused errors: Verify mosquitto.conf allows anonymous connections or configure proper authentication
Web interface shows 'Backend not available': Check that zigbee2mqtt container can reach mosquitto on port 1883
Device commands not working: Verify MQTT topic structure matches your automation platform expectations and device is online

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

zigbee2mqttmosquitto

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download