# Zigbee2MQTT Stack

> Zigbee2MQTT with MQTT broker for Zigbee device control.

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: zigbee2mqtt, mosquitto
- Tags: zigbee, mqtt, iot, smart-home, z2m
- Source: https://docker.recipes/homelab/zigbee2mqtt-stack

## 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.

## 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

## Use cases

- Building a vendor-agnostic smart home with mixed Zigbee device brands
- Integrating legacy Zigbee devices with modern home automation platforms
- Creating a privacy-focused IoT network without cloud dependencies
- Developing commercial IoT solutions requiring reliable Zigbee connectivity
- Migrating from proprietary hubs like SmartThings or Wink to open solutions
- Prototyping industrial automation systems with wireless sensor networks
- Educational 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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  mosquitto_data:
  z2m_data:

networks:
  zigbee-network:
    driver: bridge
```

## .env

```bash
# Zigbee2MQTT
Z2M_PORT=8080
MQTT_PORT=1883
ZIGBEE_DEVICE=/dev/ttyUSB0
TZ=UTC
```

## Usage notes

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

## 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

