# Zigbee Devices

## **1. Install Zigbee Adapters**

If you have followed the optional steps for Zigbee when installing CUBE, you can jump to [Step 2](#id-2.-initialize-zigbee) to initialize your dongle as your Zigbee network coordinator.

Before adding a Zigbee device, you need a Zigbee adapter, typically a USB dongle. Insert the Zigbee adapter into the USB port of the device running CUBE OS.

**For Virtual Machine Users**: After inserting the Zigbee adapter, add it to the virtual machine settings and restart CUBE. Detailed steps can be found in the virtual machine [installation guide](/getting-started/quickstart/virtual-machine.md).

### **1.1 Compatible Adapters**

CUBE is compatible with various Zigbee adapters from different manufacturers. It currently supports protocol stacks such as EZSP, Deconz, Zstack, and Zigate. Although any adapter supporting these protocol stacks can be used, the following are recommended:

> SONOFF ZBDongle-MAX\
> SONOFF ZBDongle-PMG24\
> SONOFF ZBDongle-LMG21\
> SONOFF ZBDongle-E\
> SONOFF ZBDongle-P\
> [Others listed](https://darkxst.github.io/silabs-firmware-builder/) by developer @darkxst 

## **2. Initialize Zigbee**

{% stepper %}
{% step %}
After plugging in your Zigbee adapter. CUBE shows a pop-up, such as `Dongle Connected` when the adapter is detected.

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

{% step %}
Using a **SONOFF Zigbee dongle**, click `Start Setup`.

If the dongle already runs a supported Zigbee firmware version, CUBE completes setup automatically. If the firmware version is not supported, CUBE provides one-click flashing to the recommended stable version.

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

{% step %}
Using a **non-SONOFF Zigbee adapter**, click `Start Setup`.

If the adapter already runs a supported Zigbee firmware version, CUBE completes setup automatically. If the firmware version is not supported, use the vendor's flashing tool to install the recommended stable version before you continue. **Otherwise**, CUBE cannot control Zigbee devices with that adapter.
{% endstep %}

{% step %}
Once the adapter has completed its firmware upgrade and configuration, you can now add Zigbee devices.

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

{% step %}
If CUBE does not detect your Zigbee adapter, add it manually by entering the required information:

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

* **Serial Path**: Check the “All Hardware” section on the settings page for the serial port path of the inserted Zigbee adapter.

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

* **Protocol Stack Type**: CUBE currently supports EZSP, Deconz, ZStack, and Zigate. Check the adapter documentation or purchase page for the correct type.
* **Port Speed**: Optional. Not required for all Zigbee adapters.
* **Data Flow**: Optional. Not required for all Zigbee adapters.

Click `Confirm` to save the configuration. If the setup succeeds, you can start adding Zigbee devices. If it fails, check the error message and update the configuration.

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

{% hint style="info" %}
Since a Zigbee network can only have one adapter configuration, multiple setups are not supported. If a configured adapter is removed and then reinserted, CUBE will automatically detect the device and guide you to restore itself without needing reconfiguration.
{% endhint %}

## **3. Add Zigbee Devices**

{% stepper %}
{% step %}
After configuration, on the add device page, click “Start Pairing” to add Zigbee devices in pairing mode automatically.

{% hint style="info" %}
If your Zigbee device is not found, ensure the device is in network configuration mode and check for excessive surrounding radio interference.
{% endhint %}

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

{% step %}
Discovered Zigbee devices will then be added to your CUBE OS, ready to assign a room or edit the name.

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

{% hint style="info" %}
The total number of Zigbee devices that can be added is limited, depending on the adapter's hardware and firmware.

In certain cases, you need to add extra router devices (e.g. smart plugs, lights, signal repeaters) to add more battery-powered devices like sensors.
{% endhint %}

## 4. Potential Compatibility

CUBE is **compatible with hundreds of Zigbee devices**. However, substantial differences exist between products from different manufacturers due to the complexity and wide range of devices. This means compatibility with all devices cannot be guaranteed, but improvements will be made iteratively.

Please direct you to check the <https://cube-web.ewelink.cc/> to check the compatibility.


---

# Agent Instructions: 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:

```
GET https://cube.ewelink.cc/getting-started/add-devices/zigbee-devices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.