zigbee2mqtt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zigbee2MQTT

Zigbee2MQTT bridges Zigbee devices to MQTT, enabling integration with Home Assistant, Node-RED, and custom applications without proprietary hubs.

Zigbee2MQTT可将Zigbee设备桥接到MQTT，无需专有集线器即可与Home Assistant、Node-RED及自定义应用集成。

Architecture Overview

架构概述

Zigbee Devices → [Adapter] → zigbee-herdsman → zigbee-herdsman-converters → zigbee2mqtt → MQTT Broker → Home Assistant/Apps

Three-layer stack:

zigbee-herdsman: Hardware abstraction, Zigbee protocol handling
zigbee-herdsman-converters: Device definitions, cluster-to-MQTT mapping
zigbee2mqtt: Bridge application, state management, web UI

Zigbee Devices → [Adapter] → zigbee-herdsman → zigbee-herdsman-converters → zigbee2mqtt → MQTT Broker → Home Assistant/Apps

三层架构栈：

zigbee-herdsman：硬件抽象、Zigbee协议处理
zigbee-herdsman-converters：设备定义、集群到MQTT的映射
zigbee2mqtt：桥接应用、状态管理、Web UI

Configuration

配置

Configuration lives in

data/configuration.yaml

. Key sections:

yaml

undefined

配置文件位于

data/configuration.yaml

中。关键配置部分如下：

yaml

undefined

MQTT connection

MQTT连接

mqtt: server: mqtt://localhost:1883 base_topic: zigbee2mqtt user: mqtt_user password: mqtt_pass

Zigbee adapter

Zigbee适配器

serial: port: /dev/ttyUSB0

adapter: zstack # auto-detected usually

serial: port: /dev/ttyUSB0

adapter: zstack # 通常会自动检测

Network settings

网络设置

advanced: channel: 11 # 11-26, avoid WiFi overlap network_key: GENERATE # auto-generates secure key pan_id: GENERATE

advanced: channel: 11 # 11-26，避免与WiFi重叠 network_key: GENERATE # 自动生成安全密钥 pan_id: GENERATE

Web UI

frontend: port: 8080

Device tracking

设备追踪

availability: true


**Per-device config** in `devices.yaml`:
```yaml
'0x00158d0001234567':
  friendly_name: living_room_sensor
  retain: true

Groups in

groups.yaml

yaml

'1':
  friendly_name: all_lights
  devices:
    - bulb_1
    - bulb_2

availability: true


**单设备配置**在`devices.yaml`中：
```yaml
'0x00158d0001234567':
  friendly_name: living_room_sensor
  retain: true

群组配置在

groups.yaml

中：

yaml

'1':
  friendly_name: all_lights
  devices:
    - bulb_1
    - bulb_2

MQTT Topics

MQTT主题

Device Communication

设备通信

Topic	Direction	Purpose
`zigbee2mqtt/{device}`	Subscribe	Device state
`zigbee2mqtt/{device}/set`	Publish	Control device
`zigbee2mqtt/{device}/get`	Publish	Request state
`zigbee2mqtt/{device}/availability`	Subscribe	Online/offline

Control examples:

json

// Turn on light with brightness
{"state": "ON", "brightness": 200}

// Set color temperature
{"color_temp": 350}

// RGB color
{"color": {"r": 255, "g": 100, "b": 50}}

主题	方向	用途
`zigbee2mqtt/{device}`	订阅	设备状态
`zigbee2mqtt/{device}/set`	发布	控制设备
`zigbee2mqtt/{device}/get`	发布	请求状态
`zigbee2mqtt/{device}/availability`	订阅	在线/离线状态

控制示例：

json

// 打开灯光并设置亮度
{"state": "ON", "brightness": 200}

// 设置色温
{"color_temp": 350}

// RGB颜色
{"color": {"r": 255, "g": 100, "b": 50}}

Bridge Management

桥接管理

Topic	Purpose
`zigbee2mqtt/bridge/state`	Bridge online status
`zigbee2mqtt/bridge/info`	Version, coordinator info
`zigbee2mqtt/bridge/devices`	All paired devices
`zigbee2mqtt/bridge/event`	Join/leave events

Request/response pattern:

Publish to:   zigbee2mqtt/bridge/request/{command}
Subscribe to: zigbee2mqtt/bridge/response/{command}

Common commands:

