cba45556c7
- Refactored README.md, getting-started.md, quick-reference.md - Enhanced setup-homelab.sh with 9-step automated process - Created services-overview.md with all stacks - Added comprehensive documentation for 57 services in docs/service-docs/ - All services include: overview, configuration, resources, educational content - Coverage: Core, Infrastructure, Dashboards, Media, Media-Extended, Home Assistant, Productivity, Utilities, Monitoring, Development stacks - Educational focus with links to tutorials, videos, and guides
163 lines
4.2 KiB
Markdown
163 lines
4.2 KiB
Markdown
# Zigbee2MQTT - Zigbee Bridge
|
|
|
|
## Table of Contents
|
|
- [Overview](#overview)
|
|
- [What is Zigbee2MQTT?](#what-is-zigbee2mqtt)
|
|
- [Why Use Zigbee2MQTT?](#why-use-zigbee2mqtt)
|
|
- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
|
|
- [Official Resources](#official-resources)
|
|
- [Docker Configuration](#docker-configuration)
|
|
- [Setup](#setup)
|
|
|
|
## Overview
|
|
|
|
**Category:** Zigbee Gateway
|
|
**Docker Image:** [koenkk/zigbee2mqtt](https://hub.docker.com/r/koenkk/zigbee2mqtt)
|
|
**Default Stack:** `homeassistant.yml`
|
|
**Web UI:** `http://SERVER_IP:8080`
|
|
**Requires:** USB Zigbee coordinator
|
|
**Ports:** 8080
|
|
|
|
## What is Zigbee2MQTT?
|
|
|
|
Zigbee2MQTT is a bridge between Zigbee devices and MQTT. It allows you to use Zigbee devices with Home Assistant without proprietary hubs (Philips Hue bridge, IKEA gateway, etc.). You only need a $15 USB Zigbee coordinator stick.
|
|
|
|
### Key Features
|
|
- **2500+ Supported Devices:** Huge compatibility
|
|
- **No Cloud:** Local control
|
|
- **No Hubs Needed:** Just USB stick
|
|
- **OTA Updates:** Update device firmware
|
|
- **Groups:** Control multiple devices
|
|
- **Scenes:** Save device states
|
|
- **Touchlink:** Reset devices
|
|
- **Web UI:** Visual management
|
|
- **Free & Open Source:** No subscriptions
|
|
|
|
## Why Use Zigbee2MQTT?
|
|
|
|
1. **No Proprietary Hubs:** Save $50+ per brand
|
|
2. **Local Control:** No internet required
|
|
3. **Any Brand:** Mix Philips, IKEA, Aqara, etc.
|
|
4. **More Features:** Than manufacturer apps
|
|
5. **Device Updates:** OTA firmware updates
|
|
6. **Privacy:** No cloud reporting
|
|
7. **Open Source:** Community supported
|
|
|
|
## Configuration in AI-Homelab
|
|
|
|
```
|
|
/opt/stacks/homeassistant/zigbee2mqtt/
|
|
data/
|
|
configuration.yaml
|
|
database.db
|
|
devices.yaml
|
|
groups.yaml
|
|
```
|
|
|
|
### Zigbee Coordinators
|
|
|
|
**Recommended:**
|
|
- **Sonoff Zigbee 3.0 USB Plus** ($20) - Works great
|
|
- **ConBee II** ($40) - Premium option
|
|
- **CC2652P** ($25) - Powerful, longer range
|
|
|
|
**Not Recommended:**
|
|
- CC2531 - Old, limited, unreliable
|
|
|
|
## Official Resources
|
|
|
|
- **Website:** https://www.zigbee2mqtt.io
|
|
- **Supported Devices:** https://www.zigbee2mqtt.io/supported-devices
|
|
- **Documentation:** https://www.zigbee2mqtt.io/guide
|
|
|
|
## Docker Configuration
|
|
|
|
```yaml
|
|
zigbee2mqtt:
|
|
image: koenkk/zigbee2mqtt:latest
|
|
container_name: zigbee2mqtt
|
|
restart: unless-stopped
|
|
networks:
|
|
- traefik-network
|
|
ports:
|
|
- "8080:8080"
|
|
environment:
|
|
- TZ=America/New_York
|
|
volumes:
|
|
- /opt/stacks/homeassistant/zigbee2mqtt/data:/app/data
|
|
- /run/udev:/run/udev:ro
|
|
devices:
|
|
- /dev/ttyUSB0:/dev/ttyUSB0
|
|
```
|
|
|
|
## Setup
|
|
|
|
1. **Find USB Device:**
|
|
```bash
|
|
ls -la /dev/ttyUSB*
|
|
# or
|
|
ls -la /dev/ttyACM*
|
|
```
|
|
|
|
2. **Configure:**
|
|
Edit `/opt/stacks/homeassistant/zigbee2mqtt/data/configuration.yaml`:
|
|
```yaml
|
|
homeassistant: true
|
|
permit_join: false
|
|
mqtt:
|
|
base_topic: zigbee2mqtt
|
|
server: mqtt://mosquitto:1883
|
|
user: zigbee2mqtt
|
|
password: your_password
|
|
serial:
|
|
port: /dev/ttyUSB0
|
|
frontend:
|
|
port: 8080
|
|
advanced:
|
|
network_key: GENERATE # Auto-generates on first start
|
|
```
|
|
|
|
3. **Start Container:**
|
|
```bash
|
|
docker compose up -d zigbee2mqtt
|
|
```
|
|
|
|
4. **Access Web UI:** `http://SERVER_IP:8080`
|
|
|
|
5. **Pair Devices:**
|
|
- In UI: Enable "Permit Join" (top right)
|
|
- Or in config: `permit_join: true` and restart
|
|
- Put device in pairing mode (usually hold button)
|
|
- Device appears in Zigbee2MQTT
|
|
- Automatically appears in Home Assistant
|
|
- Disable permit join when done!
|
|
|
|
## Summary
|
|
|
|
Zigbee2MQTT bridges Zigbee devices to Home Assistant via MQTT, enabling local control of 2500+ devices from any manufacturer without proprietary hubs.
|
|
|
|
**Perfect for:**
|
|
- Zigbee smart home devices
|
|
- Avoiding cloud dependencies
|
|
- Multi-brand setups
|
|
- Local control
|
|
- Cost savings (no hubs)
|
|
|
|
**Key Points:**
|
|
- Requires USB Zigbee coordinator
|
|
- 2500+ supported devices
|
|
- No manufacturer hubs needed
|
|
- Works with MQTT and Home Assistant
|
|
- OTA firmware updates
|
|
- Web UI for management
|
|
- Keep permit_join disabled when not pairing
|
|
|
|
**Remember:**
|
|
- Plug coordinator away from USB 3.0 ports (interference)
|
|
- Use USB extension cable if needed
|
|
- Disable permit_join after pairing
|
|
- Keep firmware updated
|
|
- Routers extend network (powered devices)
|
|
|
|
Zigbee2MQTT liberates your Zigbee devices from proprietary hubs!
|