> For the complete documentation index, see [llms.txt](https://cube.ewelink.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cube.ewelink.cc/english-zh/kuai-su-kai-shi/tian-jia-she-bei/zigbee-she-bei.md).

# Zigbee 设备

## **1. 安装 Zigbee 适配器**

如果你在安装 CUBE 时已按照 Zigbee 的可选步骤进行操作，你可以跳转到 [第 2 步](#id-2.-initialize-zigbee) ，将你的 dongle 初始化为 Zigbee 网络协调器。

在添加 Zigbee 设备之前，你需要一个 Zigbee 适配器，通常是一个 USB dongle。将 Zigbee 适配器插入运行 CUBE OS 的设备的 USB 端口。

**虚拟机用户**：插入 Zigbee 适配器后，请将其添加到虚拟机设置中并重启 CUBE。详细步骤可在虚拟机 [安装指南](/english-zh/kuai-su-kai-shi/quickstart/xu-ni-ji.md).

### **1.1 兼容的适配器**

CUBE 兼容来自不同厂商的多种 Zigbee 适配器。目前支持 EZSP、Deconz、Zstack 和 Zigate 等协议栈。虽然任何支持这些协议栈的适配器都可以使用，但推荐以下型号：

> SONOFF ZBDongle-MAX\
> SONOFF ZBDongle-PMG24\
> SONOFF ZBDongle-LMG21\
> SONOFF ZBDongle-E\
> SONOFF ZBDongle-P\
> [列出的其他项](https://darkxst.github.io/silabs-firmware-builder/) 由开发者 @darkxst 提供 

## **2. 初始化 Zigbee**

{% stepper %}
{% step %}
插入 Zigbee 适配器后，CUBE 会显示一个弹窗，例如 `Dongle 已连接` ，表示已检测到该适配器。

<div align="left"><figure><img src="/files/08af9673c2b4314c9f8cbadf20e9c4db6a5d0a1f" alt="" width="277"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
使用 **SONOFF Zigbee dongle**，点击 `开始设置`.

如果该 dongle 已运行受支持的 Zigbee 固件版本，CUBE 会自动完成设置。如果固件版本不受支持，CUBE 会提供一键刷写到推荐的稳定版本。

<div align="left"><figure><img src="/files/fa2d760681036ea409dd9f4f2dca34659fcbc2e2" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
使用 **非 SONOFF Zigbee 适配器**，点击 `开始设置`.

如果该适配器已运行受支持的 Zigbee 固件版本，CUBE 会自动完成设置。如果固件版本不受支持，请先使用厂商的刷写工具安装推荐的稳定版本，然后再继续。 **否则**，CUBE 将无法使用该适配器控制 Zigbee 设备。
{% endstep %}

{% step %}
当适配器完成固件升级和配置后，你现在就可以添加 Zigbee 设备了。

<div align="left"><figure><img src="/files/ca666b360a3a7aef2f23ef5ff9dfe52272f90772" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
如果 CUBE 未检测到你的 Zigbee 适配器，请通过输入所需信息手动添加：

<img src="/files/c052e62fb258d8f93d07513b5b75b2ddcda7cb8e" alt="" data-size="original">

* **串口路径**：在设置页面的“所有硬件”部分查看已插入 Zigbee 适配器的串口路径。

<img src="/files/c5d67b5871af02f2715621d292ef85bf237b8570" alt="" data-size="original">

* **协议栈类型**：CUBE 目前支持 EZSP、Deconz、ZStack 和 Zigate。请查看适配器文档或购买页面以确认正确类型。
* **端口速度**：可选。并非所有 Zigbee 适配器都需要。
* **数据流**：可选。并非所有 Zigbee 适配器都需要。

点击 `确认` 以保存配置。如果设置成功，你就可以开始添加 Zigbee 设备了。如果失败，请查看错误信息并更新配置。

<img src="/files/12080cada190fadc4b2eacd7e2abd4939ff8e074" alt="" data-size="original">
{% endstep %}
{% endstepper %}

{% hint style="info" %}
由于 Zigbee 网络只能有一个适配器配置，因此不支持多个设置。如果已配置的适配器被移除后又重新插入，CUBE 会自动检测该设备，并引导你恢复，无需重新配置。
{% endhint %}

## **3. 添加 Zigbee 设备**

{% stepper %}
{% step %}
配置完成后，在添加设备页面点击“开始配对”，即可自动添加处于配对模式的 Zigbee 设备。

{% hint style="info" %}
如果未找到你的 Zigbee 设备，请确保该设备处于网络配置模式，并检查周围是否存在过强的无线电干扰。
{% endhint %}

<img src="/files/e13ea6d40b919e4002c2e99dec309ef1503ad106" alt="" data-size="original">
{% endstep %}

{% step %}
发现的 Zigbee 设备随后会被添加到你的 CUBE OS 中，准备好分配房间或编辑名称。

<img src="/files/5bdc89fced4dc92b7974df459f49c2c11413d66a" alt="" data-size="original">
{% endstep %}
{% endstepper %}

{% hint style="info" %}
可添加的 Zigbee 设备总数受限，取决于适配器的硬件和固件。

在某些情况下，你需要额外添加路由设备（例如智能插座、灯具、信号中继器），以添加更多由电池供电的设备，如传感器。
{% endhint %}

## 4. 潜在兼容性

CUBE **兼容数百种 Zigbee 设备**。然而，由于产品复杂性高且种类繁多，不同厂商的产品之间存在很大差异。这意味着无法保证与所有设备都兼容，但我们会持续迭代改进。

请前往查看 <https://cube-web.ewelink.cc/> 以检查兼容性。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cube.ewelink.cc/english-zh/kuai-su-kai-shi/tian-jia-she-bei/zigbee-she-bei.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.