```
permit_join
```
- Enable pairing:
```
{"value": true, "time": 120}
```
```
remove
```
- Remove device:
```
{"id": "0x00158d..."}
```
```
rename
```
- Rename device:
```
{"from": "old", "to": "new"}
```
```
restart
```
- Restart bridge

主题	用途
`zigbee2mqtt/bridge/state`	桥接在线状态
`zigbee2mqtt/bridge/info`	版本、协调器信息
`zigbee2mqtt/bridge/devices`	所有已配对设备
`zigbee2mqtt/bridge/event`	加入/离开事件

请求/响应模式：

发布至:   zigbee2mqtt/bridge/request/{command}
订阅至:   zigbee2mqtt/bridge/response/{command}

常用命令：

```
permit_join
```
- 启用配对：
```
{"value": true, "time": 120}
```
```
remove
```
- 移除设备：
```
{"id": "0x00158d..."}
```
```
rename
```
- 重命名设备：
```
{"from": "old", "to": "new"}
```
```
restart
```
- 重启桥接

Adding Device Support

添加设备支持

Quick: External Converter

快速方案：外部转换器

For testing without modifying source, create

data/external_converters/my_device.js

javascript

const {deviceEndpoints, onOff} = require('zigbee-herdsman-converters/lib/modernExtend');

const definition = {
    zigbeeModel: ['TS0001'],
    model: 'TS0001',
    vendor: 'TuYa',
    description: 'Smart switch',
    extend: [onOff()],
};

module.exports = definition;

Enable in

configuration.yaml

yaml

external_converters:
  - my_device.js

无需修改源码即可测试，创建

data/external_converters/my_device.js

：

javascript

const {deviceEndpoints, onOff} = require('zigbee-herdsman-converters/lib/modernExtend');

const definition = {
    zigbeeModel: ['TS0001'],
    model: 'TS0001',
    vendor: 'TuYa',
    description: 'Smart switch',
    extend: [onOff()],
};

module.exports = definition;

在

configuration.yaml

中启用：

yaml

external_converters:
  - my_device.js

Full: Contribute to zigbee-herdsman-converters

完整方案：贡献至zigbee-herdsman-converters

Identify device - Pair and check logs for
```
zigbeeModel
```
, clusters
Find vendor file -
```
src/devices/<vendor>.ts
```
Add definition:

typescript

{
    zigbeeModel: ['lumi.sensor_motion.aq2'],
    model: 'RTCGQ11LM',
    vendor: 'Aqara',
    description: 'Motion sensor',
    fromZigbee: [fz.occupancy, fz.battery, fz.illuminance],
    toZigbee: [],
    exposes: [e.occupancy(), e.battery(), e.illuminance()],
}

Key components:

```
fromZigbee
```
: Converters for device → MQTT
```
toZigbee
```
: Converters for MQTT → device
```
exposes
```
: Capabilities exposed to Home Assistant

识别设备 - 配对设备并查看日志获取
```
zigbeeModel
```
、集群信息
找到厂商文件 -
```
src/devices/<vendor>.ts
```
添加定义：

typescript

{
    zigbeeModel: ['lumi.sensor_motion.aq2'],
    model: 'RTCGQ11LM',
    vendor: 'Aqara',
    description: 'Motion sensor',
    fromZigbee: [fz.occupancy, fz.battery, fz.illuminance],
    toZigbee: [],
    exposes: [e.occupancy(), e.battery(), e.illuminance()],
}

核心组件：

```
fromZigbee
```
：设备到MQTT的转换器
```
toZigbee
```
：MQTT到设备的转换器
```
exposes
```
：向Home Assistant暴露的设备能力

Modern Extend Pattern

现代扩展模式

Prefer

extend

for common device types:

typescript

{
    zigbeeModel: ['TRADFRI bulb E27 WS opal 980lm'],
    model: 'LED1545G12',
    vendor: 'IKEA',
    description: 'TRADFRI bulb E27 WS opal 980lm',
    extend: [light({colorTemp: {range: [250, 454]}})],
}

对于常见设备类型，优先使用

extend

：

typescript

{
    zigbeeModel: ['TRADFRI bulb E27 WS opal 980lm'],
    model: 'LED1545G12',
    vendor: 'IKEA',
    description: 'TRADFRI bulb E27 WS opal 980lm',
    extend: [light({colorTemp: {range: [250, 454]}})],
}

Debugging

调试

