Table of Contents

Overview

Zigbee2MQTT is a powerful bridge that allows you to use your Zigbee devices without the vendor's bridge or gateway. It bridges events and allows you to control your Zigbee devices via MQTT, making them compatible with any smart home solution that supports MQTT, including Home Assistant, OpenHAB, and Node-RED.

What is Zigbee2MQTT?

Zigbee2MQTT is an open-source project that:

  • Eliminates vendor lock-in by removing the need for proprietary hubs
  • Provides local control without cloud dependencies
  • Supports 2000+ devices from various manufacturers
  • Enables advanced features not available in vendor apps
  • Offers extensive customization through configuration files
  • Provides detailed logging for troubleshooting

Key Benefits

  • Cost-effective: Single adapter supports multiple device brands
  • Privacy-focused: All communication stays local
  • Flexible: Works with any MQTT-compatible automation platform
  • Feature-rich: Exposes all device capabilities
  • Community-driven: Extensive device support and documentation

Architecture Overview

graph TB
    subgraph "Zigbee Network"
        ZC[Zigbee Coordinator<br/>USB Adapter]
        ZR1[Zigbee Router<br/>Mains Powered Device]
        ZR2[Zigbee Router<br/>Smart Plug]
        ZED1[Zigbee End Device<br/>Battery Sensor]
        ZED2[Zigbee End Device<br/>Remote Control]
        ZED3[Zigbee End Device<br/>Motion Sensor]
    end
    
    subgraph "Host System"
        Z2M[Zigbee2MQTT<br/>Application]
        MQTT[MQTT Broker<br/>Mosquitto]
        CONFIG[Configuration<br/>Files]
        LOG[Log Files]
    end
    
    subgraph "Home Automation"
        HA[Home Assistant]
        NODERED[Node-RED]
        OPENHAB[OpenHAB]
    end
    
    subgraph "Monitoring & Management"
        WEB[Web Interface]
        API[REST API]
        FRONTEND[Frontend UI]
    end
    
    ZC --> Z2M
    ZR1 --> ZC
    ZR2 --> ZC
    ZED1 --> ZR1
    ZED2 --> ZR2
    ZED3 --> ZR1
    
    Z2M --> MQTT
    Z2M --> CONFIG
    Z2M --> LOG
    Z2M --> WEB
    Z2M --> API
    
    MQTT --> HA
    MQTT --> NODERED
    MQTT --> OPENHAB
    
    WEB --> FRONTEND
    
    classDef zigbee fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef system fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef automation fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef management fill:#fff3e0,stroke:#e65100,stroke-width:2px
    
    class ZC,ZR1,ZR2,ZED1,ZED2,ZED3 zigbee
    class Z2M,MQTT,CONFIG,LOG system
    class HA,NODERED,OPENHAB automation
    class WEB,API,FRONTEND management

Prerequisites

Hardware Requirements

  • Zigbee USB Adapter (recommended: Texas Instruments CC2652 based)
  • Host System with USB port (Raspberry Pi, x86 server, or desktop)
  • MQTT Broker (Mosquitto recommended)
  • Minimum 1GB RAM for stable operation
  • At least 8GB storage for logs and backups

Software Prerequisites

  • Linux, Windows, or macOS host system
  • Docker (recommended) or Node.js 18+ for native installation
  • MQTT broker running and accessible
  • Network connectivity between Zigbee2MQTT and MQTT broker

Documentation Structure

This comprehensive guide is organized into focused sections for easy navigation:

📦 Installation

Complete installation guide covering all deployment methods:

  • Docker Installation with Docker Compose examples
  • Native Installation for direct system deployment
  • Home Assistant Add-on for HASSIO users
  • Post-installation verification and testing

⚙️ Configuration

Comprehensive configuration guide:

  • Basic configuration for quick setup
  • Advanced settings for optimization
  • Security configuration and best practices
  • Network optimization for large deployments
  • Device-specific configurations

🔧 Device Management

Complete device lifecycle management:

  • Device pairing procedures and troubleshooting
  • Device configuration and customization
  • Groups and scenes setup and management
  • Device removal and network cleanup
  • Bulk operations for large deployments

📊 Monitoring and Maintenance

System monitoring and maintenance procedures:

  • Logging configuration and analysis
  • Backup strategies and automation
  • Health monitoring and alerting
  • Performance optimization
  • Maintenance schedules and procedures

🔍 Troubleshooting

Common issues and diagnostic procedures:

  • Connection problems and network issues
  • Device pairing failures and solutions
  • Performance issues and optimization
  • Log analysis and error interpretation
  • Recovery procedures for system failures

🏠 Home Assistant Integration

Deep integration with Home Assistant:

  • MQTT discovery configuration
  • Entity customization and naming
  • Automation examples and best practices
  • Dashboard integration and visualization
  • Advanced integrations with other platforms

🚀 Advanced Topics

Advanced configuration and optimization:

  • Security hardening and access control
  • Performance tuning for large networks
  • Custom device handlers and modifications
  • Network topology optimization
  • High availability setup and clustering

Quick Start

If you're new to Zigbee2MQTT, follow this recommended path:

  1. Start with Installation to get Zigbee2MQTT running
  2. Configure basics using the Configuration guide
  3. Pair your first device following Device Management
  4. Set up monitoring with Monitoring and Maintenance
  5. Integrate with Home Assistant using Integration guide

Community and Support

Version Information

This guide is maintained for:

  • Zigbee2MQTT: Version 1.35.x and newer
  • Node.js: Version 18.x and newer
  • MQTT Brokers: Mosquitto 2.0+, Eclipse Mosquitto, EMQX
  • Home Assistant: 2023.1 and newer

Note: This documentation is continuously updated to reflect the latest features and best practices. Always refer to the official Zigbee2MQTT documentation for the most current information.

Edit this page