Enable Debug Logging

启用调试日志

yaml

advanced:
  log_level: debug
  log_namespaced_levels:
    z2m:mqtt: warning  # Reduce MQTT noise
    zh:zstack: debug   # Adapter-level debug

Log namespaces:

```
z2m:*
```
- zigbee2mqtt core
```
zh:*
```
- zigbee-herdsman (protocol)
```
zhc:*
```
- zigbee-herdsman-converters

yaml

advanced:
  log_level: debug
  log_namespaced_levels:
    z2m:mqtt: warning  # 减少MQTT日志噪音
    zh:zstack: debug   # 适配器级调试

日志命名空间：

```
z2m:*
```
- zigbee2mqtt核心
```
zh:*
```
- zigbee-herdsman（协议层）
```
zhc:*
```
- zigbee-herdsman-converters

Common Issues

常见问题

Device won't pair:

Verify
```
permit_join
```
enabled
Check adapter connection:
```
ls -la /dev/ttyUSB*
```
Use USB extension cable (reduces interference)
Try different channel (avoid 11 if using 2.4GHz WiFi)

Device offline:

Check
```
availability
```
config
Verify device battery / power
Look for
```
last_seen
```
timestamp
Check for Zigbee mesh issues (weak routing)

Adapter disconnects:

bash

dmesg | grep -i usb  # Check kernel logs
journalctl -u zigbee2mqtt -f  # Service logs

设备无法配对：

确认
```
permit_join
```
已启用
检查适配器连接：
```
ls -la /dev/ttyUSB*
```
使用USB延长线（减少干扰）
尝试更换信道（若使用2.4GHz WiFi，避免信道11）

设备离线：

检查
```
availability
```
配置
确认设备电池/供电情况
查看
```
last_seen
```
时间戳
检查Zigbee mesh网络问题（路由信号弱）

适配器断开连接：

bash

dmesg | grep -i usb  # 查看内核日志
journalctl -u zigbee2mqtt -f  # 查看服务日志

Development Setup

开发环境搭建

bash

git clone https://github.com/Koenkk/zigbee2mqtt
cd zigbee2mqtt
pnpm install --frozen-lockfile
pnpm run build  # Compile TypeScript

bash

git clone https://github.com/Koenkk/zigbee2mqtt
cd zigbee2mqtt
pnpm install --frozen-lockfile
pnpm run build  # 编译TypeScript

Run

运行

node index.js


**Code structure:**
- `lib/` - TypeScript source (main application)
- `lib/extension/` - Extension system (OTA, groups, etc.)
- `lib/mqtt/` - MQTT handling
- `data/` - Configuration, database

**Testing:**
```bash
pnpm test
pnpm run lint

node index.js


**代码结构：**
- `lib/` - TypeScript源码（主应用）
- `lib/extension/` - 扩展系统（OTA、群组等）
- `lib/mqtt/` - MQTT处理模块
- `data/` - 配置文件、数据库

**测试：**
```bash
pnpm test
pnpm run lint

OTA Updates

OTA更新

Enable firmware updates:

yaml

ota:
  update_check_interval: 1440  # minutes
  disable_automatic_update_check: false

Check/trigger via MQTT:

zigbee2mqtt/bridge/request/device/ota_update/check
{"id": "device_name"}

启用固件更新：

yaml

ota:
  update_check_interval: 1440  # 分钟
  disable_automatic_update_check: false

通过MQTT检查/触发更新：

zigbee2mqtt/bridge/request/device/ota_update/check
{"id": "device_name"}

Home Assistant Integration

Home Assistant集成

Automatic discovery via MQTT. Ensure:

yaml

homeassistant: true

Devices appear automatically. Override discovery:

yaml

'0x00158d0001234567':
  friendly_name: motion_sensor
  homeassistant:
    occupancy:
      device_class: motion
      name: "Living Room Motion"

通过MQTT自动发现。确保配置：

yaml

homeassistant: true

设备会自动显示。可覆盖发现配置：

yaml

'0x00158d0001234567':
  friendly_name: motion_sensor
  homeassistant:
    occupancy:
      device_class: motion
      name: "Living Room Motion"

Reference

参考资料

Configuration options - Complete settings reference
MQTT API - Full topic and payload documentation
Converter patterns - Device definition examples

配置选项 - 完整设置参考
MQTT API - 完整主题与负载文档
转换器模式 - 设备定义示例