# Welcome Hey, glad you made it here, the official documentation website of eWeLink CUBE OS! eWeLink CUBE OS is a **free, open, self-hosted local software system** designed to upgrade the smart devices already in your home. #### Download the Latest Image on {% embed url="" %} It allows many eWeLink-supported Wi-Fi devices, such as SONOFF products, to be directly bridged into the Matter network without any additional hardware, enabling them to work simultaneously with Apple Home, SmartThings, Google Home, Amazon Alexa, Home Assistant, and other Matter-compatible platforms. With a Zigbee dongle, eWeLink CUBE OS can also integrate multi-brand Zigbee switches, sensors, and lights, and bridge them into these Matter platforms, bringing your devices together into one unified smart home environment. By installing eWeLink CUBE OS, your existing Wi-Fi and Zigbee devices gain a modern and unified Matter smart home experience, without replacing any hardware. ## Jump Right in
Cover image
Installation/pages/CyH2xJQs9yWJ1S8BYNav/files/XutfQroodcVdnX12ZY3R
Add Devices/pages/kkSyp1QxGf9lG0OXdHWh/files/ZbMhzEExWJPYsCLVEUu8
Feature Exploration/pages/nV5MeR1SPsag3XVS7l4y/files/Ffvur1CkIYbW380IfHW5
## What's eWeLink CUBE OS? A free self-hosted local system that bridges eWeLink Wi-Fi and multi-brand Zigbee devices into the Matter network for Apple Home, SmartThings, Google Home, Alexa, and Home Assistant. ## Key Features 😁**Upgrade existing devices - no new hardware required** Bridge many eWeLink/SONOFF Wi-Fi devices and multi-brand Zigbee devices (via a Zigbee dongle) into the Matter network, extending compatibility across modern ecosystems. 📡**Add Zigbee devices instantly with zero configuration** Simply plug in a Zigbee dongle to quickly add switches, sensors, and lights from various brands. Auto-detection, auto-pairing, ready to use. 🔗**Make devices available on multiple platforms at the same time** Bridged devices can appear simultaneously in Apple Home, SmartThings, Google Home, Amazon Alexa, Home Assistant, and other Matter-enabled platforms. ⚡**Local-first operation for speed and stability** Runs entirely on your local hardware - fast response, reliable connections, no cloud dependency. # Installation In general, Raspberry Pi would be easier and more extensive to experience CUBE OS. If you don't have a Raspberry Pi, don't worry, you can use an old machine or NAS at home to run CUBE OS via virtual machines. For a more seamless experience with CUBE OS without extra steps, you can alternatively purchase a [SONOFF iHost](https://sonoff.tech/products/sonoff-ihost-smart-home-hub/58).
Raspberry Pi Guide/pages/pHAhbLtrGkY94lIVjRGS
Virtual Machine Guide/pages/vEJMlEEKYVRG3RI1wc8J
NAS Devices Guide/pages/de4M7gMGOhzH2LqDRHFo
Docker/pages/euIaLsJ13Cbygoo6lWvv
We also provide one-click installers of CUBE OS on Windows and Mac. Each installer reduces manual setup and helps you get CUBE OS running faster.
One-click Installation/pages/XIrc4s3EHrTfTaNLEYDe
# Raspberry Pi A guide to install CUBE OS on a Raspberry Pi 4B/5. {% embed url="" %} {% hint style="info" %} Models with smaller memory (RAM) may counter performance issues. A **Raspberry Pi with at least 4GB of memory is recommended.** If you do not have a Raspberry Pi, consider the [virtual machine](/getting-started/quickstart/virtual-machine/virtualbox) installation. Alternatively, [purchase an iHost](https://sonoff.tech/products/sonoff-ihost-smart-home-hub/58) shipped with CUBE OS from the SONOFF website or Amazon if neither option is feasible. {% endhint %} ## 1. Preparation {% stepper %} {% step %} Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/) to download the latest image. {% endstep %} {% step %} Obtain a [Raspberry Pi](https://amzn.to/2S0Gcl1) and get it ready following the Raspberry Pi official [guides](https://www.raspberrypi.com/documentation/computers/getting-started.html) if you have a kit like the enclosure and cooling fan. {% endstep %} {% step %} Other Required Accessories: 1. A micro SD card (TF Card) and a card reader. Storage cards with at least a C10 and A1 rating are recommended. 2. Ethernet cable. 3. If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} 4. Power Adapter (Alternatively, if you have a Power over Ethernet (PoE) Hat installed, ensure your network switch or router, as well as the Ethernet cable, can provide sufficient power) {% hint style="info" %} Ensure you have an [appropriate power supply](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply) for the Raspberry Pi. Smartphone chargers may not be suitable, as some only provide full power to certain manufacturers’ phones. USB ports on computers do not supply adequate power and should not be used. {% endhint %} {% endstep %} {% endstepper %} ## 2. Burn CUBE OS to SD Card {% stepper %} {% step %} Download and install the Raspberry Pi Imager from the [Raspberry Pi website](https://www.raspberrypi.com/software/). {% endstep %} {% step %} Open Raspberry Pi Imager and select your Raspberry Pi device. {% endstep %} {% step %} For the operating system, choose “Use Custom” and select the downloaded CUBE image. ![](/files/kBYW9VXvgy4cYhifEkzD) {% endstep %} {% step %} Insert the SD card into the computer and select it as the storage to use. {% endstep %} {% step %} If you are promoted with customization options, click `NO`. {% endstep %} {% step %} Click “Next” to write the image to the SD card. Note that the card’s contents will be overwritten. {% endstep %} {% step %} Wait until the write process reaches 100% and eject the SD card upon completion. {% endstep %} {% endstepper %} ## 3. Boot Raspberry Pi and Accessing CUBE: {% stepper %} {% step %} Insert the Micro SD card into the Raspberry Pi (on the short side of the board near the LED). {% endstep %} {% step %} Connect the Raspberry Pi to a power source and Ethernet cable, ensuring it is on the same network as your computer and connected to the internet. {% endstep %} {% step %} Optional: If you have a Zigbee Dongle, plug it into a USB port. {% endstep %} {% step %} After powering the Raspberry Pi, wait a few minutes for it to boot up. Then, access the Web management page using [cube.local](http://cube.local). Or you can find the CUBE’s IP from your router’s interface and use it to access the management page. Usually, you can see the IP next to the device named `cube`, which also has the longest expiring time (Leasetime remaining). {% endstep %} {% step %} Upon successful access, view a short ID on the settings page. Access the CUBE Web management page subsequently using cube-{short id}.local, especially useful for distinguishing multiple CUBEs on the same local network. {% endstep %} {% endstepper %} # Virtual Machine These guides provide instructions for installing CUBE OS on virtual machines. The host can be an old PC or a Mini PC.
VirtualBox/pages/x9xVPqO7K55qCOzOkjJH
VMware/pages/yXQMiVP8yHsIGM0V1XPS
Hyper-V/pages/LkT7m7lH2Zbemg1NGWIM
Proxmox/pages/jNnR1RbeIKQlUqFzYE35
# VirtualBox This is a generic guide to installing CUBE OS on VirtualBox, the host can be an old PC, or a Mini PC. {% embed url="" %} ### 1. Preparation: {% stepper %} {% step %} **Download the** CUBE OS **image** Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) to download the latest `.vdi` image. Please extract the image after downloading. {% endstep %} {% step %} **Install Virtual Machine** Download and install a virtual machine manager, with [VirtualBox](https://www.virtualbox.org/wiki/Downloads) being recommended. > Have other virtual machine managers? The following steps can theoretically be used as well.\ > Unfamiliar with virtual machines and owning a Raspberry Pi? You can choose to install CUBE OS on a [Raspberry Pi](/getting-started/quickstart/raspberry-pi). \ > If none of these options are viable, you can purchase an [iHost](https://sonoff.tech/products/sonoff-ihost-smart-home-hub/58) with built-in CUBE OS from the SONOFF official website or platforms like Amazon. > {% endstep %} {% step %} **Zigbee Adapter (Optional)** If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} {% endstep %} {% endstepper %} ### 2. Create a Virtual Machine: {% stepper %} {% step %} Launch VirtualBox {% endstep %} {% step %} Select “New” or use the shortcut “Ctrl + N”. {% endstep %} {% step %} Name the virtual machine, select “Linux” as the type, “Other Linux” as the subtype, and “Other Linux (64 bit)” as the version. {% endstep %} {% step %} Under “Hardware”, allocate the memory size and processor count for the virtual machine. 4GB memory and 2 CPUs are recommended. Then, enable EFI. {% hint style="info" %} Important: Ensure EFI is enabled; otherwise, CUBE OS will not boot. {% endhint %} {% endstep %} {% step %} Under “Hard Disk”, choose to use an existing virtual hard disk file and select the .vdi file extracted from [Preparation Step 1.](#id-1-preparation) {% endstep %} {% step %} Click “Finish” to create the virtual machine. {% endstep %} {% endstepper %} ### 3. Configure the Virtual Machine: {% stepper %} {% step %} Select the created virtual machine and click the “Settings” button. {% endstep %} {% step %} Under the “Network” tab, configure the network connection as “Bridged Adapter” and select the network adapter you are using. {% endstep %} {% step %} Under “Audio”, enable sound and choose the Default option as the controller. {% endstep %} {% step %} **Optional:** For Zigbee Dongle usage, insert the Zigbee Dongle at this step and select the correct controller type under “USB”. In the USB filter, add the necessary Zigbee Dongle using the add button on the side. {% endstep %} {% step %} Click “OK” to save the configuration. {% endstep %} {% endstepper %} ### 4. Boot CUBE OS {% stepper %} {% step %} Click the "Start" button . {% endstep %} {% step %} Monitor the boot screen until the boot is complete. {% endstep %} {% step %} Once completed, you will see the CUBE OS' IP displayed on the screen. Use this IP address or [cube.local](http://cube.local) to access the CUBE OS Web management page. {% endstep %} {% step %} Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using `cube-{short id}.local`, which is useful for differentiating multiple CUBE OS instances on the same local network. {% endstep %} {% endstepper %} # VMware This is a generic guide to installing CUBE OS on VMware, the host can be an old PC, or a Mini PC. {% embed url="" %} ### 1. Preparation: {% stepper %} {% step %} **Download the** CUBE OS **image** Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) to download the latest `.vmdk`image. Please extract the image after downloading. {% endstep %} {% step %} **Install VMware** Download and install a virtual machine manager, with [VMware Workstation](https://www.vmware.com/products/desktop-hypervisor/workstation-and-fusion) being recommended. > Have other virtual machine managers? The following steps can theoretically be used as well.\ > Unfamiliar with virtual machines and owning a Raspberry Pi? You can choose to install CUBE OS on a [Raspberry Pi](/getting-started/quickstart/raspberry-pi). \ > If none of these options are viable, you can purchase an [iHost](https://sonoff.tech/products/sonoff-ihost-smart-home-hub/58) with built-in CUBE OS from the SONOFF official website or platforms like Amazon. > {% endstep %} {% step %} **Zigbee Adapter (Optional)** If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} {% endstep %} {% endstepper %} ### 2. Create a Virtual Machine {% stepper %} {% step %} Launch VMware, Select “Create a New Virtual Machine” .
{% endstep %} {% step %} Choose **Custom**, click **Next**. Hardware-**Workstation 17.5 or later,** click **Next.**\ ![](/files/1QPdwNm8ttJKaxxsb3Od)![](/files/fv8lF2n0DVmzS8WQwAf5) {% endstep %} {% step %} Choose **I will install the operating system later**, click **Next**.![](/files/3ekdrbkocuNFwvjF7ode) {% endstep %} {% step %} Select **Linux > Other Linux 6.x kernel (64-bit)** as the guest operating system type.![](/files/C6ryBw3xNr8NKF6B4zfS) {% endstep %} {% step %} Name the VM as **CUBE OS** and choose a storage location.![](/files/obnt00ign9r7Qhtzh470) {% endstep %} {% step %} System Resources: * **Processors**: 2 cores * **Memory**: 4096MB (4GB) or more\ ![](/files/HO3u94GJT5odN8gYmZns)![](/files/Y6tWTGPUXiFmqZGbhivl) {% endstep %} {% step %} Network / I/O Controller Types: * Set **Network Adapter** to **Bridged** mode (important for LAN access and discovery). * Set **Controller Type** to **LSI Logic** (required for compatibility with the virtual disk).![](/files/UPx3rYQZZfNVBcReQL7Q)![](/files/MjrwNfdVDJ7jKHjfFU8K) {% endstep %} {% step %} Select a Disk Type **SCSI(Recommended), Use an existing virtual disk**. ![](/files/B14h4eYbg3cTJxpEiWZV)![](/files/c6Zs2AM8At2Ku6LB8hnM) {% endstep %} {% step %} Click **Browse**, then select the CUBE OS `.vmdk` and **Keep Existing Format**.![](/files/F6Zir4sAEB2XUY0UQKj8)![](/files/rdspYd9HJmcF912kj2Mn) {% endstep %} {% step %} Click “Finish” to create the virtual machine. {% endstep %} {% endstepper %} ### 3. Configure the Virtual Machine {% stepper %} {% step %} Select the created virtual machine and click the “Settings” ![](/files/chbff7DLftkcF1wILBdb) button.![](/files/AGPEyDDiiqQEHy2VFgAU) {% endstep %} {% step %} Under the “Network” tab, confirm the network connection as “**Bridged**” and select **Replicate physical network connection state**. {% endstep %} {% step %} Under “Options”-“Advanced” tab, set **Firmware type** to **UEFI**. ![](/files/uDDbJxFUYDVOoOKhh5aS) {% endstep %} {% step %} **Optional:** If using a Zigbee USB dongle, ensure **USB Controller** is added. Under **USB Controller**, enable **Show all USB input devices.** ![](/files/bMmDItxspJahsRoHCTtd) {% endstep %} {% step %} Click “OK” to save the configuration. {% endstep %} {% endstepper %} ### 4. Boot CUBE OS {% stepper %} {% step %} Start the virtual machine. {% endstep %} {% step %} Wait a few moments for CUBE OS to initialize. Monitor the boot screen until the boot is complete. ![](/files/ooXXlbvBBfxIkch1GV2Y) {% endstep %} {% step %} Once completed, you will see the CUBE OS' IP displayed on the screen. Use this IP address or [cube.local](http://cube.local) to access the CUBE OS Web management page. {% endstep %} {% step %} Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using `cube-{short id}.local`, which is useful for differentiating multiple CUBE OS instances on the same local network. {% endstep %} {% endstepper %} # Hyper-V This guide explains how to install CUBE OS on Microsoft Hyper-V running on Windows. Special thanks to our community contributor [@Jordanwise](https://forum.ewelink.cc/u/jordanwise) for creating and sharing this helpful tutorial video: {% embed url="" %} ### 1. Preparation {% stepper %} {% step %} **Download the** CUBE OS **image** Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) to download the latest `.vmdk` image. Please extract the image after downloading. {% endstep %} {% step %} **Install Hyper-V** Windows 10 / 11 Pro, Enterprise, or Education (Hyper-V required) Hyper-V enabled on your system: Before using Hyper-V, make sure it is enabled in Windows. Open **Control Panel → Programs → Turn Windows features on or off**,
enable **Hyper-V** (including *Hyper-V Management Tools* and *Hyper-V Platform*), **Virtual Machine Platform**, **Windows Hypervisor Platform**, then click **OK** and restart your computer.
{% endstep %} {% step %} **Zigbee Adapter (Optional)** If you need to add USB Zigbee devices, please note that Hyper-V does not support native USB passthrough for hardware devices such as Zigbee dongles. If USB access is required, consider using a **USB-over-IP solution** or a **network-based Zigbee coordinator** instead. {% endstep %} {% endstepper %} ### 2. Convert the CUBE OS Image to VHDX Before creating the virtual machine, convert the CUBE OS disk image to a Hyper-V **VHDX** compatible format. {% stepper %} {% step %} Download and install a VM image conversion tool, such as **VM Image Converter** (recommended on Windows)
{% endstep %} {% step %} Launch the converter and select: * Source format: **VMDK** * Target format: **VHDX**
{% endstep %} {% step %} Complete the conversion and note the location of the generated `.vhdx` file.
{% endstep %} {% endstepper %} ### 3. Create the Virtual Machine {% stepper %} {% step %} Launch **Hyper-V Manager**.
{% endstep %} {% step %} Click **Quick Create** → Select![](/files/apOgK77L0Kd5BfrrkXUG)**Local installation source**.
{% endstep %} {% step %} Select **Change installation source**, select the converted **CUBE OS `.vhdx`** file and disable **Windows Secure Boot**.
{% endstep %} {% step %} Enter a name for the VM (for example, `CUBE OS`), and then **Create Virtual Machine**. {% endstep %} {% endstepper %} ### 4. Configure Virtual Machine Settings {% stepper %} {% step %} Click **Settings** for the newly created virtual machine.
{% endstep %} {% step %} Assign System Resources: * Minimum: **4096 MB (4 GB)** * Disable Dynamic Memory (recommended). * **Processor**: 2 virtual processors
{% endstep %} {% step %} Click **Apply** and **OK** to Save the settings. {% endstep %} {% endstepper %} ### 5. Boot CUBE OS {% stepper %} {% step %} Click **Connect** and **Start** the created virtual machine.
{% endstep %} {% step %} Wait a few moments for CUBE OS to initialize. Monitor the boot screen until the boot is complete.
{% endstep %} {% step %} Once completed, you will see the CUBE OS' IP displayed on the screen. Use this IP address or [cube.local](http://cube.local/) to access the CUBE OS Web management page.
{% endstep %} {% step %} Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using `cube-{short id}.local`, which is useful for differentiating multiple CUBE OS instances on the same local network.
{% endstep %} {% endstepper %} # Proxmox This is a generic guide to installing CUBE OS on Proxmox, the host can be an old PC, or a Mini PC. ### 1. Preparation {% stepper %} {% step %} **Download the CUBE OS image** Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) to download the latest CUBE OS image and extract it after downloading. For Proxmox VE 9, download the disk image archive (commonly `sdcard.vmdk.xz`). Extract it to get the `.vmdk` file. {% endstep %} {% step %} **Prepare a Proxmox VE host** * A running **Proxmox VE** host with admin access (Web UI + Shell/SSH) * If you haven’t installed Proxmox VE yet, follow the official [guide](https://www.proxmox.com/en/products/proxmox-virtual-environment/get-started). * Recommended resources for the VM: * **CPU**: 2 cores * **Memory**: 4096 MB (4 GB) or more {% endstep %} {% step %} **Zigbee Adapter (Optional)** If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} You can pass the dongle through to the VM in Proxmox (see the optional section below). {% endstep %} {% endstepper %} ### 2. Create a Virtual Machine (Proxmox) {% stepper %} {% step %} In Proxmox Web UI, click **Create VM**.
{% endstep %} {% step %} **General -** Set a VM ID and a name, e.g. `CUBE OS`.
{% endstep %} {% step %} **OS -** Choose **Do not use any media**.
{% hint style="info" %} CUBE OS is provided as a prebuilt disk image. In Proxmox, you will **import the disk image** and then boot from it. {% endhint %} {% endstep %} {% step %} **System -** Recommended settings: * **BIOS**: `OVMF (UEFI)` * **EFI Disk**: add an EFI disk (default size is fine) * **Pre-Enfoll keys**: Uncheck
{% hint style="info" %} Just like the VirtualBox/VMware guides, **UEFI is required**. If you can’t boot, double-check the BIOS is set to **OVMF (UEFI)**. {% endhint %} {% endstep %} {% step %} **Disk / CPU / Memory / Network** * **Disk**: do **not** create a new empty disk. You will import the CUBE OS disk image in the next section. * **CPU**: 2 cores (CPU type `host` recommended) * **Memory**: 4096 MB (4 GB) or more * **Network**: * **Bridge**: `vmbr0` (or your LAN bridge) * **Model**: `VirtIO (paravirtualized)`
{% hint style="warning" %} For LAN discovery and `cube.local` to work reliably, avoid NAT-style networking. Use a **bridged** network connected to your home/office LAN. {% endhint %} {% endstep %} {% endstepper %} ### 3. Import the CUBE OS disk image into Proxmox You’ll import the extracted CUBE OS image (for example `CUBE-OS.vmdk`) and attach it as the VM’s boot disk. {% stepper %} {% step %} **Find the right storage (`local`, not `local-lvm`).** In the Proxmox Web UI left sidebar, click **local** (not **local-lvm**).
{% endstep %} {% step %} **Upload the `.vmdk` into `local`** 1. Click **Import** 2. Select the extracted disk image on your computer, for example: * `sdcard.vmdk` 3. Wait for the upload to complete (800+ MB can take a while)
After it finishes, you should see the file in the **Content** list.
{% endstep %} {% step %} **Attach the imported disk and set it as boot disk.** In the CUBE OS VM: 1. Go to **Hardware** 2. Select the imported **Add** → ![](/files/9XmHtOmLiLqDozpC3zdy)**Import Hard Disk**
3. Then go to **Options → Boot Order** and set the imported disk as the first boot device.
{% endstep %} {% endstepper %} ### 4. Boot CUBE OS {% stepper %} {% step %} Click to![](/files/6fwoxeu60uW9YJgC3wtl) the VM and open the **Console**.
{% endstep %} {% step %} Wait a few moments for CUBE OS to initialize. Once boot is complete, you should see the **IP address** displayed on the console.
{% endstep %} {% step %} Open the CUBE OS Web UI * Visit `http:///`, or * Try:
Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using `cube-{short id}.local`, which is useful for differentiating multiple CUBE OS instances on the same local network.
{% endstep %} {% endstepper %} ### 5. (Optional) Zigbee USB Dongle passthrough (Proxmox) {% stepper %} {% step %} Plug the Zigbee dongle into the Proxmox host. {% endstep %} {% step %} In the VM, go to **Hardware → Add → USB Device**. * Prefer selecting by **Vendor/Device ID** (more stable than by port if you move USB ports). * If your dongle exposes a serial interface, it may also appear under **Add → Serial Port** depending on your setup.
{% endstep %} {% step %} Reboot the VM (if required) and then add Zigbee devices in CUBE OS. {% endstep %} {% endstepper %} # NAS Devices These guides provide instructions for installing CUBE OS on NAS Devices.
Synology NAS/pages/lsdRimXnw3LY7TLY3rQ7
UGREEN NAS/pages/UkzPIDXPDhyGcDTWpGXB
# Synology NAS {% embed url="" %} ## 1. Preparation Please make sure your setup meets the following requirements: {% stepper %} {% step %} **6GB RAM** installed (recommended) in your Synology NAS (4GB for the virtual machine running CUBE OS); Please contact Synology for upgrading guides if your unit only has 2GB or less memory. {% endstep %} {% step %} Your NAS has an x86\_64 platform {% hint style="info" %} Currently, only x86\_64 architecture is supported by this installation method. For ARM and other platforms, please turn to other devices and wait for future updates. {% endhint %} {% hint style="info" %} You can refer to this official [document](https://kb.synology.com/en-me/DSM/tutorial/What_kind_of_CPU_does_my_NAS_have) to find the platform information for your Synology devices. {% endhint %} {% endstep %} {% step %} WAN access to download the virtual machine manager {% endstep %} {% step %} Admin account to your Synology NAS {% endstep %} {% step %} Zigbee Adapter (Optional) If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} {% endstep %} {% endstepper %} ## 2. Installation {% stepper %} {% step %} Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) to download the CUBE OS image ending with `.vdi` {% endstep %} {% step %} Access to Synology dashboard {% endstep %} {% step %} Install `Virtual Machine Manager` from the Package Center {% endstep %} {% step %} Launch `Virtual Machine Manager` from the dashboard and switch to the Image page. {% endstep %} {% step %} Enter the Disk Image tab, then click the `Add` button. {% endstep %} {% step %} Follow the guide to upload the `.vdi` file you downloaded from the previous [step](#preparation). {% endstep %} {% step %} Wrap the steps and wait for it to be fully uploaded. {% endstep %} {% step %} Switch to the `Image` tab and upload the .vdi file to your NAS. Please wait until it completes uploading. {% endstep %} {% step %} Switch to the `Virtual Machine` page and click on the dropdown icon next to the `Create` button and use `Import`. {% endstep %} {% step %} Select the `Import from disk images` option on the wizard. {% endstep %} {% step %} Select the storage where you uploaded the virtual disk file. {% endstep %} {% step %} Set the computational resources CUBE OS needs. {% hint style="info" %} **2 vCPUs and 4GB RAM are recommended for a better experience.** {% endhint %} {% endstep %} {% step %} Choose the virtual disk on the dropdown list. {% endstep %} {% step %} ⚠️ For `Other Settings`, choose `UEFI` in the `Firmware` option. ![](/files/orEh0Ga9EXng4mCLmw39) {% endstep %} {% step %} Optional: Plug in your Zigbee dongle to your NAS, and pass through the device to the virtual machine on this page. {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} {% endstep %} {% step %} Assign management permission to your NAS accounts. {% endstep %} {% step %} Final review of your configuration, check `Power on the virtual machine after creation` and click `Done` {% endstep %} {% step %} Wait for a few minutes. Enter [cube.local](http://cube.local) on your browser to access the onboarding page. You can also access it via IP alternatively. {% hint style="info" %} Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using cube-{short id}.local, which is useful for differentiating multiple CUBE OS instances on the same local network. {% endhint %} {% endstep %} {% endstepper %} # UGREEN NAS ## 1. Preparation Please make sure your setup meets the following requirements: {% stepper %} {% step %} **6GB RAM** installed (recommended) in your UGREEN NAS (4GB for the virtual machine running CUBE OS); Please contact UGREEN for upgrading guides if your unit only has 2GB or less memory. {% endstep %} {% step %} Your NAS has an x86\_64 platform {% hint style="info" %} Currently, only x86\_64 architecture is supported by this installation method. For ARM and other platforms, please turn to other devices and wait for future updates. {% endhint %} {% endstep %} {% step %} WAN access to download the virtual machine manager {% endstep %} {% step %} Zigbee Adapter (Optional) If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} {% endstep %} {% endstepper %} ## 2. Installation {% stepper %} {% step %} Visit this [repo](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) to download the CUBE OS image ending with `.vdi` {% endstep %} {% step %} Access to UGREEN dashboard {% endstep %} {% step %} Install `Virtual Machine Manager` from. Launch `Virtual Machine Manager` from the dashboard and switch to the Image page. ![](/files/th504vf4X553AJ0LudFx) {% endstep %} {% step %} Click **Create VM**, then select **Import Virtual Machine**. Choose **Import from Disk File**, then click **Next**. ![](/files/kCOeEhDTED0962cpqY67) {% endstep %} {% step %} If this is your first time setting up, select **Upload image manually**.![](/files/UjFAaiBt3IwGvFUOTalF) {% endstep %} {% step %} Locate the downloaded CUBE OS `.vdi` file: * You can upload it from your local device, or * Select it from existing files on your NAS. ![](/files/LNI0gMYDWRE9asAqYy6I) {% endstep %} {% step %} After selecting the image, click **Confirm** to upload and convert the image.![](/files/j3uSL2CyEgiIvHK9QN1w) {% endstep %} {% step %} Once imported, repeat the **Import Virtual Machine** process: * The uploaded image will now appear in the dropdown list. * Select it and click **Next**. ![](/files/jDB6kU7ixadiHaFZLajY) {% endstep %} {% step %} Choose a storage volume for the virtual machine and continue. ![](/files/vGfTDwJZrNTd94K7kZgd) {% endstep %} {% endstepper %} ## 3. Configure Virtual Machine Settings {% stepper %} {% step %} Basic Configuration: * **System type**: Select **Other** * **vCPUs**: 2 cores (or more if available) * **Memory**: Allocate **4GB or more** ![](/files/2cgMzTzbZC5LmjJs2ur7) {% endstep %} {% step %} Network Configuration: * Select **Bridge mode** (Do **not** use Host or NAT) ![](/files/N1JjZ34ANfIalgJuROAJ) {% endstep %} {% step %} Under USB options, locate and add your Zigbee/Thread USB dongle: * Click the **+** icon to assign the correct USB port. ![](/files/eIoZz4dxXtTuSzEO4Nlx) {% endstep %} {% step %} Set **Bootstrap Type** to **UEFI**. ![](/files/yq5xdeIOuxMvK20MG2he) {% endstep %} {% endstepper %} ## 4. Booting CUBE OS {% stepper %} {% step %} Back in the VM list, click **Start** to power on the virtual machine.![](/files/GmSiqnjgPjEa8CJx9XcX) {% endstep %} {% step %} Wait for a few minutes. Click **Connect** to view the VM console: * If the CUBE OS welcome screen appears, the system has started successfully.![](/files/Gzw7u2pVO3xiB5GTxmhE) {% endstep %} {% step %} Enter [cube.local](http://cube.local) on your browser to access the onboarding page. You can also access it via IP alternatively. {% hint style="info" %} Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using cube-{short id}.local, which is useful for differentiating multiple CUBE OS instances on the same local network. {% endhint %} {% endstep %} {% endstepper %} # Docker A guide to install CUBE OS using Docker on Linux systems. Install CUBE OS as a Docker container on a Linux host. This method works well for home servers, NAS devices, and always-on Linux machines. {% hint style="info" %} Docker deployment is supported on **Linux only**. If you do not have a Linux host, use [Raspberry Pi](/getting-started/quickstart/raspberry-pi) or [Virtual Machine](/getting-started/quickstart/virtual-machine/virtualbox). {% endhint %} ### 1. Preparation {% stepper %} {% step %} **Check the host architecture** CUBE Docker supports these Linux architectures: * **amd64** (`x86_64`) — PCs, servers, Synology NAS, and similar devices * **arm64** (`aarch64`) — Raspberry Pi 4/5, Orange Pi, and other ARM hosts {% endstep %} {% step %} **Check the Linux kernel version** Kernel `4.15` or later is required. ```bash uname -r ``` {% hint style="warning" %} Some NAS devices ship with older kernels, such as `4.4.x`. These hosts are not compatible with CUBE Docker. In that case, run CUBE OS in a Linux virtual machine instead. {% endhint %} {% endstep %} {% step %} **Install Docker Engine** Install Docker Engine on the host before you continue. Use the [official Docker installation guide](https://docs.docker.com/engine/install/). {% endstep %} {% step %} **Check required ports** Make sure ports `80` and `1883` are free on the host. ```bash sudo lsof -i :80 sudo lsof -i :1883 ``` * **80** — CUBE OS web UI * **1883** — MQTT broker If another service is using these ports, stop it first. {% endstep %} {% step %} **Prepare a Zigbee dongle if needed** If you plan to add Zigbee devices, connect a compatible Zigbee dongle to the host. Tested Zigbee dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} For more information on Zigbee support, refer to [this guide](/compatibility-check/zigbee). {% endstep %} {% endstepper %} ### 2. Pull the image {% stepper %} {% step %} **Download the latest image** ```bash docker pull ghcr.io/ewelinkcube/cube-os:latest ```
{% hint style="info" %} You can replace `latest` with a specific version tag, such as `2.10.3`. Available versions are listed on [GitHub Releases](https://github.com/eWeLinkCUBE/CUBE-OS/releases/). {% endhint %} {% endstep %} {% endstepper %} ### 3. Start CUBE OS {% stepper %} {% step %} **Create a data directory** ```bash mkdir -p ~/cubeos-data ``` This directory stores your devices, scenes, and settings. {% endstep %} {% step %} **Check the Zigbee device path if you use one(optional)** Common device paths are: ```bash ls /dev/ttyUSB* /dev/ttyACM* ``` Use the correct path in the next command. {% endstep %} {% step %} **Start the container** Use this command as a baseline: ```bash docker run -d \ --name cubeos \ --privileged \ --net=host \ -v ~/cubeos-data:/data \ --device /dev/ttyUSB0:/dev/ttyUSB0 \ -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \ ghcr.io/ewelinkcube/cube-os:latest ```
{% hint style="info" %} If you do not use Zigbee, remove `--device /dev/ttyUSB0:/dev/ttyUSB0`. If you do not use Matter Hub or eWeLink Remote, you can also remove the D-Bus mount. {% endhint %} {% endstep %} {% step %} **Understand the main parameters** * `--privileged` — required for hardware access * `--net=host` — required for LAN discovery and MQTT * `-v ~/cubeos-data:/data` — keeps your data after container restarts * `--device /dev/ttyUSB0:/dev/ttyUSB0` — passes through a Zigbee dongle * `-v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro` — enables D-Bus access for supported features {% endstep %} {% endstepper %} ### 4. Access CUBE OS {% stepper %} {% step %} **Confirm that the container is running** ```bash docker ps ``` The container status should show `Up`. {% endstep %} {% step %} **Open the web UI** Open a browser on the same network and visit one of these addresses: * `http:///` * Replace `` with the Linux host IP address. {% endstep %} {% step %} **Use the short local address later** After setup, you can find the short ID on the settings page. You can then use `cube-{short-id}.local` to identify this CUBE OS instance on your LAN. {% endstep %} {% endstepper %} ### 5. Update CUBE OS The Docker deployment does not support OTA updates from the web UI. To update manually: ```bash docker stop cubeos docker rm cubeos docker pull ghcr.io/ewelinkcube/cube-os:latest docker run -d \ --name cubeos \ --privileged \ --net=host \ -v ~/cubeos-data:/data \ --device /dev/ttyUSB0:/dev/ttyUSB0 \ -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \ ghcr.io/ewelinkcube/cube-os:latest ``` Your data stays in `~/cubeos-data`, so devices, scenes, and settings remain after the update. ### 6. Limitations Due to container isolation, these features are not available in Docker deployments: * **Add-ons** — cannot install or manage add-ons * **Bluetooth Speaker** — Bluetooth passthrough is not supported * **System Update** — OTA updates in the web UI are disabled * **Reboot / Shutdown** — system-level power controls are unavailable ### 7. Raspberry Pi note If you run Docker on a Raspberry Pi, make sure the page size is `4096`: ```bash getconf PAGE_SIZE # If the result is not 4096, add this line and reboot echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt sudo reboot ``` # One-click Installation Install CUBE OS on Windows or Mac with the One-click Installer. Each installer reduces manual setup and helps you get CUBE OS running faster.
Target
Windows/spaces/CnF8kmk9yw3yiy2mRerq/pages/GuRm0vzpKm6dcou17hlQ
Mac/spaces/CnF8kmk9yw3yiy2mRerq/pages/d4SVeW0YBdI632oMRyxd
# Windows This guide shows you how to install CUBE OS on Windows with the One-click Installer. The installer sets up VirtualBox, creates the virtual machine, and starts CUBE OS for you. ### 1. Preparation {% stepper %} {% step %} **Check your Windows PC** Make sure your PC meets these requirements: * **OS**: Windows 10 or Windows 11, 64-bit * **CPU**: 2 cores or more * **Memory**: 4 GB RAM or more * **Network**: Stable internet and LAN access * **Permissions**: Administrator access on Windows * {% endstep %} {% step %} **Download the installer** Go to the [CUBE OS release page](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) and download **One-click Installer for Windows**.
{% endstep %} {% step %} **Zigbee Adapter (Optional)** If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} Before connecting the Zigbee adapter to Windows, install the matching USB serial driver for the dongle chipset: * **CP210x** — [Silicon Labs CP210x USB to UART Bridge VCP Drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) * **CH34x** — [WCH CH341/CH34x USB Serial Driver](https://www.wch-ic.com/downloads/CH341SER_EXE.html) {% hint style="info" %} If Windows does not detect the dongle in the installer or in VirtualBox, unplug the adapter, install the driver, and then reconnect it. {% endhint %} {% endstep %} {% endstepper %} ### 2. Install CUBE OS with the One-click Installer {% stepper %} {% step %} **Run the installer as administrator** Find the installer file in **Downloads** or your chosen folder. Right-click it and select **Run as administrator**.
{% endstep %} {% step %} **Let the installer check VirtualBox** The installer checks whether VirtualBox is available on your PC. If VirtualBox is not installed, follow the on-screen steps to install it first.
{% endstep %} {% step %} **Set virtual machine resources** Choose the virtual machine name, memory, and CPU cores. Recommended settings: * **Memory**: 2048 MB or more * **CPU**: 2 cores or more
{% endstep %} {% step %} **Select a bridged network adapter** Choose an active network adapter on your PC. Use a bridged adapter so CUBE OS can join your local network.
{% endstep %} {% step %} **Optional: Configure USB passthrough** If you use a Zigbee dongle, select the USB device from the list. If you do not need Zigbee now, skip this step.
{% endstep %} {% step %} **Start the installation** The installer extracts the required files and creates the CUBE OS virtual machine automatically. Wait until the process finishes, then click **Finish**.
{% endstep %} {% endstepper %} ### 3. Boot and access CUBE OS {% stepper %} {% step %} **Wait for CUBE OS to start** After installation, the virtual machine starts automatically in VirtualBox. When boot completes, the console shows the CUBE OS IP address.
{% endstep %} {% step %} **Open the CUBE OS web console** Open a browser on the same network and visit one of these addresses: * `http:///` *
{% endstep %} {% step %} **Use the short local address later** After setup, you can find the short ID on the settings page. You can then use `cube-{short-id}.local` to identify this CUBE OS instance on your LAN.
{% endstep %} {% endstepper %} # Mac This guide shows you how to install CUBE OS on macOS with the One-click Installer. The installer prepares the environment, creates the virtual machine, and starts CUBE OS for you. {% hint style="info" %} This guide follows the current one-click installer flow. Some labels may vary by version. {% endhint %} ### 1. Preparation {% stepper %} {% step %} **Check your Mac** Make sure your Mac is ready for installation: * **OS**: A supported macOS version * **Network**: Stable internet and LAN access * **Permissions**: Administrator access on macOS {% endstep %} {% step %} **Download the installer** Go to the [CUBE OS release page](https://github.com/eWeLinkCUBE/CUBE-OS/releases/latest) and download **One-click Installer for Mac**.
{% endstep %} {% step %} **Zigbee Adapter (Optional)** If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include: > 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 {% hint style="info" %} For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee). {% endhint %} {% endstep %} {% endstepper %} ### 2. Install CUBE OS with the One-click Installer {% stepper %} {% step %} **Open the installer** Find the installer in **Downloads** or your chosen folder. Open the package and follow the on-screen steps.
{% endstep %} {% step %} **Let the installer check VirtualBox** The installer checks whether VirtualBox is available on your Mac. If VirtualBox is not installed, follow the on-screen steps to install it first.
{% endstep %} {% step %} **Set virtual machine resources** Choose the virtual machine name, memory, and CPU cores. Recommended settings: * **Memory**: 2048 MB or more * **CPU**: 2 cores or more
{% endstep %} {% step %} **Select a bridged network adapter** Choose an active network adapter on your Mac. Use a bridged adapter so CUBE OS can join your local network.
{% endstep %} {% step %} **Optional: Configure USB passthrough** If you use a Zigbee dongle, select the USB device from the list. If you do not need Zigbee now, skip this step.
{% endstep %} {% step %} **Start the installation** The installer creates the CUBE OS virtual machine and starts the setup automatically. Wait until the installation completes.
{% endstep %} {% endstepper %} ### 3. Boot and access CUBE OS {% stepper %} {% step %} **Wait for CUBE OS to start** After installation, CUBE OS starts automatically. When boot completes, note the CUBE OS IP address shown on screen.
{% endstep %} {% step %} **Open the CUBE OS web console** Open a browser on the same network and visit one of these addresses: * `http:///` *
{% endstep %} {% step %} **Use the short local address later** After setup, you can find the short ID on the settings page. You can then use `cube-{short-id}.local` to identify this CUBE OS instance on your LAN.
{% endstep %} {% endstepper %} # Add Devices Devices Supported by CUBE The CUBE system currently supports a variety of devices, including Zigbee devices, Matter devices, eWeLink Wi-Fi devices, eWeLink-Remote sub-devices, cameras (such as Onvif and ESP32-CAM models), and Tasmota devices. # eWeLink Wi-Fi Devices Lots of eWeLink-supported devices, specifically, those working via Ethernet and Wi-Fi can be managed on CUBE OS. Most of them work locally with your CUBE OS host, while others need WAN access due to limitations of firmware and chipset design. Gateway devices can also expose supported devices to CUBE OS like a bridge between them. ### To use this feature: 1. A CUBE OS device running `v2.10.3` or later. 2. Internet access. 3. An eWeLink account. {% stepper %} {% step %} ### Open Add Device Open CUBE OS in your browser. Click the `+` button in the top-right corner. Then select `Add Device`.
{% endstep %} {% step %} ### Add eWeLink-linked devices On the **Add Device** page, click `Add eWeLink-linked Devices`. The built-in eWeLink Smart Home add-on will open directly.
{% endstep %} {% step %} ### Sign in to your eWeLink account Click the sign-in button in the top-right corner. Enter your eWeLink account and password to log in.
{% endstep %} {% step %} ### Sync Devices After sign-in, your supported eWeLink Wi-Fi devices will be listed. Click `Sync` to import the devices you want into CUBE OS.
After syncing, go back to **All Devices** to assign rooms and rename devices.
{% endstep %} {% endstepper %} {% hint style="info" %} In `CUBE v2.10.3` and later, eWeLink Smart Home is built in. You do not need to install it from the Docker page first. {% endhint %} # Zigbee Devices Here's a full guide to adding Zigbee devices to your CUBE setup. ## **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). ### **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.
{% 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.
{% 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.
{% endstep %} {% step %} If CUBE does not detect your Zigbee adapter, add it manually by entering the required information: * **Serial Path**: Check the “All Hardware” section on the settings page for the serial port path of the inserted Zigbee adapter. * **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. {% 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 %} {% endstep %} {% step %} Discovered Zigbee devices will then be added to your CUBE OS, ready to assign a room or edit the name. {% 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 to check the compatibility. # Matter (Beta) Devices A guide to add Matter devices to CUBE OS. You can also share Matter devices from other apps following the provided steps. CUBE OS has a built-in Matter Hub (Controller) feature, allowing you to add supported Matter devices to your home locally. {% hint style="info" %} For compatibility, check the **Supported Accessory** [article](/compatibility-check/matter). {% endhint %} ## 1. For New/Factory Reset Devices {% stepper %} {% step %} ### Find Onboarding Code Locate the Matter onboarding code on your product, packaging, or manual. It will look similar to the demo shown below: *Credit: Connectivity Standards Alliance* {% hint style="info" %} Some devices must first be paired with specific apps to generate the code. For instance, older models of Wiz, and most Matter bridges require this step. In such cases, follow the vendor’s guide to obtain the Matter Onboarding Code. {% endhint %} {% endstep %} {% step %} Visit your CUBE OS home page. ![](/files/kcdLmqdtAjfVUt3R8NAQ) Click on the `+` button, and select `Add Device`. {% endstep %} {% step %} ### 3.1 Auto Option Power on your Matter devices and ensure they are in pairing mode following the manufacturer's guides. Then click `Start Setup`. Available devices would be listed on this interface. Select the one you want to add. ### 3.2 Manual Option Click `AddMatter Devices` {% endstep %} {% step %} Enter the onboarding code of your devices obtained from [step 1](#for-new-factory-reset-devices). {% endstep %} {% step %} Fill in your Wi-Fi credentials if you are prompted to do so. Then click `Next`. {% endstep %} {% step %} CUBE OS will start to talk with your devices for setups. {% endstep %} {% step %} When finishing adding your device, CUBE OS will promote a window to name it and assign it to a room. {% endstep %} {% endstepper %} ## 2. For Devices From Other Apps For Matter devices already in use, follow these steps to enable pairing and get the onboarding codes: ### **2.1 Apple Home** #### **2.1.1 Native Matter Devices (e.g. Matter Wi-Fi Plugs)** {% stepper %} {% step %} Open the Home app and find the tile of the device you want to share. {% endstep %} {% step %} Open the device's control panel and tap the gear icon. {% endstep %} {% step %} In the device settings page, scroll to the bottom and tap “Turn On Pairing Mode.” {% endstep %} {% step %} Copy the code and follow the pairing guide on the CUBE OS page. ![](https://appcms.coolkit.cn/wp-content/uploads/2024/06/image2.png) {% endstep %} {% endstepper %} #### **2.1.2 For bridged devices like *****Philips Hue lights with Hue Bridge*****:** {% stepper %} {% step %} Open the Home app and find the tile of the device you want to share. {% endstep %} {% step %} Open the device's control panel and tap the gear icon. {% endstep %} {% step %} In the **device settings** page, **scroll down** to “**Bridge**” and tap it. {% endstep %} {% step %} This will lead you to the settings page of the bridge that connects your devices, scroll to the bottom and tap “Turn On Pairing Mode.” ![](https://appcms.coolkit.cn/wp-content/uploads/2024/06/Apple-%E2%80%93-Bridge-2-1.png) {% endstep %} {% step %} Copy the code and follow the pairing guide on the CUBE OS page. {% endstep %} {% endstepper %} {% hint style="info" %} Please Note: This will bring all supported devices attached to the bridge to your CUBE OS. {% endhint %} ### **2.2 Google Home** #### **2.2.1 Native Matter Devices (e.g. Matter Wi-Fi Plugs)** {% stepper %} {% step %} Open the Google Home app. {% endstep %} {% step %} Select the device you want to add to eWeLink. {% endstep %} {% step %} Tap the gear icon for the settings page. {% endstep %} {% step %} Tap “Linked Matter apps & services.” {% endstep %} {% step %} Wait for it to load and press “Link Matter apps & services.” {% endstep %} {% step %} Copy the code and follow the pairing guide in the eWeLink app. {% endstep %} {% endstepper %}
#### **2.2.2 For bridged devices like *****Philips Hue lights with Hue Bridge*****:** For bridged devices, the steps are identical to those in the above section. ### **2.3 Alexa & SmartThings** Alexa and SmartThings provide official guides to follow: [How to Set Up an Alexa Connected Matter Device with Another Assistant](https://www.amazon.com/gp/help/customer/display.html?nodeId=T6iLWTtbZygaBJnQhg) [SmartThings x Matter Integration](https://support.smartthings.com/hc/en-us/articles/11219700390804-SmartThings-x-Matter-Integration)
# Cameras ## 1. Before you move on Please make sure you have: 1. Connect your camera to your home network either via Ethernet or Wi-Fi. 2. Ensure your camera and your CUBE OS host are on the same LAN (or VLAN, subnet). 3. **Please follow the vendor's official guide to enable the RTSP/ONVIF feature,** and obtain the following information (For SONOFF cameras, you can find the required information on the device's settings page, listed under the `More Settings` entry.): * RTSP Streaming Address, which looks like \`rtsp\://username:password\@192.168.0.201:554/av\_stream/ch0\` * User name and password (if not provided in the link you obtained) ## 2. Add RTSP-enabled cameras {% stepper %} {% step %} ### Access to CUBE OS via browser. Log in to your CUBE OS host, click on the `+` button, then select `Add Device`.
{% endstep %} {% step %} ### Add RTSP Camera Select Add `RTSP Camera`.
{% endstep %} {% step %} ### Fill credentials Give your camera a name, and input the stream address obtained from [Step 1](#id-2.-add-rtsp-enabled-cameras). If the address does not contain authentication information, please input the RTSP Username and Password manually.
{% endstep %} {% step %} ### Go Live Back to the All Devices page, click on the camera to stream.
{% endstep %} {% endstepper %} ## 3. Add ONVIF Cameras {% stepper %} {% step %} ### Access to CUBE OS via browser Log in to your CUBE OS host, click on the `+` button, then select `Add Device`.
{% endstep %} {% step %} ### Discover your cameras Click on the Start Setup to discover cameras on your local network.
{% endstep %} {% step %} ### Fill in credentials Find the listed devices you want to add, and click `Add`, then fll in the authentication information you obtained from [Step 1](#id-3.-add-onvif-cameras) if there is any.
{% endstep %} {% step %} ### Go Live Back to the All Devices page, click on the camera to stream.
{% endstep %} {% endstepper %} ## 4. Multi-View for Cameras {% hint style="info" %} You can only view 10 cameras at the same time. The actual experience depends on your CUBE OS' performance. {% endhint %} {% stepper %} {% step %} Visit your CUBE OS' web console, and navigate to the All Devices tab (the default one). And select a camera to start, a pop-up will show in the corner. Please wait until it manages to stream.
{% endstep %} {% step %} On the pop-up, click on the Multi-View icon – the one in the right-button corner {% endstep %} {% step %} Navigate to the cameras you want to stream from the list, then click the Add button to add them to the main panel to view. And remove any with the close button .
{% hint style="info" %} You can add up to four cameras to the main panel. {% endhint %} {% endstep %} {% step %} To zoom in on any camera view, click the Zoom icon on the main panel. On the zoomed view, you can also quickly switch between cameras from the dropdown list.
{% endstep %} {% endstepper %} # eWeLink-Remote Sub-Devices You can transform the CUBE OS into an eWeLink Remote Gateway, allowing integration of sub-devices like the [**S-MATE 2**](https://sonoff.tech/en-us/products/sonoff-s-mate-extreme-switch-mate/58) **or** [**R5**](https://sonoff.tech/en-us/products/sonoff-switchman-r5-scene-controller/58). {% hint style="info" %} **What is the eWeLink-Remote control？** eWeLink-Remote Control is a unique new remote control solution for SONOFF devices. It provides a more convenient, more reliable, and longer-distance control way for your home appliances. About the details, please view: {% endhint %} ## 1. Enable eWeLink-Remote Control in Pilot {% stepper %} {% step %} From the left sidebar, go to **Pilot Features**.
{% endstep %} {% step %} Find **eWeLink-Remote Control** and click **Learn More**. Toggle the switch to **enable** this feature.
{% endstep %} {% step %} Once enabled, CUBE OS will activate the eWeLink-Remote protocol and prepare to receive signals from compatible devices. {% endstep %} {% endstepper %} ## 2. Add an eWeLink-Remote Sub-Device (Using R5 as Example) {% stepper %} {% step %} Go back to the **Home** page. Click the **“+”** icon in the top-right corner. Select **eWeLink-Remote Sub-Devices** from the list.
{% endstep %} {% step %} Click **Pair** to enter pairing mode.
{% endstep %} {% step %} On your **SONOFF R5**, trigger any button once. This will send a pairing signal. {% endstep %} {% step %} Once pairing is successful, the R5 will appear in your device list.
{% endstep %} {% endstepper %} ## 3. Configure Smart Scenes for eWeLink-Remote Sub-Devices After adding your eWeLink-Remote sub-device, you can link it to other smart devices through **Smart Scenes**. {% stepper %} {% step %} Go to the **Scene** page.
{% endstep %} {% step %} Under the **Smart Scene** tab, click **Add Scene**.
{% endstep %} {% step %} Set up the **If** condition: **Add Smart Device → SONOFF R5 → Enable Wireless Button → Channel 1 → Click → Done.** {% endstep %} {% step %} Set up the **Then** action: **Add Smart Device → SONOFF B05-BL → Enable Switch → On → Done.** {% endstep %} {% step %} Save your Smart Scene.
{% endstep %} {% endstepper %} Now, when you press the R5 button, the connected B05-BL light will turn on automatically. # Feature List Here's a quick comparison between different installations of CUBE; they only present the current status instead of a roadmap. Features in the early stage may not all arrive in the final version for all installation methods.
No.FeatureRaspberry Pi (4B/5)Virtual MachineNotes
1Zigbee Cluster Support⚠️ (Zigbee dongle needed)⚠️ (Zigbee dongle needed)

Supported Zigbee clusters:

Zigbee Compatibility

2Matter Bridge⚠️⚠️

Under certification testing, may encounter issues on certain Matter fabrics.

Supported Matter clusters:

Matter Compatibility

3Matter Hub⚠️⚠️

Requires target platform with Bluetooth capability

Supported Matter clusters:

Matter Compatibility

4Remote Access✅✅Implemented via PWA (Progressive Web App). Chrome and Safari are recommended.
5Push Notifications⚠️⚠️Only available via eWeLink CUBE CAST Dashboard
6CAST Dashboards✅✅
7Docker & Add-ons✅✅Stored locally on the target platform
8Backup / Restore✅✅
9Scenes (Smart / Manual)✅✅
10Groups / Rooms✅✅
11Firmware OTA✅✅Supports OTA for both CUBE and Zigbee sub-devices
12Turbo Mode (Zigbee)✅✅
# Matter Bridge - Link Apps CUBE OS has a built-in Matter Bridge (BETA), which will expose supported devices from your host to Matter-enabled platforms like Apple Home, Google Home, SmartThings, and Alexa. So you can manage your home devices via preferred voice assistants provided by these platforms. Matter allows you to add your CUBE OS as a bridge device to multiple platforms. The steps would vary between a fresh setup and a secondary setup. Here's a guide for Apple Home; other platforms usually have the same procedures. We will soon add step-by-step guides for all mainstream platforms.
Apple Home & Siri/pages/LXWWGAIKbHx889npEE73
Amazon Alexa/pages/T8DtCUWtgAqpebKnKiMj
Google Assistant/pages/E8yTXfI3ofyUDHxfKcmF
SmartThings/pages/mna6WS41rLLGlwErs0Nr
# Amazon Alexa ## 1. Fresh setup Use the Amazon Alexa app to scan the QR code from CUBE Matter Bridge. {% hint style="info" %} Make sure Alexa has permissions for **Camera** and **Local Network**. {% endhint %} {% stepper %} {% step %} ### Enable Matter Bridge in CUBE OS Open CUBE OS in a browser. Click the **Matter** icon in the side panel. Follow the on-screen guide to enable **Matter Bridge**.
You should see: * A **QR code** (for pairing) * A **numeric setup code** (useful if scanning fails) {% endstep %} {% step %} ### Scan the QR code in the Alexa app Open the **Amazon Alexa** app. Go to **Devices**. Tap **+** → **Add Device**. Select **Matter**, then choose **Scan QR code** and scan the QR code shown in CUBE OS. {% endstep %} {% step %} ### Finish setup and wait for devices to sync Follow the Alexa flow to complete the setup. After pairing, Alexa will sync devices exposed by the CUBE bridge. You can rename devices and assign rooms in Alexa. {% endstep %} {% endstepper %} {% embed url="" %} # Apple Home & Siri ## 1. Fresh setup {% stepper %} {% step %} ### Enable Matter Bridge Please visit CUBE OS via browser. Click on the Matter logo on the side panel, and follow the guide to enable the feature.
Shortly, the page should show a QR Code and a line of numbers as keys to pair your device with other platforms. {% endstep %} {% step %} ### Scan on App Pick up your iPhone or iPad and open the system Camera, aiming at the QR Code. When a yellow promotion came up labeled "Open in Home", tap it.
{% endstep %} {% step %} ### Finish in Apple Home app iOS/iPadOS will redirect you to the Apple Home app to add your devices. Feel free to rename each devices and assign rooms for them in the app.
{% endstep %} {% step %} ### Try out Siri commands When you are done with naming your devices, give it a shot with Siri.
{% endstep %} {% endstepper %} ## 2. Secondary Setup If you have linked with a platform through Matter. You will need to generate the setup codes from that platform's app. ### **2.1 Apple Home** {% stepper %} {% step %} Open the Home app and find the tile of the device you want to share. {% endstep %} {% step %} Open the device's control panel and tap the gear icon. {% endstep %} {% step %} In the **device settings** page, **scroll down** to “**Bridge**” and tap it. {% endstep %} {% step %} This will lead you to the settings page of the bridge that connects your devices, scroll to the bottom and tap “Turn On Pairing Mode.” ![](https://appcms.coolkit.cn/wp-content/uploads/2024/06/Apple-%E2%80%93-Bridge-2-1.png) {% endstep %} {% step %} Copy the code and follow the pairing guide on the CUBE OS page. {% endstep %} {% endstepper %} {% hint style="info" %} Please Note: This will bring all supported devices attached to the bridge to your CUBE OS. {% endhint %} # Google Home ## 1. Fresh setup Use the Google Home app to scan the QR code from CUBE Matter Bridge. {% hint style="info" %} Make sure Google Home has permissions for **Camera** and **Local Network**. {% endhint %} {% stepper %} {% step %} ### Enable Matter Bridge in CUBE OS Open CUBE OS in a browser. Click the **Matter** icon in the side panel. Follow the on-screen guide to enable **Matter Bridge**.
You should see: * A **QR code** (for pairing) * A **numeric setup code** (useful if scanning fails) {% endstep %} {% step %} ### Scan the QR code in the Google Home app Open the **Google Home** app. Tap **+** → **Set up device**. Choose **Matter-enabled device**. Scan the QR code shown on the CUBE OS Matter Bridge page. {% endstep %} {% step %} ### Finish setup and wait for devices to sync Follow the Google Home flow to complete the pairing. After pairing, Google Home will sync devices exposed by the CUBE bridge. You can rename devices and assign rooms in Google Home. {% endstep %} {% endstepper %} {% embed url="" %} # SmartThings ## 1. Fresh setup Use the SmartThings app to scan the QR code from CUBE Matter Bridge. {% hint style="info" %} Make sure SmartThings has permissions for **Camera** and **Local Network**. {% endhint %} {% stepper %} {% step %} ### Enable Matter Bridge in CUBE OS Open CUBE OS in a browser. Click the **Matter** icon in the side panel. Follow the on-screen guide to enable **Matter Bridge**.
You should see: * A **QR code** (for pairing) * A **numeric setup code** (useful if scanning fails) {% endstep %} {% step %} ### Scan the QR code in the SmartThings app Open the **SmartThings** app. Tap **+** to add a device. Choose the **Partner devices** option, select **Matter** and then scan. Scan the QR code shown on the CUBE OS Matter Bridge page. {% endstep %} {% step %} ### Finish setup and wait for devices to sync Follow the SmartThings flow to complete the pairing. After pairing, SmartThings will sync devices exposed by the CUBE bridge. You can rename devices and assign rooms in SmartThings. {% endstep %} {% endstepper %} {% embed url="" %} # Automation and Scene Learn how to create automations and manual scenes in CUBE OS to make your smart home more intelligent and autonomous. CUBE OS allows you to create **two types of automations** with your connected devices: * **Manual Scenes** - triggered manually by the user. * **Smart Scenes** - triggered automatically based on conditions or device states. Both types are created in the same interface, but differ in how they are **activated**. {% hint style="success" %} All automations in CUBE OS run and are **stored locally**, ensuring fast, private, and reliable device interactions without relying on the cloud. {% endhint %} ## 1. Manual Scenes A **Manual Scene** is triggered directly by you - not by sensors, buttons, or schedules.\ It’s ideal for actions you want to activate on demand, like turning on a set of lights or running a "movie mode". ### Example: Turn On a Wi-Fi Lamp and Set Its Color to Blue {% stepper %} {% step %} Go to **Scene** and click the **"+"** button to create a new scene.
{% endstep %} {% step %} Under **IF**, select **Tap to Run**.
{% endstep %} {% step %} Under **THEN**, choose **Smart Devices → Wi-Fi Lamp**. {% endstep %} {% step %} In the lamp options, set: **Switch** → On; **Color** → Blue
{% endstep %} {% step %} Save the scene. Now, whenever you manually run this scene, your lamp will turn on and change to blue. {% endstep %} {% endstepper %} ## 2. Smart Scenes A **Smart Scene** runs automatically when certain conditions are met, for example, when a motion sensor is triggered or a temperature threshold is reached. ### Example: Turn On the Lamp When R5 Button is Pressed {% stepper %} {% step %} Go to **Scene → Add Scene**. {% endstep %} {% step %} Under **IF**, select **Smart Device → SONOFF R5 Button → Click**.
{% endstep %} {% step %} Under **THEN**, select **Smart Devices → Wi-Fi Lamp → Switch On → Set Color Blue**.
{% endstep %} {% step %} Save the scene. Now, pressing the Zigbee button will automatically turn on your lamp. {% endstep %} {% endstepper %} {% hint style="info" %} You can combine multiple IF and THEN conditions to create complex automations - for example, adding a time condition (Only at night) to the same scene. {% endhint %} ## 3. View Automation History CUBE OS records when each automation was executed.\ To check automation history: {% stepper %} {% step %} Open the automation you want to review.
{% endstep %} {% step %} Click the **History** icon. {% endstep %} {% step %} Use the **filter** to view events by time or condition. {% endstep %} {% endstepper %} This helps you monitor whether automations are working as expected. # Cast Dashboard Cast allows you to create dashboards of your devices and scenes, arm and disarm smart security, and receive your security notifications. On the settings page, simply drag and drop the icons to sort your devices and scenes. Set an access PIN code for the dashboard to prevent unexpected switching. ## **Create your CAST dashboard** {% stepper %} {% step %} Please visit CUBE OS via browser. Click on the CAST menu on the left side.
{% endstep %} {% step %} Click the '+' button to create a new dashboard. {% endstep %} {% step %} Enter a name for the dashboard, select your devices, manual scenes, and charts.
{% endstep %} {% step %} On the settings tab, select the widgets you need. * For the Custom text, please enter your text in the text box. * Extended CAST pad layouts for a more flexible dashboard experience. * Select a background color for the dashboard. * Set a PIN code for the dashboard if necessary. (If set, when you enter or exit the dashboard, you need to enter the PIN code.)
{% endstep %} {% step %} In the preview area, drag and drop the tiles to arrange them. And click the resize icon to change between different sizes.
{% endstep %} {% step %} Click the Save button, and the dashboard is created. {% endstep %} {% step %} You can visit CUBE's IP/cast to use the dashboard on any web browser (on PC or phone/pad).
{% endstep %} {% endstepper %} # Remote Access & Notification CUBE OS has a built-in feature allowing you to access your smart home devices remotely with a link. This guide will walk you through the initial setup. Before moving forward, please make sure you enable the push notification feature of the devices you have on the device settings page.
{% stepper %} {% step %} Please visit CUBE OS via browser. Click on Pilot Features, and then select Remote Features.
{% endstep %} {% step %} Toggle on Remote Features.
{% hint style="info" %} The features rely on WAN access, please ensure your CUBE OS has proper access to the internet. {% endhint %} {% endstep %} {% step %} CUBE OS will generate two links to visit your CUBE OS web console and the CAST dashboards. Feel free to copy and save them in your bookmarks.
{% hint style="danger" %} Please secure your remote access link and PIN to your CUBE OS! {% endhint %} {% endstep %} {% step %} Copy the link for eWeLink CUBE CAST and open the link on your phone's web browser (Safari and Chrome are recommended for full features) {% hint style="warning" %} When using Remote Access on your phone, only the CAST dashboard can be accessed currently. {% endhint %} {% endstep %} {% step %} Add the web page to your Home Screen. On Safari, click on the share button in the middle of the bottom tab.
{% endstep %} {% step %} For Chrome, tap on the button next to the address bar, and select "Add to home screen".
Chrome may give you option to add CAST as a shortcut or an app, select Install.
{% endstep %} {% step %} Close your browser, and click on the CAST icon you just added to your Home Screen.
The system may ask you permission for notification, tap Allow. If your phone didn't ask for permission, please click on the Alarm icon, and click on the banner that says "No notifications without system permission". This move will force a trigger to ask for notification permission.
{% endstep %} {% step %} Once you are allowed permission, you are free to explore all the features. {% endstep %} {% endstepper %} {% hint style="warning" %} The Remote Features use web app technology, and functionality may vary based on your phone's operating system and browser. As previously noted, Safari and Chrome delivered better performance during testing. {% endhint %} # Docker & Add-on By downloading different Add-ons in Docker, you can enable CUBE OS to gain more capabilities and become more comprehensive and reliable.
The following are 2 examples to show how to use the Add-on features on CUBE OS. ## eWeLink Smart Home Sync eWeLink-supported devices to CUBE and control them. Tutorial refers to: [eWeLink Wi-Fi Devices (LAN Capable)](/getting-started/add-devices/ewelink-wi-fi-devices). ## Node-RED Low-code programming for event-driven applications. {% stepper %} {% step %} Install and run the Node-Red Add-on.
{% endstep %} {% step %} Click 'RUN' to open the settings, select network as 'host', and fill in other parameters according to your needs, then tap 'RUN'.
{% endstep %} {% step %} Wait a while and open a new browser tab to visit the Node-Red page, the default URL is ihost.local:1880 or IP of iHost:1880 (for example, 192.168.1.232:1880, you may find the IP on your router’s management page.)
{% endstep %} {% endstepper %} # Security System Learn how to configure and use the built-in security modes in CUBE OS to protect your smart home. CUBE OS includes a **Security System** feature that lets you use your connected sensors - such as motion detectors, door/window sensors, or other triggers - to monitor your home and trigger alarms or automations. If your device hardware supports it, the built-in speaker can act as a **siren**, while other systems can trigger alerts or automations through configured actions. ## 1. Security Modes CUBE OS provides **three pre-defined modes** to match your daily routines:
ModeDescription
Home ModeWhen you’re home and only want partial monitoring (e.g., door sensors active).
Away ModeWhen you’re not home - all selected sensors will trigger alarms.
Sleep ModeWhen you’re at home but asleep, typically only perimeter sensors remain active.
In this example, we’ll focus on **Away Mode**, which is used when no one is home. ## 2. Configure Away Mode {% stepper %} {% step %} Open the **Security System** from the main menu. {% endstep %} {% step %} Click on the **Away Mode** card to open the configuration panel.
{% endstep %} {% step %} Set up the following options: **Siren Type** – choose between built-in or linked siren devices. **Volume** – adjust the alarm loudness. **Trigger Sensors** – toggle on the sensors you want to include. {% endstep %} {% endstepper %} Active sensors will appear on the right side of the screen.\ Once enabled, these sensors will automatically trigger the alarm when motion is detected or a door/window is opened. ## 3. What Happens When an Alarm is Triggered When the system is in **Away Mode**, and any of the selected sensors is activated: 1. The **siren** will sound immediately (if supported). 2. The system can trigger linked **automations** - for example: * Sending a notification * Turning on all lights * Closing blinds * Recording video via a connected camera # Manage Your Device In this article, you will learn about devices in CUBE OS, and how to manage them to fit your needs. ## 1. Identify your device CUBE OS utilizes corner labels on the device cards to identify how the device is connected. You could see the following types:
## 2. Rename Your Devies {% stepper %} {% step %} Click on the device card you want to rename. {% endstep %} {% step %} Click on the Gear icon.
{% endstep %} {% step %} Click on the Edit icon, then enter a new name for your device.
{% endstep %} {% step %} Click on the Save icon.
{% endstep %} {% endstepper %} ## 3. Change Device type & add pictures {% stepper %} {% step %} On the basic info tab, you can change the device type.
{% endstep %} {% step %} Or you can customize its icon.
{% endstep %} {% endstepper %} ## 4. Remove devices Scroll down to the bottom of the edit page, and you can find the 'Delete Device' button.
## 5. Assign Room On the Shortcuts tab, you can assign the device to a specific location.
# Backup & Restore CUBE OS includes a built-in **Backup & Restore** feature that helps you safeguard your system configuration, device data, and automation settings.\ You can create a manual backup at any time or configure scheduled automatic backups, ensuring your environment is always protected. {% hint style="warning" %} eWeLink CUBE has five backup slots: four manual and one automatic backup. The earliest backup will be overwritten when the storage is insufficient. The system will be temporarily frozen during the backup process. Do not power off or reboot your eWeLink CUBE during backup for backup integrity. {% endhint %} ## Accessing the Backup Settings {% stepper %} {% step %} Navigate to **Settings** from the left sidebar. {% endstep %} {% step %} Scroll down to the **Feature** - **Backup & Restore** tab.
{% endstep %} {% step %} Here you can view your current backup status, create a new backup, or restore from a previous one. {% endstep %} {% endstepper %} # Reset Password If you forget your CUBE OS password, please follow this guide to reset it. {% hint style="info" %} ### Preparation * For Raspberry Pi installation, please connect an external monitor. * For virtual machine installation, ensure you can access the screen output via a client device. {% endhint %} {% stepper %} {% step %} On the log-in page, click `Forget Password`.
{% endstep %} {% step %} Click `Send Verification Code.`
{% endstep %} {% step %} Access your CUBE OS backend console via the external monitor or virtual machine manager, and find the code printed.
{% endstep %} {% step %} Enter the code to your CUBE OS web console, and set a new password.
{% endstep %} {% step %} Click Log in to finish the steps. You will be redirected to the All Devices page with a promotion saying "Success".
{% endstep %} {% endstepper %} # Matter In the Matter standard, a **Cluster** represents a group of device capabilities and behaviors, such as turning a light on/off, adjusting brightness, reporting temperature, or detecting occupancy.\ Each device exposes one or more clusters, which define what the device can do and how it communicates with a Matter controller or Matter Bridge. Understanding supported clusters helps you determine which device types can be integrated and what features will be available inside **CUBE OS**. *** ## Matter Bridge **Supported Matter clusters:** 1. On/Off Plug-in Unit 2. Dimmable Light 3. Color Temperature Light 4. Occupancy Sensor 5. Contact Sensor 6. Humidity Sensor 7. Temperature Sensor 8. Generic Switch 9. Thermostat 10. Window Covering 11. Light Sensor 12. Smoke & CO Alarm (covering smoke and carbon monoxide sensors) 13. Air Quality Sensor 14. Room Air-conditioner 15. Fan *** ## **Matter Hub** **Supported Matter clusters:** 1. Switches and plugs (On/Off Plug-in Units) 2. Lights, including: * Dimmable Light * On/Off Light * Extended Color Light 3. Bridge-type devices * Devices connected under a Matter Bridge, including: * Switches * Plugs * Light types (Dimmable Light, On/Off Light, Temperature Light, Extended Color Light) # Zigbee CUBE OS acts as a **local Zigbee gateway**, allowing you to connect, manage, and bridge a wide range of Zigbee subdevices, including switches, sensors, lights, and environmental monitors. To achieve stable Zigbee network performance, CUBE OS relies on **compatible Zigbee dongles** that serve as radio coordinators. Once a supported dongle is connected, CUBE OS can pair and manage multi-brand Zigbee devices through standardized Zigbee **clusters**, which define the capabilities and functions of each device type. The tables below list the supported Zigbee dongles and the Zigbee clusters currently compatible with CUBE OS. *** ## Supported Zigbee Dongles * SONOFF ZBDongle-MAX * SONOFF ZBDongle-PMG24 * SONOFF ZBDongle-LMG21 * SONOFF ZBDongle-E * SONOFF ZBDongle-P * [Other supported adapters ](https://darkxst.github.io/silabs-firmware-builder/)contributed by developer **@darkxst** *** ## Supported Zigbee Clusters For the full list of clusters and compatibility details, please click here:\ [**https://cube-web.ewelink.cc**](https://cube-web.ewelink.cc) # Change Log ## v2.12.0 - Jul. 07 2026 ### What's New? 1. **New Device Support** * Added support for SONOFF MINI-ZB1GP / MINI-ZB1GSP single-channel Zigbee smart switches with electricity monitoring. 2. **Expanded Matter Hub Device Support** * Matter Hub now supports the following Matter device types: * Temperature Sensor * Contact Sensor * Occupancy Sensor * Light Sensor * Air Quality Sensor * Smoke CO Alarm * Generic Switch * Dimmable Plug-in Unit 3. **Enhanced eWeLink-linked Device Sync Support** * Eligible Zigbee sub-devices connected through SONOFF NSPanel Pro 86-Relay and Bridge-M can now be synced to eWeLink CUBE via either the eWeLink Smart Home Add-on or the built-in "Add eWeLink-linked Devices" feature. 4. **SONOFF TRVZB Enhancements** * Optimized the temperature graph in CUBE CAST with a dynamically adjusted axis based on temperature data. ### Bug Fixes 1. Fixed an issue where a blank pop-up box was displayed when configuring temperature and humidity reporting for IKEA air quality sensors. 2. Fixed an issue where SONOFF SNZB-02M could incorrectly show air pressure comfort as out of range when no air pressure comfort range was configured. 3. Fixed an issue where the Node-RED Add-on could fail to install or update on some devices. *** ## v2.11.0 - Jun. 16 2026 This release expands compatibility for multiple SONOFF devices and support for Matter Bridge camera capabilities, with improved room temperature sensing for SONOFF TRVZB. Please take a moment to read through the notes before updating to this version. ### What's New? 1. **New Device Support** * Added support for the following SONOFF devices: * SONOFF SNZB-06P24 24GHz presence sensor. * SONOFF SNZB-03PR2 motion sensor with illuminance reporting. * SONOFF SWV-ZF2U / SWV-ZF2E dual-channel smart water valve. * SONOFF BASIC-ZB1GSP smart plug with energy monitoring. 2. **Matter Bridge Camera Support** * Syncing eligible cameras to the added Matter platforms via Matter Bridge is now available, with video and audio streaming. 3. **SONOFF TRVZB Enhancements** * SONOFF SNZB-02B can now be used as an external sensor for SONOFF TRVZB, providing more accurate room temperature readings. ### Bug Fixes 1. Fixed an issue where the energy consumption graph failed to load for Zigbee plugs synced to CUBE via eWeLink Smart Home Add-on. 2. Fixed an issue where SONOFF Zigbee Dongles could not be detected or configured properly by CUBE when connected to Raspberry Pi 4. *** ## v2.10.3 - May 27 2026 This release introduces built-in eWeLink Smart Home for easier device syncing, One-click Installation on Mac, and adds support for running CUBE OS in Docker environments for more flexible deployment options. Please take a moment to read through the notes before updating to this version. ### What's New? 1. **Built-in eWeLink Smart Home for Easier Device Sync** * A simpler way to sync eWeLink-linked devices is now available in CUBE. Sign in with your eWeLink account from **Home > Add Device** to sync and manage eligible devices directly in CUBE, without installing the eWeLink Smart Home Add-on.\ \&#xNAN;*Note: Existing add-on devices will continue to work independently.* 2. **Docker Deployment Support** * CUBE OS can now run in Docker environments, giving users more flexible deployment options.\ For Docker-based deployments, the following system-level features are not available: * Docker (Add-ons) * Pilot Features > Bluetooth Speaker * Settings > Gateway Info > Version Update * Settings > Reboot & Shutdown * To update a Docker-based deployment, pull the latest Docker image. 3. **Expanded One-click Installation Support** * Added support for one-click installation of CUBE on Mac. *** ## v2.10.2 - May 18 2026 This release introduces SONOFF Dongle firmware management, expanded deployment options, and new device support, while further improving Matter Bridge compatibility, Zigbee device behavior, and overall system stability. Please take a moment to read through the notes before updating to this version. ### **What's New？** 1. **SONOFF Dongle Firmware Management** * Added automatic detection for connected Zigbee Dongles. Unsupported SONOFF Dongles can now be upgraded to recommended stable Zigbee firmware versions with one click: * Ember-based Dongles with firmware versions earlier than v7.4.5 will be upgraded to v8.0.2. * ZStack-based Dongles with firmware versions earlier than v20250321 will be upgraded to v20250321. * After upgrading CUBE to v2.10.2, connected SONOFF Dongles will be automatically upgraded to the recommended stable firmware versions. Non-SONOFF Dongles must be upgraded using their official flashing tools to ensure proper connection and device control. * Optimized Zigbee offline detection behavior: * Router devices report within 1 minute * End devices report within 1 hour * Devices exceeding the reporting interval will appear offline until triggered again. 2. **Expanded Deployment Support** * Added support for one-click installation of CUBE on Windows. 3. **Matter Bridge Enhancements** * Upgraded the CUBE Matter Bridge SDK to v1.5.0. * Optimized the default device naming when syncing devices to SmartThings and Alexa via Matter Bridge. 4. **SONOFF TRVZB Enhancements** * Added Adaptive Mode for SONOFF TRVZB, configurable in the eWeLink App, to help maintain a more stable room temperature. 5. **New Device Support** * Added support for SONOFF Hydro ONE Zigbee Smart Water Valves (SWV-ZFU / SWV-ZFE) and SONOFF Hydro ONE Lite Zigbee Smart Water Valves (SWV-ZNU / SWV-ZNE). * Added support for SONOFF MINI-ZBD Smart Dry Contact Module. 6. **Zigbee Device Compatibility Improvements** * Optimized power-on behavior configuration for third-party Zigbee devices. 7. **Shutdown Feature** * Added a shutdown option in the CUBE Web settings page. ### **Bug Fixes** 1. Fixed an issue where Raspberry Pi 5 Rev1.1 boards could fail to boot properly. 2. Fixed an issue where devices could fail to sync to Alexa via Matter Bridge. 3. Fixed timeout issues when adding ONVIF / RTSP cameras. 4. Fixed the issue where the status of the HOBEIAN ZG-102ZM vibration sensor did not update. 5. Fixed the issue where the historical data chart of Zigbee plugs was not displayed. *** ## v2.9.0 - Feb. 13 2026 This release expands eWeLink Smart Home Add-on compatibility and device support, with notable improvements to Zigbee reliability, automation stability, and device control flexibility. Please take a moment to read through the notes before updating to this version. ### **What's New?** 1. **Expanded eWeLink Smart Home Add-on Device Support** * Added support for syncing eligible air quality monitors to CUBE via eWeLink Smart Home Add-on, including: * **SONOFF SAWF-07P** * **SONOFF SAWF-08P** * Added support for SONOFF SNZB-04PR2 Door/Window Sensor. 2. **Sensor Accuracy & Calibration Enhancements** * Added an option to adjust temperature and humidity offsets for **SONOFF SNZB-02P** to improve reading accuracy. 3. **SONOFF TRVZB Enhancements** * Boost Mode and Temp. Override Mode can now be enabled or disabled directly from **CUBE CAST.** * **SONOFF SNZB-02LD** can now be used as an external sensor for more accurate room temperature and humidity measurements. 4. **Zigbee Reliability Improvements** * Optimized Zigbee offline detection logic to identify device disconnections faster and improve overall control reliability. (Note: Due to reporting interval limitations, legacy **SNZB-01 / SNZB-02 / SNZB-03 / SNZB-04** sensors are excluded from this optimization) 5. **Device Control & Calibration Enhancements** * Added an option to configure extra travel time for **SONOFF MINI-ZBRBS** to ensure blinds fully open and close during manual calibration. * Added stepping control support for **SONOFF MINI-ZB2GS**, allowing external switch presses to cycle through predefined relay states for more flexible multi-state control scenarios. * Added a manual calibration option to **SONOFF MINI-ZBDIM** dimming calibration. ### **Bug Fixes** 1. Fixed a bug where input capability of **Frient IOMZB-110** module was missing in eWeLink CUBE. 2. Resolved a control issue with **Tuya/Moes AM43-0.45/40-ES-EZ** curtain motor. 3. Fixed an issue where **Paulmann Gen2 RGB Remote** could not be used as a scene trigger. 4. Corrected an issue where the **SONOFF R5 remote** did not trigger automations as expected after restoring from a backup. 5. Fixed an issue where scenes had to be re-enabled after an eWeLink CUBE reboot to run again. 6. Fixed an intermittent issue where the **Matter Bridge** could become unresponsive on third-party platforms when synchronizing a large number of devices. 7. Optimized the logic for synchronizing water leak sensors via the **Matter Bridge**. *** ## v2.8.1 - Nov. 27 2025 We're excited to announce that **CUBE OS has now transitioned from beta to its official release version**. From this version onward, **CUBE OS version numbers will stay aligned with iHost releases** for consistent updates and feature improvements. This update expands Matter Bridge and eWeLink Smart Home Add-on support, introduces new features for SONOFF TRVZB, enhances scene organization, and improves overall usability. Please take a moment to read through the notes before updating to this version. ### What's New? 1. **Expanded Matter Bridge Device Support** * Added support for syncing additional Matter-defined device types via Matter Bridge, including: * Light Sensor * Smoke & CO Alarm (covering smoke and carbon monoxide sensors) * Air Quality Sensor * Room Air-conditioner * Fan 2. **New Features for SONOFF TRVZB** * Added two new temporary modes for SONOFF TRVZB: * Boost Mode: heats the room quickly for a short period. * Temp. Override Mode: temporarily maintains a set temperature. 3. **Scene Enhancements** * Easily create custom labels and assign scenes to existing labels. 4. **New features for ONVIF compatible Cameras** * ONVIF-compatible cameras now support using "Motion Detected" and "Occupancy Detected" as scene triggers. 5. **Expanded eWeLink Smart Home Add-on** * Added support for syncing eligible devices to CUBE via eWeLink Smart Home Add-on, including: * SONOFF Mini-RBS * Virtual Devices (covering switches and buttons) * Sub-devices from ZBBridge-U: SONOFF S60ZB, SNZB-02LD/SNZB-02WD, Mini-ZBRBS, SWV 6. **Device List Enhancements** * You can now hide offline devices from the Home page device list for a cleaner, more focused view. 7. **Data Visualization Enhancements** * Temperature and humidity graphs now support minute-level data for more detailed insights. ### Bug Fixes 1. Fixed an issue where scene notifications were not received via CUBE CAST during remote access. 2. Fixed compatibility issues with Tuya TS0001 Fingerbot. 3. Fixed Matter Bridge issues: * Fixed an issue where the Matter Bridge repeatedly went offline. * Fixed a problem where adding more than 10 devices prevented newly added devices from being synchronized through Matter Bridge. * Fixed an issue where the Matter Fabric displayed as empty. * Fixed an issue where deleting a device from CUBE did not correctly remove the corresponding device from the third-party Matter platform. 4. Fixed SONOFF TRVZB issues: * Fixed an issue where Boost Mode and Temp. Override Mode failed to execute correctly. * Fixed an issue where scene actions incorrectly allowed selecting Temp. Override Mode. * Fixed an issue where adjusting the Boost Time while in Boost Mode caused inconsistent or incorrect timing. * Fixed a bug where minute-level data of temperature and humidity graphs could not be properly displayed. * Fixed an issue where the target temperature displayed in CAST exceeded the allowed range. * Fixed an issue where the TRV's target temperature for Boost/Temp. Override Mode could not be synchronized or displayed correctly. *** ## v0.5 - Aug. 27 2025 This update brings extended Zigbee dongle compatibility, ONVIF camera enhancements, and notable improvements for CUBE CAST. Please take a moment to read through the notes before updating to this version. ### What's New? 1. **Expanded Zigbee Dongle Compatibility** * Added support for SONOFF ZBDongle-P and SMLIGHT SLZB-06 Zigbee Coordinator. * Currently tested and verified compatible dongles: * SONOFF ZBDongle-E / P * SMLIGHT SLZB-06 / 06M * SkyConnect Zigbee (EZSP) 2. **ONVIF Camera Support** * Added automatic discovery of ONVIF-compatible cameras. * Supported PTZ (Pan-Tilt-Zoom) control. * Tested and verified compatible devices (with required firmware versions): * SONOFF CAM-PT2: FW ≥ 1.0.6 * SONOFF CAM-B1P: FW ≥ 1.0.2 3. **CAST Enhancements** * Extended CAST pad layouts for a more flexible dashboard experience. ### Bug Fixes 1. Fixed an issue where CUBE OS failed to boot on Raspberry Pi 5 and could not perform OTA updates. 2. Corrected inaccurate data display in thermostatic radiator valves' trend graphs. 3. Fixed a bug where scenes triggered by power thresholds failed to execute properly. 4. Fixed an issue where device status updates on CAST required a manual browser refresh. *** ## v0.4 - Jun. 19 2025 ### What’s New? 1. Standalone installation support for: * Raspberry Pi 4B / 5 * -x86\_64 Virtual Machines (e.g., VirtualBox, VMware) * NAS devices (compatible models) 2. Zigbee device support via USB dongles (e.g., SONOFF ZBDongle-E) 3. Matter Hub & Matter Bridge 4. Remote Access/Push Notifications via PWA 5. Docker & Add-ons support 6. Scenes, Groups, OTA, CAST Dashboards, and more\ For more details:\ ### How to Try 1. Download the image that fits your environment (Raspberry Pi / VM / NAS)\ `raspberrypi4_64_prod.img.xz` for Raspberry Pi\ `sdcard.vdi.xz/sdcard.vmdk.xz` for VMs, NAS devices 2. Flash and install by following these guides:\ 3. Join our [Discord server](https://discord.gg/67Ybdn23rS) to get support and share feedback *** ## v0.2 - Dec. 31, 2024 ### What’s New? * Remote Access rolls out for Pilot Features. When enabled, it allows remote access to CubeOS' web console and CAST via secured links. * CAST can be installed as a web app with remote links. The app enables notifications for scene executions, Smart Security events, switch and plug toggles, and sensor triggers, including: * Motion detection * Presence detection * Open window detection * Gas detection * Water leakage detection * Smoke detection * Press actions * Users can now change the password for the web console. * A new MQTT Broker settings page is available, supporting adding accounts and passwords. It allows connection to the broker using those credentials to subscribe to MQTT messages. * Cameras now support simultaneous viewing of multiple streams. **New Platform:** * Raspberry Pi 5 (unverified). **Optimizations:** * Optimized the Tasmota add-on by using the built-in Mosquitto broker, retiring the need for extra broker installation. * Improved the display format of Matter setup codes for better readability. **Bug Fixes:** * Resolved an issue where version 0.1 could not handle updates via OTA. **Known Issues:** The following known issues exist with version 0.2 and remain to be fixed in future updates: * When accessing the web for the first time, virtual machines and Raspberry Pi might occasionally show a disconnection prompt. * Raspberry Pi installation does not support adding fresh new or factory resetting Matter devices. Please use alternative Matter platforms and share them with CubeOS. * Matter Hub sometimes crashes and restarts continuously. * Remote notifications are unstable; users may not receive system pushes, potentially related to the network environment, browser issues, or backend process closures. * Camera streaming may fail for Raspberry Pi installation via remote links. * Matter Bridges won't show sub-devices on the devices' control page. And for sub-devices connected to a Matter Bridge on the settings page, the information of the Connected Bridge is missing. * Matter fabric with Vendor ID "1286" can not be removed on CubeOS. If the system promotes a device that is full of fabric, please remove one from the other Matter platforms it is connected to. * OTA is unsupported for Raspberry Pi 5 installation. # Developer & API Guide ## 1. Start to Use ### 1.1 Preparation Step 1. Please make sure the gateway is powered on and works properly. Step 2. Make sure the gateway and the PC are connected to the same LAN. Then enter the URL of CUBE on your browser. Notice: If you have several gateways, you can get the corresponding IP address to access the specified gateway in the below two ways. 1. Log in to your wireless router and check the IP address of the gateway in DHCP. 2. CUBE supports local discovery via mDNS. ### 1.2 Get started * Call the \[Access Token] interface, and get an error response, prompting to click <**Done**>. Note that after pressing, the interface access is valid for no more than 5 minutes. ```json // Request curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Response { "error": 401, "data": {}, "message": "link button not pressed" } ``` * Click <**Done**> and call the \[Access Token] interface again. The response is successful, and the token is obtained. ```json // Request curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Response { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` * Verify token. Call the \[Get Device List] interface. The response is successful, and the device list is obtained. ```json // Request curl --location --request GET 'http:///open-api/V2/rest/devices' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d' // Response { "error": 0, "data": { "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "device name", "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] } "message": "success" } ``` * Get CUBE access token method: After calling the \[Access Token] interface, the CUBE Web console page global pop-up box prompts the user to confirm the acquisition of the interface call credentials. * Note: If you open more than one CUBE web console page, the confirmation pop-up box will appear on multiple web console pages together, and the pop-up box of other web console pages will be closed after clicking the confirmation on one of the web console pages. ## 2. Core Concept ### 2.1 Development Interface Address The gateway Web API interface has two access methods (based on IP or domain name), usually the root path is /open-api/V2/rest/< specific function module > // IP access http\:///open-api/V2/rest/bridge // Domain name access http\:///open-api/V2/rest/bridge ### 2.2 Device Display Category & Capabilities * \*\*Device display category (DisplayCategory). \*\*Device display category is used to identify (device) specific categories, such as switch, plug, light, etc. **This information will determine the UI display effect of the device in the gateway**. * \*\*Device Capability. \*\*Device capability is used to describe the specific sub-functions of the device. Such as power control, brightness control, color temperature control, etc. **A single device can support 1 or more capabilities**. * **capability:** Describes the capability name, which must be globally unique and of string type. Multiple English words should be separated by hyphens ("-"). For example: `"thermostat-target-setpoint"`. * **name:** Describes the category under the capability, also of string type. Multiple English words should be separated by hyphens ("-"). For example: `"auto-mode"`, `"manual-mode"`. * **permission:** Describes the permissions associated with the capability. The type is string, formatted in a 8421 binary code. Examples include: * Device controllable: `"1000"` * Device configurable: `"0010"` * Device controllable and configurable: `"1010"` * Device controllable and reportable: `"1100"` The significance of each bit, from right to left, is as follows: ⅰ. Bit 0: Allows querying the device ⅱ. Bit 1: Allows configuring the device ⅲ. Bit 2: Allows the device to report data ⅳ. Bit 3: Allows controlling the device ```javascript const permission = { "update": "1000", "updated": "0100", "configure": "0010", "query": "0001", "update-updated": "1100", "update-query": "1001", "update-updated-configure": "1110", "updated-configure":"0110", "update-updated-query":"1101" } ``` **settings:** Describes the configuration items for the capability, which are of object type and include a description of each configuration item. ⅰ. **key:** Describes the name of the configuration item, which is of string type. Multiple English words should be expressed in camelCase. For example: `"temperatureUnit"`. ⅱ. **value:** Describes the content of the configuration item. The specific specifications are detailed in the table below. | Attribute | Type | Optional | Description | | -------------------- | ------ | -------- | ----------------------------------------------------- | | permission | string | N | Describes the permissions for the configuration item. | | **Optional values:** | | | | * Allow modification of this configuration item: `"10"` * Allow viewing of this configuration item: `"01"` * Allow both modification and viewing of this configuration item: `"11"` **Bit explanation:** 1. **Bit 0:** Allows viewing of this configuration item 2. **Bit 1:** Allows modification of this configuration item | | type | string | N | Describes the data type of the configuration item value. **Optional values:** * `"enum"` * `"numeric"` * `"object"` * `"boolean"` * `"string"` **Type-specific guidelines:** 1. **When `**type = enum**`:** * The `value` field (describing the configuration item value) is required if `permission` allows modification (`"10"` or `"11"`). * The `default` (describing the default value of the configuration item) and `values` (describing the selectable values for the configuration item) fields are optional. 2. **When `**type = numeric**`:** * The `value` field is required if `permission` allows modification (`"10"` or `"11"`). * The following fields are optional: * `min` (describing the minimum value of the configuration item) * `max` (describing the maximum value of the configuration item) * `step` (describing the step value for the configuration item) * `precision` (describing the precision) * `unit` (describing the unit of the configuration item) * `default` (describing the default value) 3. **When `**type = object**`:** * The `value` field is required if `permission` allows modification (`"10"` or `"11"`). * The `default` field is optional. 4. **When `**type = boolean**`:** * The `value` field is required if `permission` allows modification (`"10"` or `"11"`). * The `default` field is optional. 5. **When `**type = string**`:** * The `value` field is required if `permission` allows modification (`"10"` or `"11"`). * The `default` field is optional. | ```javascript // type = enum { "settings":{ "temperatureUnit": { "type": "enum", "permission": "11", "values": ["c", "f"], "default": "c", "value": "f" } } } // type = numeric { "settings": { "setpointRange": { "type": "numeric", "permission": "01", "min": 4, "max": 35, "default": 20, "step": 0.5, "precision": 0.01 "unit": "c" } } } // type = object { "settings":{ "weeklySchedule":{ "type": "object", "permission": "11", "value": { "maxEntryPerDay": 2, "Monday": [ { "startTimeInMinutes": 440, "upperSetpoint": 36.5 }, { "startTimeInMinutes": 900, "upperSetpoint": 26.5 } ]， "Tuesday": [...], "Wednesday": [...], "Thursday": [...], "Friday": [...], "Saturday": [...], "Sunday": [...], } } } } ``` ## 3.Web API ### Type of Data | Type | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | string | String data type. UTF8 encoded. | | number | Number data type. [double-precision 64-bit binary format IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | | int | Integral data type. | | object | Object data type. JSON-compliant object | | string\[] | Array of string | | int\[] | Array of integral | | object\[] | Array of object | | bool | Boolean | | date | Time string. String in ISO (ISO 8601 Extended Format) format: YYYY-MM-DDTHH:mm:ss.sssZ. The time zone is always UTC (Coordinated Universal Time), identified by a suffix "Z". | ### Generic Response Results | Attribute | Type | Optional | Description | | ------------------------------------------------------------------------------------------------ | ------ | -------- | --------------------- | | error | int | N | Error code: | | 0: Success | | | | | 400:Parameter error | | | | | 401:Authentication failed | | | | | 500:Server exception | | | | | data | object | N | Response data body | | message | string | N | Response description: | | When error is equal to 0, the content is success | | | | | When error is not equal to 0, it is a non-empty string, and the content is an error description. | | | | **Response Example**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "error": 400, "data": {}, "message": "invalid parameters" } ``` ### Resource List | Type | Description | | --------------- | ------------------------ | | Supported sound | - alert1 (Alarm Sound 1) | * alert2 (Alarm Sound 2) * alert3 (Alarm Sound 3) * alert4 (Alarm Sound 4) * alert5 (Alarm Sound 5) * doorbell1 (Doorbell Sound 1) * doorbell2 (Doorbell Sound 2) * doorbell3 (Doorbell Sound 3) * doorbell4 (Doorbell Sound 4) * doorbell5 (Doorbell Sound 5) * alarm1 (Alarm Sound 1) * alarm2 (Alarm Sound 2) * alarm3 (Alarm Sound 3) * alarm4 (Alarm Sound 4) * alarm5 (Alarm Sound 5) | | Supported deep | - bootComplete (System startup completed) * networkConnected (Network connected) * networkDisconnected (Network disconnected) * systemShutdown (System shutdown) -deviceDiscovered (Discover device) * system Armed (System armed enable) * system Disarmed (System armed disable) * factoryReset (Reset device) | ### 3.1 The Gateway Function #### a. Access Token Allow users to access token. * Notice: The token will be cleared after device reset. * Notice: After obtaining the token, you need to press the button again to successfully obtain a new token. :::tips * **URL**：`/open-api/V2/rest/bridge/access_token` * **Method**：`GET` * **Header**： * Content-Type: application/json ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------------- | | app\_name | string | Y | Application name description. | Successful data response: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ---------------------------------------------------------------------- | | token | string | N | The interface access token. It's valid for a long time, please save it | | app\_name | string | Y | Application name description. | :::tips **Condition**: User trigger the < command key > and access this interface within the valid time. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` Failure data response：empty Object :::tips **Conditions**：The user has not triggered the < command key >, or the valid time has expired. \*\*Status Code: \*\* `200 OK` ::: **Response Example**: ```json { "error": 401, "data": {}, "message": "link button not pressed" } ``` #### b. Get the State of Gateway Allow authorized users to obtain the status of gateway through this interface :::tips * **URL**：`/open-api/V2/rest/bridge/runtime` * **Method**：`GET` * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request Parameters: none Successful data response: | **Attribute** | **Type** | **Optional** | **Description** | | ---------------------------------------------------------------------------- | -------- | ------------ | ------------------------------ | | ram\_used | int | N | ram usage percent.\[0-100] | | cpu\_used | int | N | cpu usage percentage. \[0-100] | | power\_up\_time | date | N | The last power-on time | | cpu\_temp | int | N | CPU Temperature: | | Unit: Celsius | | | | | cpu\_temp\_unit | string | N | CPU Temperature Unit: | | Optional | | | | | values:`'c'`, `'f'` | | | | | sd\_card\_used | int | Y | SD Card Usage (Percentage): | | Range:`[0-100]` with one decimal place of precision | | | | | \*Note: If the SD card is not inserted or not formatted, the value is empty. | | | | :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": { "ram_used": 40, "cpu_used": 30, "power_up_time": "2022-10-12T02:58:09.989Z", "cpu_temp": 51, "cpu_temp_unit": "c", "sd_card_used" : "12" }, "message": "success" } ``` #### c. Set the Gateway Allow authorized users to set the gateway through this interface :::tips * **URL**：`/open-api/V2/rest/bridge/config` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------- | | volume | int | Y | System volume. \[0-100] | Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Get the Gateway info Allow authorized users to get the gateway info through this interface :::tips * **URL**：`/open-api/V2/rest/bridge` * **Method**：`GET` * **Header**： * Content-Type: application/json ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ---------------------- | | ip | string | N | ip address | | mac | string | N | mac address | | domain | string | Y | Gateway service domain | | fw\_version | string | N | Firmware version | | name | string | N | Device name | Successful data response:empty Object {} :::tips **Conditions**: None \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": { "ip": "192.168.31.25", "mac": "00:0A:02:0B:03:0C", "domain": "ihost.local", "fw_version": "1.9.0", "name": "iHost" }, "message": "success" } ``` #### e. Gateway Mute Allows authorized users to mute the gateway through this interface. :::tips * **URL**：`/open-api/v2/rest/bridge/mute` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: none Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### f. Unmute Gateway Allows authorized users to unmute the gateway through this interface.\ :::tips * **URL**：`/open-api/v2/rest/bridge/unmute` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: none Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### g. Cancel Gateway Alarm Allows authorized users to disable the alarm sound status on the gateway through this interface. :::tips * **URL**：`/open-api/v2/rest/bridge/cancel_alarm` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: none Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.2 Hardware Function #### a. Restart Gateway Allow authorized user to restart the gateway through this interface :::tips * **URL**：`/open-api/V2/rest/hardware/reboot` * **Method**：`POST` * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request Parameters: none Successful data response: empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: ```json { "error": 0, "data": {}, "message": "success" } ``` #### b. Speaker Control Allow authorized users to control the speaker through this interface :::tips * **URL**：`/open-api/V2/rest/hardware/speaker` * **Method**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------- | ----------------------------- | -------------------------------------------------------------------------------- | | type | string | N | Optional parameters: 1.play\_sound (play the sound) 2.play\_beep (play the beep) | | sound | SoundObject | Y (N if type is play\_sound.) | The sound. | | beep | BeepObject | Y (N if type is play\_beep.) | The beep | SoundObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | name | string | N | The sound name. The supported values can be checked in \[Resource List - Supported sound] | | volume | int | N | The sound volume. \[0-100] | | countdown | int | N | The duration for the speaker to play the sound, and it will stop playing automatically after the time is up. Unit: second. \[0,1799] | BeepObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------------------------------------------------------------- | | name | string | N | The deep name. The supported values can be checked in \[Resource List - Supported deep] | | volume | int | N | The deep volume. \[0-100] | Successful data response: empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\* `200 OK` ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.3 Device Management Function #### a. Supported Device Type | **Device Type** | **Value** | iHost Version | | ------------------------------- | ---------------------------- | ------------- | | Plug | plug | ≥ 2.1.0 | | Switch | switch | ≥ 2.1.0 | | Light | light | ≥ 2.1.0 | | Curtain | curtain | ≥ 2.1.0 | | Door/Window Sensor | contactSensor | ≥ 2.1.0 | | Motion sensor | motionSensor | ≥ 2.1.0 | | Temperature sensor | temperatureSensor | ≥ 2.1.0 | | Humidity sensor | humiditySensor | ≥ 2.1.0 | | Temperature and humidity sensor | temperatureAndHumiditySensor | ≥ 2.1.0 | | Water leak detector | waterLeakDetector | ≥ 2.1.0 | | Smoke detector | smokeDetector | ≥ 2.1.0 | | Wireless button | button | ≥ 2.1.0 | | Camera | camera | ≥ 2.1.0 | | General sensor | sensor | ≥ 2.1.0 | | General sensor | sensor | ≥ 2.1.0 | | Fanlight | fanLight | ≥ 2.1.0 | | AirConditioner | airConditioner | ≥ 2.1.0 | | Fan | fan | ≥ 2.1.0 | | Thermostat | thermostat | ≥ 2.1.0 | #### b. Supported Device Capabilities **Power Switch (power):** **Capability Declaration Example:** ``` [ { "capability": "power", // Capability name "permission": "1100", // ihost does not support configuring soft start/stop, thus no configure field } ] ``` **State Attribute:** ``` { "powerState": "on", // Field powerState indicates the power on/off state. Required. **Type:** string. "on" indicates power on, "off" indicates power off, "toggle" indicates toggle. } ``` **Protocol (Query Status & Control Instructions):** **Turn On:** ``` { "power": { "powerState": "on" } } ``` **Turn Off:** ``` { "power": { "powerState": "off" } } ``` **Channel Switch (toggle):** **Capability Declaration Example:** Single Component Example: ``` [ { "capability": "toggle", // Capability name "permission": "1100", // Permission "name": "1", // Component name, **Type:** String. Optional values: "1" (Channel 1), "2" (Channel 2), "3" (Channel 3), "4" (Channel 4), or other values containing uppercase and lowercase letters and numbers } ] ``` Multiple Components Example: ``` [ { "capability": "toggle", "permission": "1100", "name": "1" }, { "capability": "toggle", "permission": "1100", "name": "2" } ] ``` **State Attribute:** ``` { "toggleState": "on", // Field toggleState indicates the toggle state of {device_id}'s {name} attribute. Required. **Type:** String. "on" indicates enabled, "off" indicates disabled, "toggle" indicates toggle. } ``` **Protocol (Query Status & Control Instructions):** Toggle Format: ``` { [capability]: { [toggle-name]: { [toggleState]: [value] } } } Component 1 On, Component 2 Off: { "toggle": { "1": { "toggleState": "on" }, "2": { "toggleState": "off" } } } ``` **Channel Inching (toggle-inching):** **Capability Declaration Example:** ``` [ { "capability": "toggle-inching", // Capability name "permission": "0010", // Permission "settings": { "toggleInchingSetting": { "permission": "11", "type": "object", "value": { "supported": { "1": { // Component name "enable": true, // Whether inching function is enabled. **Type:** Boolean. Required. "inchingSwitch": "off", // Inching switch setting. **Type:** String. Required. "off" (power off), "on" (power on) "delay": 1000, // Inching delay time in milliseconds. **Type:** Integer. Required. "min_delay": 500, // Minimum delay time "max_delay": 100000 // Maximum delay time }, "2": { // Component name "enable": true, // Whether inching function is enabled. **Type:** Boolean. Required. "inchingSwitch": "off", // Inching switch setting. **Type:** String. Required. "off" (power off), "on" (power on) "delay": 1000, // Inching delay time in milliseconds. **Type:** Integer. Required. "min_delay": 500, // Minimum delay time "max_delay": 100000 // Maximum delay time }, "3": { // Component name "enable": true, // Whether inching function is enabled. **Type:** Boolean. Required. "inchingSwitch": "off", // Inching switch setting. **Type:** String. Required. "off" (power off), "on" (power on) "delay": 1000, // Inching delay time in milliseconds. **Type:** Integer. Required. "min_delay": 500, // Minimum delay time "max_delay": 100000 // Maximum delay time }, "4": { // Component name "enable": true, // Whether inching function is enabled. **Type:** Boolean. Required. "inchingSwitch": "off", // Inching switch setting. **Type:** String. Required. "off" (power off), "on" (power on) "delay": 1000, // Inching delay time in milliseconds. **Type:** Integer. Required. "min_delay": 500, // Minimum delay time "max_delay": 100000 // Maximum delay time } } } } } } ] ``` **State Attribute** None **Protocol (Query Status & Control Instructions)** None **Brightness Adjustment (brightness):** **Capability Declaration Example:** ``` { "capability": "brightness", // Capability name "permission": "1100" // Permission } ``` **State Attribute:** ``` { "brightness": 100, // Field brightness indicates the brightness percentage. Choose between brightness or brightnessDelta. **Type:** Number. Range: 0-100. } ``` **Protocol (Query Status & Control Instructions):** Set Brightness to 80%. (0 is darkest and 100 is lightest.) ``` json 复制代码 { "brightness": { "brightness": 80 } } ``` **Color Temperature Adjustment (color-temperature):** **Capability Declaration Example:** ``` { "capability": "color-temperature", // Capability name "permission": "1100" // Permission } ``` **State Attribute:** ``` { "colorTemperature": 100, // Field colorTemperature indicates the color temperature percentage. Choose between colorTemperature or colorTemperatureDelta. **Type:** Number. Range: 0-100. 0 indicates warm light, 50 indicates neutral light, 100 indicates cool light. } ``` **Protocol (Query Status & Control Instructions):** Adjust Color Temperature to 50%: ``` json { "color-temperature": { "colorTemperature": 50 } } ``` **Color Adjustment (color-rgb):** **Capability Declaration Example:** ``` { "capability": "color-rgb", // Capability name "permission": "1100" // Permission } ``` **State Attribute:** ``` { "red": 255, // Field red represents the red color in the RGB color space. Required. **Type:** Number. Range: 0-255. "green": 0, // Field green represents the green color in the RGB color space. Required. **Type:** Number. Range: 0-255. "blue": 255 // Field blue represents the blue color in the RGB color space. Required. **Type:** Number. Range: 0-255. } ``` **Protocol (Query Status & Control Instructions):** Set Color to Purple: ``` { "color-rgb": { "red": 255, "green": 0, "blue": 255 } } ``` **Percentage Adjustment (percentage):** **Capability Declaration Example:** ``` { "capability": "percentage", "permission": "1100", "settings": { // Optional "percentageRange": { "permission": "01", "type": "numeric", "min": 0, "max": 100, "step": 5 } } } ``` **State Attribute:** ``` { "percentage": 100, // Field percentage indicates a percentage value. Choose between percentage or percentageDelta. **Type:** Number. Range: 0-100. } ``` **Protocol (Query Status & Control Instructions):** Adjust to 40%: ``` { "percentage": { "percentage": 40 } } ``` **Motor Control (motor-control):** **Capability Declaration Example:** ``` { "capability": "motor-control", "permission": "1100" } ``` **State Attribute:** ``` json { "motorControl": "stop", // Field motorControl indicates the motor's state. Required. **Type:** String. Possible values: "open" (open), "close" (close), "stop" (stop), "lock" (lock). } ``` **Protocol (Query Status & Control Instructions):** Open Motor: ``` { "motor-control": { "motorControl": "open" } } ``` **Motor Reversal (motor-reverse):** **Capability Declaration Example:** ``` { "capability": "motor-reverse", "permission": "1100" } ``` **State Attribute:** ``` { "motorReverse": true, // Field motorReverse indicates the motor's direction setting. Required. **Type:** Boolean. true indicates forward, false indicates reverse. } ``` **Protocol (Query Status & Control Instructions):** Set Motor to Forward: ``` { "motor-reverse": { "motorReverse": true } } ``` **Motor Calibration (motor-clb)** **Capability Declaration Example:** ``` { "capability": "motor-clb", "permission": "0100" } ``` **Attributes (State):** ``` { "motorClb": "calibration" // Field motorClb indicates the calibration status of the motor. Required. **Type:** String. "normal" indicates normal mode (calibrated), "calibration" indicates ongoing calibration. } ``` **Protocol (Status Reporting):** Report Motor Status is Being Calibrated: ``` { "motor-clb": { "motorClb": "calibration" } } ``` **Power On State (startup)** **Capability Declaration Example:** ``` { "capability": "startup", "permission": "1100" } ``` **Attributes (State):** ``` { "startup": "on" // Power state upon startup. **Type:** String. Required. Optional values: "on" (power on), "stay" (maintain power), "off" (power off), "toggle" (invert power state). } ``` **Protocol (Query Status & Control Instructions):** Set Power State to Always On: ``` { "startup": { "startup": "on" } } ``` *** **Wake-up Activation (identify)** **Capability Declaration Example:** ``` { "capability": "identify", "permission": "0100" } ``` **Attributes (State):** ``` { "identify": true // Indicates whether the device actively reports recognition results or is activated. } ``` **Protocol (Status Reporting & Control Instructions):** Set Wake-up Activation Time: ``` { "identify": { "countdown": 180 // Field countdown indicates the countdown time. Required. **Type:** Number. Unit: seconds. } } ``` Report Activation Status: ``` { "identify": { "identify": true // Indicates whether the device actively reports recognition results or is activated. } } ``` **Real-time Power Consumption Statistics Switch (power-consumption)** **Capability Declaration Example:** ``` { "capability": "power-consumption", "permission": "1101", "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ``` **Attributes (State):** Start/Stop Real-time Statistics: ``` { "rlSummarize": true, // Start/stop real-time statistics. **Type:** Boolean. Required. "timeRange": { // Summarized time range. Required. "start": "2020-07-05T08:00:00Z", // Start time of power consumption statistics. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time of power consumption statistics. **Type:** String. Required. } } ``` Query Power Consumption by Time Range: ``` { "type": "summarize", // Type of statistics. **Type:** String. Required. Optional values: "rlSummarize" (real-time summary), "summarize" (current summary). "timeRange": { // Summarized time range. Required if type is "summarize". "start": "2020-07-05T08:00:00Z", // Start time of power consumption statistics. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time of power consumption statistics. **Type:** String. Optional. If omitted, indicates current time. } } ``` Respond with Statistics Result within Time Range: ``` json { "type": "summarize", // Type of statistics. **Type:** String. Required. Optional values: "rlSummarize" (real-time summary), "summarize" (current summary). "rlSummarize": 50.0, // Total power consumption. **Type:** Number. Unit: 0.01 kWh. Optional. "electricityIntervals": [ // Multiple statistics records divided according to configuration.resolution. Optional. Not present when type is "rlSummarize". { "usage": 26.5, // Power consumption. **Type:** Number. Unit: 0.01 kWh. Required. "start": "2020-07-05T08:00:00Z", // Start time. **Type:** Date. Required. "end": "2020-07-05T09:00:00Z" // End time. **Type:** Date. Required. If the interval between end and start is smaller than resolution, all reported records are considered invalid. }, { "usage": 26.5, // Power consumption. **Type:** Number. Unit: 0.01 kWh. Required. "start": "2020-07-05T09:00:00Z", // Start time. **Type:** Date. Required. "end": "2020-07-05T10:00:00Z" // End time. **Type:** Date. Required. If the interval between end and start is smaller than resolution, all reported records are considered invalid. } ] } ``` **Protocol (Status Reporting & Control Instructions):** Start Real-time Statistics: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Stop Real-time Statistics: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Get Historical Power Consumption: ``` json { "power-consumption": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } ``` Get Real-time Power Consumption: ``` json { "power-consumption": { "powerConsumption": { "type": "rlSummarize" } } } ``` **Temperature and Humidity Mode Detection (thermostat-mode-detect)** **Capability Declaration Example:** ``` { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Type of temperature control detection. **Type:** String. Required. Optional values: "humidity" (humidity detection), "temperature" (temperature detection). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Supported detection settings. Required. { "name": "lowerSetpoint", // Detection value should be above this setpoint. At least one of lowerSetpoint or upperSetpoint is required. "value": { // Detection range. Optional. Specify if preset conditions exist. "value": 68.0, // Temperature value. **Type:** Number. Required. "scale": "f" // Temperature unit. Required when name=temperature. Optional values: "c" (Celsius), "f" (Fahrenheit). } }, { "name": "upperSetpoint", // Detection value should be below this setpoint. At least one of lowerSetpoint or upperSetpoint is required. "value": { // Detection range. Optional. Specify if preset conditions exist. "value": 68.0, // Temperature value. **Type:** Number. Required. "scale": "f" // Temperature unit. Required when name=temperature. Optional values: "c" (Celsius), "f" (Fahrenheit). } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } { "capability": "thermostat-mode-detect", "permission": "0110", "name": "humidity", // Type of temperature control detection. **Type:** String. Required. Optional values: "humidity" (humidity detection), "temperature" (temperature detection). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Supported detection settings. Required. { "name": "lowerSetpoint", // Detection value should be above this setpoint. At least one of lowerSetpoint or upperSetpoint is required. "value": { // Detection range. Optional. Specify if preset conditions exist. "value": 68.0, // Humidity value. **Type:** Number. Required } }, { "name": "upperSetpoint", // Detection value should be below this setpoint. At least one of lowerSetpoint or upperSetpoint is required. "value": { // Detection range. Optional. Specify if preset conditions exist. "value": 68.0, // Humidity value. **Type:** Number. Required } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ``` **Attributes (State):** ``` { "mode": "COMFORT" // Mode ID. Optional. Supported values: "COMFORT" (Comfort Mode), "COLD" (Cold Mode), "HOT" (Hot Mode), "DRY" (Dry Mode), "WET" (Wet Mode). } ``` **Protocol (Query Status & Control Instructions):** Format: ``` { [capability] :{ [mode name] :{ "mode": [value] } } } ``` Example: ``` { "thermostat-mode-detect": { "humidity": { "mode": "COMFORT" } } } ``` **Thermostat Mode (thermostat-mode)** **Capability Declaration Example:** ``` { "capability": "thermostat", "permission": "1100", "name": "thermostat-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", "AUTO", "ECO" ] } } } ``` **Attributes (State):** ``` { "thermostatMode": "MANUAL" // Thermostat operating mode. **Type:** String. Optional values: "MANUAL", "AUTO", "ECO". } ``` **Protocol (Query Status & Control Instructions):** ``` { "thermostat": { "thermostat-mode": { "thermostatMode": "MANUAL" } } } ``` **Thermostat Adaptive Recovery Status (thermostat/adaptive-recovery-status)** **Capability Declaration Example:** ``` { "capability": "thermostat", "permission": "0100", "name": "adaptive-recovery-status" // Thermostat adaptive recovery status } ``` **Attributes (State):** ``` { "adaptiveRecoveryStatus": "HEATING" // Thermostat adaptive recovery status. **Type:** String. Optional values: "HEATING", "INACTIVE". } ``` **Protocol (Query Status & Control Instructions):** ``` { "thermostat": { "adaptive-recovery-status": { "adaptiveRecoveryStatus": "HEATING" } } } ``` **Thermostat Mode Target Temperature Setting (thermostat-target-setpoint)** **Capability Declaration Example:** ``` [[ { "capability": "thermostat-target-setpoint", "name": "manual-mode", "permission": "1110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 } } }, { "capability": "thermostat-target-setpoint", "name": "eco-mode", "permission": "1110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 } } }, { "capability": "thermostat-target-setpoint", "name": "auto-mode", "permission": "0110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 }, "weeklySchedule":{ "type": "object", "permission": "11", "value": { "maxEntryPerDay": 2, "Monday": [ { "startTimeInMinutes": 440, // Start time in minutes. **Type:** int. E.g., 7:20 AM = 440 minutes. "upperSetpoint": 36.5, // Maximum target temperature. **Type:** number. "lowerSetpoint": 20 // Minimum target temperature. **Type:** number. }, { "startTimeInMinutes": 900, // Start time in minutes. E.g., 3:00 PM = 900 minutes. "upperSetpoint": 26.5, // Maximum target temperature. **Type:** number. "lowerSetpoint": 21 // Minimum target temperature. **Type:** number. } ], "Tuesday": [... ], "Wednesday": [... ], "Thursday": [... ], "Friday": [... ], "Saturday": [... ], "Sunday": [... ], } } } } ] ``` **Attributes (State):** ``` { "targetSetpoint": 30 // Target temperature for the specified mode. **Type:** number, in the unit specified by temperatureUnit. } ``` **Protocol (Query Status & Control Instructions):** ``` { "thermostat-target-setpoint": { "manual-mode": { "targetSetpoint": 30 }, "auto-mode": { "targetSetpoint": 30 } } } ``` **Sensor Detection (detect)** **Capability Declaration Example:** ``` { "capability": "detect", "permission": "0110", "settings": { // Optional "detectInterval": { "permission": "11", "type": "numeric", "value": 300 }, "detectSensitivity": { "permission": "11", "type": "numeric", "value": 1000 } } } ``` **Attributes (State):** ``` { "detected": true // Detection result. **Type:** Boolean. `true` indicates detection, `false` indicates no detection. } ``` **Protocol (Query Status & Control Instructions):** ``` { "detect": { "detected": true } } ``` **Temperature Detection (temperature)** **Capability Declaration Example:** ``` { "capability": "temperature", "permission": "0110", "settings": { // Optional "temperatureCalibration": { // Optional temperature calibration "type": "numeric", "permission": "11", "min": -7, // Minimum value "max": 7, // Maximum value "step": 0.2, // Temperature adjustment step, unit same as temperatureUnit "value": 5.2 // Current temperature calibration value. **Type:** number. }, "temperatureUnit": { // Optional temperature unit "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange": { // Optional temperature detection range "type": "numeric", "permission": "01", "min": -40, "max": 80 } } } ``` **Attributes (State):** ``` json 复制代码 { "temperature": 26.5 // Current temperature. **Type:** Number, in Celsius. } ``` **Protocol (Query Status & Control Instructions):** ``` { "temperature": { "temperature": 20 } } ``` **Humidity Detection (humidity)** **Capability Declaration Example:** ``` { "capability": "humidity", "permission": "0100", "settings": { // Optional humidity detection range. "humidityRange": { "type": "numeric", "permission": "01", "min": 0, "max": 100 } } } ``` **Attributes (State):** ``` { "humidity": 50 // Current relative humidity (percentage). **Type:** Number, range 0-100. } ``` **Protocol (Query Status & Control Instructions):** ``` { "humidity": { "humidity": 20 } } ``` **Battery Detection (battery)** **Capability Declaration Example:** ``` { "capability": "battery", "permission": "0100" } ``` **Attributes (State):** ``` { "battery": 95 // Remaining battery percentage. **Type:** Number, range -1 to 100. Note: -1 indicates unknown battery level. } ``` **Protocol (Query Status & Control Instructions):** ``` { "battery": { "battery": 40 } } ``` **Single Button Detection (press)** **Capability Declaration Example:** ``` { "capability": "press", "permission": "1100", "settings": { // Optional "actions": { // Button actions, optional. "type": "enum", "permission": "01", "values": [ // Optional button actions. Default values are "singlePress", "doublePress", "longPress". Configured actions replace defaults. ] } } } ``` **Attributes (State):** ``` { "press": "singlePress" // Button press type. **Type:** String. Standard values: "singlePress" (single or short press), "doublePress" (double press), "longPress" (long press). } ``` **Protocol (Query Status & Control Instructions):** ``` { "press": { "press": "singlePress" } } ``` **Multi-Button Detection (multi-press)** **Capability Declaration Example:** ``` { "capability": "multi-press", "permission": "0100", "name": "1", // Name of the multi-press attribute. **Type:** String. Only alphanumeric characters allowed. "settings": { // Optional "actions": { // Button actions, optional. "type": "enum", "permission": "01", "values": [ // Optional button actions. Default values are "singlePress", "doublePress", "longPress". Configured actions replace defaults. ] } } } ``` **Attributes (State):** ``` { "press": "singlePress" // Button press type. **Type:** String. Standard values: "singlePress" (single or short press), "doublePress" (double press), "longPress" (long press). } ``` **Protocol (Query Status & Control Instructions):** ``` { [capability] :{ [multi-press-name]：{ press:[value] } } } example: { "multi-press": { "1": { "press": "singlePress" }, "2": { "press": "doublePress" } } } ``` **Signal Strength Detection (rssi)** **Capability Declaration Example:** ``` { "capability": "rssi", "permission": "0100" } ``` **Attributes (State):** ``` { "rssi": -65 // Wireless signal strength (Received Signal Strength Indicator). **Type:** Number, unit dBm, negative integer values. } ``` **Protocol (Query Status & Control Instructions):** ``` { "rssi": { "rssi": -65 } } ``` **Tamper Detection (tamper-alert)** **Capability Declaration Example:** ``` { "capability": "tamper-alert", "permission": "0100" } ``` **Attributes (State):** ``` { "tamper": "clear" // Tamper status. **Type:** String. Possible values: "clear" (not tampered), "detected" (tampered). } ``` **Protocol (Query Status & Control Instructions):** ``` { "tamper-alert": { "tamper": "clear" // Tamper status. **Type:** String. Possible values: "clear" (not tampered), "detected" (tampered). } } ``` **Illumination Level Detection (illumination-level)** **Capability Declaration Example:** ``` { "capability": "illumination-level", "permission": "0100" } ``` **Attributes (State):** ``` { "level": "brighter" // Brightness level. **Type:** String. Possible values: "brighter" (brighter), "darker" (darker). } ``` **Protocol (Query Status & Control Instructions):** ``` { "illumination-level": { "level": "brighter" } } ``` **Voltage Detection (voltage)** **Capability Declaration Example:** ``` { "capability": "voltage", "permission": "0100" } ``` **Attributes (State):** ``` { "voltage": 50 // Current voltage value, in 0.01V units. **Type:** Number, non-negative values. } ``` **Protocol (Query Status & Control Instructions):** ``` { "voltage": { "voltage": 50 } } ``` **Electric Current Detection (electric-current)** **Capability Declaration Example:** ``` { "capability": "electric-current", "permission": "0100" } ``` **Attributes (State):** ``` { "electric-current": 50 // Current current value, in 0.01A units. **Type:** Number, non-negative integer values. } ``` **Protocol (Query Status & Control Instructions):** ``` { "electric-current": { "electric-current": 50 } } ``` **Electric Power Detection (electric-power)** **Capability Declaration Example:** ``` { "capability": "electric-power", "permission": "0100" } ``` **Attributes (State):** ``` { "electric-power": 50 // Current power value, in 0.01W units. **Type:** Number, non-negative integer values. } ``` **Protocol (Query Status & Control Instructions):** ``` { "electric-power": { "electric-power": 50 } } ``` **Fault Detection (fault)** **Capability Declaration Example:** ``` { "capability": "fault", "permission": "0100" } ``` **Attributes (State):** ``` { "fault": "none" // Fault status. **Type:** String. Possible values: "none" (no fault), "detected" (fault detected). } ``` **Protocol (Query Status & Control Instructions):** ``` { "fault": { "fault": "none" } } ``` **Threshold Breaker (threshold-breaker)** **Capability Declaration Example:** ``` { "capability": "threshold-breaker", "permission": "0010", "settings": { "supportedSetting": { "type": "object", "permission": "11", "value": { "supported": [ { "name": "lowerPower", // Low power threshold breaker "value": { "value": 50, // Detection power value, in 0.01W units. **Type:** Integer. Range: >=0. "min_range": 10, // Minimum detection power value, in 0.01W units. **Type:** Integer. Range: >=0. "max_range": 3500 // Maximum detection power value, in 0.01W units. **Type:** Integer. Range: >=0. } }, { "name": "upperPower", // High power threshold breaker "value": { "value": 50, // Detection power value, in 0.01W units. **Type:** Integer. Range: >=0. "min_range": 10, // Minimum detection power value, in 0.01W units. **Type:** Integer. Range: >=0. "max_range": 3500 // Maximum detection power value, in 0.01W units. **Type:** Integer. Range: >=0. } }, { "name": "lowerElectricCurrent", // Low current threshold breaker "value": { "value": 50, // Detection current value, in 0.01A units. **Type:** Integer. Range: >=0. "min_range": 10, // Minimum detection current value, in 0.01A units. **Type:** Integer. Range: >=0. "max_range": 1500 // Maximum detection current value, in 0.01A units. **Type:** Integer. Range: >=0. } }, { "name": "upperElectricCurrent", // High current threshold breaker "value": { "value": 50, // Detection current value, in 0.01A units. **Type:** Integer. Range: >=0. "min_range": 10, // Minimum detection current value, in 0.01A units. **Type:** Integer. Range: >=0. "max_range": 1500 // Maximum detection current value, in 0.01A units. **Type:** Integer. Range: >=0. } }, { "name": "lowerVoltage", // Low voltage threshold breaker "value": { "value": 50, // Detection voltage value, in 0.01V units. **Type:** Integer. Range: >=0. "min_range": 10, // Minimum detection voltage value, in 0.01V units. **Type:** Integer. Range: >=0. "max_range": 24000 // Maximum detection voltage value, in 0.01V units. **Type:** Integer. Range: >=0. } }, { "name": "upperVoltage", // High voltage threshold breaker "value": { "value": 50, // Detection voltage value, in 0.01V units. **Type:** Integer. Range: >=0. "min_range": 10, // Minimum detection voltage value, in 0.01V units. **Type:** Integer. Range: >=0. "max_range": 24000 // Maximum detection voltage value, in 0.01V units. **Type:** Integer. Range: >=0. } } ] } } } } ``` **Attributes (State)** * None **Protocol (Query Status & Control Instructions)** * None **Inch Function (inching)** **Capability Declaration Example:** ``` { "capability": "inching", "permission": "0010", "settings": { "inchingEnable": { // Inch function enable setting "permission": "11", "type": "boolean", "value": false }, "inchingSwitch": { // Inch action setting "type": "enum", "permission": "11", "value": "on", "values": ["on", "off"] }, "inchingDelay": { // Inch time setting "type": "numeric", "permission": "11", "min": 500, "max": 100000, "value": 1000, "unit": "ms" } } } ``` **Attributes (State):** * None **Protocol (Query Status & Control Instructions):** * None **Camera Stream (camera-stream)** **Capability Declaration Example:** ``` { "capability": "camera-stream", "permission": "0010", "settings": { "streamSetting": { "type": "object", "permission": "11", "value": { "username": "String", // Access account. **Type:** String. Required. "password": "String", // Access password. **Type:** String. Required. "streamUrl": "rtsp://:@:/streaming/channel01", // Stream URL. **Type:** String. Required. "videoCodec": "", // Video codec. **Type:** String. Required. Optional parameters to be defined. "resolution": { // Video resolution. Required. "width": 1080, // Width. **Type:** Number. Required. "height": 720 // Height. **Type:** Number. Required. }, "keyFrameInterval": 5, // Key frame interval. **Type:** String. Required. "audioCodec": "G711", // Audio codec. **Type:** String. Required. Optional parameters to be defined. "samplingRate": 50, // Audio sampling rate, in Hz. **Type:** Number. Required. Optional parameters to be defined. "dataRate": 50 // Bitrate. **Type:** Number. Required. Unit: kb/s. } } } } ``` **Attributes (State):** * None **Protocol (Query Status & Control Instructions):** * None **Mode Control (mode)** **Capability Declaration Example:** ``` [ { "capability": "mode", "name": "fanLevel", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["low", "medium", "high"] // Custom mode values. Configured values override defaults. } } }, { "capability": "mode", "name": "thermostatMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["auto", "manual"] // Custom mode values. Configured values override defaults. } } }, { "capability": "mode", "name": "airConditionerMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["cool", "heat", "auto", "fan", "dry"] // Custom mode values. Configured values override defaults. } } }, { "capability": "mode", "name": "fanMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["normal", "sleep", "child"] // Custom mode values. Configured values override defaults. } } }, { "capability": "mode", "name": "horizontalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Custom mode values. Configured values override defaults. } } }, { "capability": "mode", "name": "verticalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Custom mode values. Configured values override defaults. } } } ] ``` **Attributes (State):** ``` { "modeValue": "low" // Mode value. **Type:** String. Required. Refer to supported preset modes. } ``` **Protocol (Query Status & Control Instructions):** ``` { "mode": { "fanLevel": { "modeValue": "low" } } } ``` **Carbon Dioxide Detection (co2)** **Capability Declaration Example:** ``` { "capability": "co2", "permission": "0100", "settings": { "co2Range": { "type": "numeric", "permission": "01", "min": 400, "max": 10000 } } } ``` **Attributes (State):** ``` { "co2": 111 // Carbon dioxide concentration. **Type:** Integer. Unit: ppm. } ``` **Protocol (Query Status & Control Instructions):** ``` { "co2": { "co2": 500 } } ``` **Illumination Detection (illumination)** **Capability Declaration Example:** ``` { "capability": "illumination", "permission": "0100", "settings": { "illuminationRange": { "type": "numeric", "permission": "01", "min": 0, "max": 160000 } } } ``` **Attributes (State):** ``` { "illumination": 11 // Illumination level. **Type:** Integer. Unit: lux. } ``` **Protocol (Query Status & Control Instructions):** ``` { "illumination": { "illumination": 50 } } ``` **Smoke Detection (smoke)** **Capability Declaration Example:** ``` { "capability": "smoke", "permission": "0100" } ``` **Attributes (State):** ``` { "smoke": true // Detection result. **Type:** Boolean. `true` indicates detection, `false` indicates no detection. } ``` **Protocol (Query Status & Control Instructions):** ``` { "smoke": { "smoke": true } } ``` **Door Magnet Open/Close Detection (contact)** **Capability Declaration Example:** ``` { "capability": "contact", "permission": "0100" } ``` **Attributes (State):** ``` { "contact": true // Detection result. **Type:** Boolean. `true` indicates detection, `false` indicates no detection. } ``` **Protocol (Query Status & Control Instructions):** ``` { "contact": { "contact": true } } ``` **Motion Detection (motion)** **Capability Declaration Example:** ``` { "capability": "motion", "permission": "0110", "settings": { "motionInterval": { "type": "numeric", "permission": "11", "value": 300 }, "motionSensitivity": { "type": "numeric", "permission": "11", "value": 1000 } } } ``` **Attributes (State):** ``` { "motion": true // Detection result. **Type:** Boolean. `true` indicates detection, `false` indicates no detection. } ``` **Protocol (Query Status & Control Instructions):** ``` { "motion": { "motion": true } } ``` **Water Leak Detection (water-leak)** **Capability Declaration Example:** ``` { "capability": "water-leak", "permission": "0100" } ``` **Attributes (State):** ``` { "waterLeak": true // Field `waterLeak` indicates the current detection result. **Type:** Boolean. `true` indicates detection, `false` indicates no detection. } ``` **Protocol (Query Status & Control Instructions):** ``` { "water-leak": { "waterLeak": true } } ``` **Window Detection Switch (window-detection)** **Capability Declaration Example:** ``` { "capability": "window-detection", "permission": "1100" } ``` **Attributes (State):** ``` { "powerState": "on" // Field `powerState` indicates the power state. **Type:** String. `on` indicates power is on, `off` indicates power is off. } ``` **Protocol (Query Status & Control Instructions):** ``` { "window-detection": { "powerState": "on" } } ``` **Child Lock Switch (child-lock)** **Capability Declaration Example:** ``` { "capability": "child-lock", "permission": "1100" } ``` **Attributes (State):** ``` { "powerState": "on" // Field `powerState` indicates the power state. **Type:** String. `on` indicates power is on, `off` indicates power is off. } ``` **Protocol (Query Status & Control Instructions):** ``` { "child-lock": { "powerState": "on" } } ``` **Anti-Direct Blow Switch (anti-direct-blow)** **Capability Declaration Example:** ``` { "capability": "anti-direct-blow", "permission": "1100" } ``` **Attributes (State):** ``` { "powerState": "on" // Field `powerState` indicates the power state. **Type:** String. `on` indicates power is on, `off` indicates power is off. } ``` **Protocol (Query Status & Control Instructions):** ``` { "anti-direct-blow": { "powerState": "on" } } ``` **Horizontal Swing Switch (horizontal-swing)** **Capability Declaration Example:** ``` { "capability": "horizontal-swing", "permission": "1100" } ``` **Attributes (State):** ``` { "powerState": "on" // Field `powerState` indicates the power state. **Type:** String. `on` indicates power is on, `off` indicates power is off. } ``` **Protocol (Query Status & Control Instructions):** ``` { "horizontal-swing": { "powerState": "on" } } ``` **Vertical Swing Switch (vertical-swing)** **Capability Declaration Example:** ``` { "capability": "vertical-swing", "permission": "1100" } ``` **Attributes (State):** ``` { "powerState": "on" // Field `powerState` indicates the power state. **Type:** String. `on` indicates power is on, `off` indicates power is off. } ``` **Protocol (Query Status & Control Instructions):** ``` { "vertical-swing": { "powerState": "on" } } ``` **ECO Mode Switch (eco)** **Capability Declaration Example:** ``` { "capability": "eco", "permission": "1100" } ``` **Attributes (State):** ``` { "powerState": "on" // Field `powerState` indicates the power state. **Type:** String. `on` indicates power is on, `off` indicates power is off. } ``` **Protocol (Query Status & Control Instructions):** ``` { "eco": { "powerState": "on" } } ``` **Toggle Startup (toggle-startup)** **Capability Declaration Example:** ``` { "capability": "toggle-startup", "permission": "1100", "name": "1" // Field `name` specifies the attribute name for `toggle-startup`. **Type:** String. Only letters and numbers are allowed. } ``` **Attributes (State):** ``` { "startup": "on" // **Type:** String. Options: `on` (power on), `stay` (power hold), `off` (power off). } ``` **Protocol (Query Status & Control Instructions):** ``` { "toggle-startup": { "1": { "startup": "on" }, "2": { "startup": "off" } } } ``` **Detect Hold (detect-hold)** **Capability Declaration Example:** ``` { "capability": "detect-hold", "permission": "0100", "settings": { "detectHoldEnable": { // Detect hold enable setting "permission": "01", "type": "boolean", "value": false }, "detectHoldSwitch": { // Detect hold action setting "type": "enum", "permission": "01", "value": "on", "values": ["on", "off"] }, "detectHoldTime": { // Detect hold time setting "type": "numeric", "permission": "01", "min": 1, "max": 359, "value": 5, "unit": "minute" } } } ``` **Attributes (State):** ``` { "detectHold": "on" // Field `detectHold` indicates the state detection hold status. **Type:** String. `on` means detection hold is active, `off` means detection hold is inactive. } ``` **Protocol (Query Status & Control Instructions):** ``` { "detect-hold": { "detectHold": "on" } } ``` **Toggle Identify/Activate (toggle-identify)** **Capability Declaration Example:** ``` { "capability": "toggle-identify", "permission": "1100", // Note: This capability is not used for reporting in the current version (V1.13.7) on ihost. "name": "1" // Component name. **Type:** String. Optional values: "1" (Channel 1), "2" (Channel 2), "3" (Channel 3), "4" (Channel 4). } ``` **Attributes (State):** ``` { "identify": true, // Indicates the device has actively reported identification or activation. "countdown": 180 // Field `countdown` indicates activation duration. **Type:** Number. Unit: seconds. } ``` **Protocol (Query Status & Control Instructions):** ``` { "toggle-identify": { "1": { "countdown": 180 // Activate device for 180 seconds. } } } // Device reports self-activation { "toggle-identify": { "1": { "identify": true } } } ``` **Toggle Voltage Detection (toggle-voltage)** **Capability Declaration Example:** ``` { "capability": "toggle-voltage", "permission": "1100" } ``` **Attributes (State):** ``` { "voltage": 230 // Field `voltage` indicates the detected voltage. **Type:** Number. Unit: Volts. } ``` **Protocol (Query Status & Control Instructions):** ``` { "toggle-voltage": { "voltage": 230 } } ``` **Subcomponent Electric Current Detection (toggle-electric-current)** **Capability Declaration Example:** ``` [ { "capability": "toggle-electric-current", "permission": "0100", "name": "1" // Component name. **Type:** String. Optional values: "1" (Channel 1), "2" (Channel 2), "3" (Channel 3), "4" (Channel 4). } ] ``` **Attributes (State):** ``` { "electricCurrent": 50 // Field `electricCurrent` represents the current value. **Unit:** 0.01 A. **Type:** Integer. Value must be greater than or equal to 0. } ``` **Protocol (Query Status & Control Instructions):** ``` { "toggle-electric-current": { "1": { "electricCurrent": 50 } } } ``` **Subcomponent Power Detection (toggle-electric-power)** **Capability Declaration Example:** ``` [ { "capability": "toggle-electric-power", "permission": "0100", "name": "1" // Component name. **Type:** String. Optional values: "1" (Channel 1), "2" (Channel 2), "3" (Channel 3), "4" (Channel 4). } ] ``` **Attributes (State):** ``` { "electricPower": 50, // Field `electricPower` represents the current power value. **Unit:** 0.01 W. **Type:** Integer. Value must be greater than or equal to 0. "reactivePower": 50, // Field `reactivePower` represents the current reactive power value. **Unit:** 0.01 W. **Type:** Integer. Optional. "activePower": 50, // Field `activePower` represents the current active power value. **Unit:** 0.01 W. **Type:** Integer. Optional. "apparentPower": 50 // Field `apparentPower` represents the current apparent power value. **Unit:** 0.01 W. **Type:** Integer. Optional. } ``` **Protocol (Query Status & Control Instructions):** ``` { "toggle-electric-power": { "1": { "electricPower": 50, "reactivePower": 50, "activePower": 50, "apparentPower": 50 } } } ``` **Subcomponent Power Consumption Statistics (toggle-power-consumption)** **Capability Declaration Example:** ``` [ { "capability": "toggle-power-consumption", "permission": "1101", "name": "1", // Component name. **Type:** String. Optional values: "1" (Channel 1), "2" (Channel 2), "3" (Channel 3), "4" (Channel 4). "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ] ``` **Attributes (State):** Start/Stop Real-time Statistics: ``` { "rlSummarize": true, // Start or stop real-time statistics. **Type:** Boolean. Required. "timeRange": { // Summary time range. Required. "start": "2020-07-05T08:00:00Z", // Start time of the power consumption. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time of the power consumption. **Type:** String. Required. } } ``` Query Power Consumption by Time Range: ``` { "type": "summarize", // Summary type. **Type:** String. Required. Options: "rlSummarize" (Real-time summary), "summarize" (Current summary). "timeRange": { // Summary time range, required when type is "summarize". "start": "2020-07-05T08:00:00Z", // Start time of the power consumption. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time of the power consumption. **Type:** String. Optional. If not provided, defaults to the current time. } } ``` Response for Power Consumption within Time Range: ``` { "type": "summarize", // Summary type. **Type:** String. Required. "rlSummarize": 50.0, // Total power consumption. **Unit:** 0.01 kWh. **Type:** Number. Optional. "electricityIntervals": [ // Divided by `configuration.resolution` into multiple records. Optional. Not present when type is "rlSummarize". { "usage": 26.5, // Power consumption. **Unit:** 0.01 kWh. **Type:** Number. Required. "start": "2020-07-05T08:00:00Z", // Start time. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time. **Type:** String. Required. Records with intervals shorter than resolution are considered invalid. }, { "usage": 26.5, // Power consumption. **Unit:** 0.01 kWh. **Type:** Number. Required. "start": "2020-07-05T09:00:00Z", // Start time. **Type:** String. Required. "end": "2020-07-05T10:00:00Z" // End time. **Type:** String. Required. Records with intervals shorter than resolution are considered invalid. } ] } ``` **Protocol (Query Status & Control Instructions):** Start Real-time Statistics: ``` { "toggle-power-consumption": { "1": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Stop Real-time Statistics: ``` { "toggle-power-consumption": { "1": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Get Historical Power Consumption: ``` { "toggle-power-consumption": { "1": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Get Real-time Power Consumption: ``` { "toggle-power-consumption": { "1": { "type": "rlSummarize" } } } ``` **Link Quality Indicator (lqi)** **Capability Declaration Example:** ``` { "capability": "lqi", "permission": "0100" } ``` **Attributes (State):** ``` { "lqi": 60 // Field `lqi` represents the link quality indicator. **Type:** Number. Value range: 0 to 255. } ``` **Protocol (Query Status & Control Instructions):** ``` { "lqi": { "lqi": 60 } } ``` **Functional Configuration (configuration)** **Capability Declaration Example:** ``` [ { "capability": "configuration", "permission": "1100" } ] ``` **Attributes (State):** ``` { "deviceConfiguration": { // Device-related functional configuration "defaultResolution": 300, // Default resolution for reading moisture saturation data. **Type:** Integer. **Unit:** Seconds. Required. "maxResolution": 86400, // Maximum resolution for reading moisture saturation data. **Type:** Integer. **Unit:** Seconds. Required. "minResolution": 60 // Minimum resolution for reading moisture saturation data. **Type:** Integer. **Unit:** Seconds. Required. } } ``` **Protocol (Query Status & Control Instructions):** ``` { "configuration": { "deviceConfiguration": { // Device-related functional configuration "defaultResolution": 300, // Default resolution for reading moisture saturation data. **Type:** Integer. **Unit:** Seconds. Required. "maxResolution": 86400, // Maximum resolution for reading moisture saturation data. **Type:** Integer. **Unit:** Seconds. Required. "minResolution": 60 // Minimum resolution for reading moisture saturation data. **Type:** Integer. **Unit:** Seconds. Required. } } } ``` **System (system)** **Capability Declaration Example:** ``` [ { "capability": "system", "permission": "1000" } ] ``` **Attributes (State):** ``` { "restart": true // Restart device command. **Type:** Boolean. Required. Value must be `true`. } ``` **Protocol (Query Status & Control Instructions):** ``` { "system": { // Capability-related configuration. Optional. "restart": true } } ``` **Moisture (moisture)** **Capability Declaration Example:** ``` [ { "capability": "moisture", "permission": "0100" } ] ``` **Attributes (State):** ``` { "moisture": 55.5 // Field `moisture` represents the moisture saturation percentage. **Type:** Number. Required. Range: 0 to 100. } ``` **Protocol (Query Status & Control Instructions):** ``` { "moisture": { "moisture": 55.5 } } ``` **Barometric Pressure (barometric-pressure)** **Capability Declaration Example:** ``` [ { "capability": "barometric-pressure", "permission": "0100", "settings": { "barometricPressureRange": { "type": "numeric", "permission": "01", "min": 540, // Minimum value. **Type:** Integer. Required. Must be less than `max`. "max": 1100 // Maximum value. **Type:** Integer. Required. Must be greater than `min`. } } } ] ``` **Attributes (State):** ``` { "barometricPressure": 50 // Barometric pressure value. **Type:** Integer. Required. **Unit:** hPa. } ``` **Protocol (Query Status & Control Instructions):** ``` { "barometric-pressure": { "barometricPressure": 50 } } ``` **Wind Speed (wind-speed)** **Capability Declaration Example:** ``` [ { "capability": "wind-speed", "permission": "0100", "settings": { "windSpeedRange": { "type": "numeric", "permission": "01", "min": 0, // Minimum value. **Type:** Number. Required. Must be less than `max`. "max": 50 // Maximum value. **Type:** Number. Required. Must be greater than `min`. } } } ] ``` **Attributes (State):** ``` { "windSpeed": 50 // Wind speed value. **Type:** Number. Required. **Unit:** m/s (meters per second). } ``` **Protocol (Query Status & Control Instructions):** ``` { "wind-speed": { "windSpeed": 50 } } ``` **Wind Direction (wind-direction)** **Capability Declaration Example:** ``` [ { "capability": "wind-direction", "permission": "0100" } ] ``` **Attributes (State):** ``` { "windDirection": 10 // Wind direction. **Type:** Integer. Required. **Unit:** Degrees. Range: 0 to 360 degrees (clockwise direction). } ``` **Protocol (Query Status & Control Instructions):** ``` { "wind-direction": { "windDirection": 10 } } ``` **Rainfall (rainfall)** **Capability Declaration Example:** ``` [ { "capability": "rainfall", "permission": "0100", "settings": { "rainfallRange": { "type": "numeric", "permission": "01", "min": 0, // Minimum value. **Type:** Number. Required. Must be less than `max`. "max": 450 // Maximum value. **Type:** Number. Required. Must be greater than `min`. } } } ] ``` **Attributes (State):** ``` { "rainfall": 11.11 // Rainfall value. **Type:** Number. Required. **Unit:** mm/h (millimeters per hour). } ``` **Protocol (Query Status & Control Instructions):** ``` { "rainfall": { "rainfall": 11.11 } } ``` **Ultraviolet Index (ultraviolet-index)** **Capability Declaration Example:** ``` [ { "capability": "ultraviolet-index", "permission": "0100", "settings": { "ultravioletIndexRange": { "type": "numeric", "permission": "01", "min": 0, // Minimum value. **Type:** Number. Required. Must be less than `max`. "max": 16 // Maximum value. **Type:** Number. Required. Must be greater than `min`. } } } ] ``` **Attributes (State):** ``` { "ultravioletIndex": 11.1 // Ultraviolet index. **Type:** Number. Required. } ``` **Protocol (Query Status & Control Instructions):** ``` { "ultraviolet-index": { "ultravioletIndex": 11.1 } } ``` **Electrical Conductivity (electrical-conductivity)** **Capability Declaration Example:** ``` [ { "capability": "electrical-conductivity", "permission": "0100", "settings": { "electricalConductivityRange": { "type": "numeric", "permission": "01", "min": 0, // Minimum value. **Type:** Number. Required. Must be less than `max`. "max": 23 // Maximum value. **Type:** Number. Required. Must be greater than `min`. } } } ] ``` **Attributes (State):** ``` { "electricalConductivity": 11.11 // Electrical conductivity value. **Type:** Number. Required. **Unit:** dS/m. } ``` **Protocol (Query Status & Control Instructions):** ``` { "electrical-conductivity": { "electricalConductivity": 11.11 } } ``` **Transmit Power (transmit-power)** **Capability Declaration Example:** ``` [ { "capability": "transmit-power", "permission": "1100" } ] ``` **Attributes (State):** ``` { "transmitPower": 9 // Device transmit power value. **Type:** Integer. Required. **Unit:** dBm. } ``` **Protocol (Query Status & Control Instructions):** ``` { "transmit-power": { "transmitPower": 9 } } ``` **PM2.5 Detection (pm25)** **Capability Declaration Example:** ``` [ { "capability": "pm25", "permission": "0100" } ] ``` **Attributes (State):** ``` { "pm25": 10 // PM2.5 concentration in the air. **Type:** Number. Required. **Unit:** µg/m³. } ``` **Protocol (Query Status & Control Instructions):** ``` { "pm25": { "pm25": 10 } } ``` **VOC Index (voc-index)** **Capability Declaration Example:** ``` { "capability": "voc-index", "permission": "0100" } ``` **Attributes (State):** ``` { "vocIndex": 10 // VOC index reflecting the level of harmful gas pollution. **Type:** Number. Required. **Unit:** µg/m³. } ``` **Protocol (Query Status & Control Instructions):** ``` { "voc-index": { "vocIndex": 10 } } ``` **Natural Gas Detection (gas)** **Capability Declaration Example:** ``` { "capability": "gas", "permission": "0100" } ``` **Attributes (State):** ``` { "gas": true // Indicates whether natural gas leakage is detected. **Type:** Boolean. Required. } ``` **Protocol (Query Status & Control Instructions):** ``` { "gas": { "gas": true } } ``` **Irrigation Work Status (irrigation/work-status)** **Capability Declaration Example:** ``` [ { "capability": "irrigation", "permission": "0101", "name": "work-status", "settings": { "volumeUnit": { "type": "enum", "permission": "01", "values": ["L"], "value": "L" } } } ] ``` **Attributes (State):** ``` { "realTimeVolume": 20, // Real-time irrigation volume. **Type:** Number. Optional. **Unit:** L. "start": "2020-07-05T08:00:00Z", // Irrigation start time. **Type:** Date. Optional. "end": "2020-07-05T09:00:00Z", // Irrigation end time. **Type:** Date. Optional. "dailyVolume": 20 // Daily irrigation volume. **Type:** Number. Optional. **Unit:** L. } ``` **Protocol (Query Status & Control Instructions):** Work Status Reporting: ``` { "irrigation": { "work-status": { "realTimeVolume": 20, "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z", "dailyVolume": 20 } } } ``` Work Status Query: ``` { "irrigation": { "type": "oneDay", // Aggregation type. **Type:** String. Required. Options: "oneDay", "30Days", "180Days". "timeRange": { // Time range for aggregation. **Type:** Object. Required. "start": "2020-07-05T08:00:00Z", // Start time for irrigation data aggregation. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time for irrigation data aggregation. **Type:** String. Optional. If omitted, current time is used. } } } ``` Work Status Query Result: ``` { "irrigation": { "type": "oneDay", // Aggregation type. **Type:** String. Required. "irrigationIntervals": [ { "volume": 6500, // Irrigation volume. **Type:** Number. Required. **Unit:** L. "duration": 30, // Irrigation duration. **Type:** Number. Required. **Unit:** minutes. "start": "2020-07-05T08:00:00Z", // Start time. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time. **Type:** String. Required. }, { "volume": 6500, // Irrigation volume. **Type:** Number. Required. **Unit:** L. "duration": 30, // Irrigation duration. **Type:** Number. Required. **Unit:** minutes. "start": "2020-07-05T08:00:00Z", // Start time. **Type:** String. Required. "end": "2020-07-05T09:00:00Z" // End time. **Type:** String. Required. } ] } } ``` **Irrigation Work Mode (irrigation/work-mode)** **Capability Declaration Example:** ``` [ { "capability": "irrigation", "permission": "0100", "name": "work-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", // Manual mode "TIMER", // Single-time scheduling "CYCLE-TIMER", // Repeated scheduling "VOLUME", // Single-time volume "CYCLE-VOLUME" // Repeated volume ] } } } ] ``` **Attributes (State):** ``` { "workMode": "MANUAL" // Irrigation work mode. **Type:** String. Optional. Values should be from `settings.supportedModes`. } ``` **Protocol (Query Status & Control Instructions):** ``` { "irrigation": { "work-mode": "MANUAL" } } ``` **Automatic Irrigation Controller (irrigation/auto-controller)** **Capability Declaration Example:** ``` [ { "capability": "irrigation", "permission": "1100", "name": "auto-controller", "settings": { "volumeRange": { // Volume range "type": "enum", "permission": "01", "min": 0, "max": 6500, "unit": "L" }, "timeRange": { // Time range "type": "enum", "permission": "01", "min": 1, "max": 86400, "unit": "second" }, "cycleCountRange": { // Cycle count range "type": "enum", "permission": "01", "min": 1, "max": 100, "step": 1 } } } ] ``` **Attributes (State):** Single-Time or Repeated Scheduling: ``` { "type": "time", // Irrigation mode. **Type:** String. Required. Options: "volume", "time". "action": { "perDuration": 60, // Duration per irrigation cycle. **Type:** Number. Required. "intervalDuration": 20, // Interval between irrigation cycles. **Type:** Number. Required. "count": 3 // Number of irrigation cycles. **Type:** Number. Required. } } ``` Single-Time or Repeated Volume: ``` { "type": "volume", // Irrigation mode. **Type:** String. Required. Options: "volume", "time". "action": { "perConsumedVolume": 60, // Volume consumed per irrigation cycle. **Type:** Number. Required. "intervalDuration": 20, // Interval between irrigation cycles. **Type:** Number. Required. "count": 3 // Number of irrigation cycles. **Type:** Number. Required. } } ``` **Protocol (Query Status & Control Instructions):** Single-Time or Repeated Scheduling: ``` { "irrigation": { "auto-controller": { "type": "time", // Irrigation mode. **Type:** String. Required. "action": { "perDuration": 60, // Duration per irrigation cycle. **Type:** Number. Required. "intervalDuration": 20, // Interval between cycles. **Type:** Number. Required. "count": 3 // Number of cycles. **Type:** Number. Required. } } } } ``` Single-Time or Repeated Volume: ``` { "irrigation": { "auto-controller": { "type": "volume", // Irrigation mode. **Type:** String. Required. "action": { "perConsumedVolume": 60, // Volume consumed per cycle. **Type:** Number. Required. "intervalDuration": 20, // Interval between cycles. **Type:** Number. Required. "count": 3 // Number of cycles. **Type:** Number. Required. } } } } ``` **Supported Preset Modes** | \*\*Mode Names \*\* | \*\*Optional Values \*\* | | ------------------------------------------------- | ------------------------ | | fanLevel (fan Level) | "low" | | "medium" | | | "high" | | | thermostatMode(Thermostat Mode) | "auto" | | "manual" | | | airConditionerMode >= 1.11.0(airConditioner Mode) | "cool" | | "heat" | | | "auto" | | | "fan" | | | "dry" | | | fanMode >= 1.11.0(Fan Mode) | "normal" | | "sleep" | | | "child" | | | horizontalAngle >= 1.11.0(Horizontal Angle) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | | verticalAngle >= 1.11.0(Vertical Angle) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | #### c. Tags Description * The special key toggle is used to set the name of the toggle subcomponent. ``` { "toggle": { '1': 'Chanel1', '2': 'Chanel2', '3': 'Chanel3', '4': 'Chanel4', }, } ``` * The special key temperature\_unit is used to set the temperature unit. ``` { "temperature_unit":'c' // c-Celsius; f-Fahrenheit } ``` #### d. Special Error Code and Description | **Error Code** | **Description** | iHost Version | | -------------- | ----------------------------------------------------------------------------------------- | ------------- | | 110000 | The sub-device/group corresponding to the id does not exist | ≥2.1.0 | | 110001 | The gateway is in the state of discovering zigbee devices | ≥2.1.0 | | 110002 | Devices in a group do not have a common capability | ≥2.1.0 | | 110003 | Incorrect number of devices | ≥2.1.0 | | 110004 | Incorrect number of groups | ≥2.1.0 | | 110005 | Device Offline | ≥2.1.0 | | 110006 | Failed to update device status | ≥2.1.0 | | 110007 | Failed to update group status | ≥2.1.0 | | 110008 | The maximum number of groups has been reached. Create up to 50 groups | ≥2.1.0 | | 110009 | The IP address of the camera device is incorrect | ≥2.1.0 | | 110010 | Camera Device Access Authorization Error | ≥2.1.0 | | 110011 | Camera device stream address error | ≥2.1.0 | | 110012 | Camera device video encoding is not supported | ≥2.1.0 | | 110013 | Device already exists | ≥2.1.0 | | 110014 | Camera does not support offline operation | ≥2.1.0 | | 110015 | The account password is inconsistent with the account password in the RTSP stream address | ≥2.1.0 | | 110016 | The gateway is in the state of discovering onvif cameras | ≥2.1.0 | | 110017 | Exceeded the maximum number of cameras added | ≥2.1.0 | | 110018 | The path of the ESP camera is wrong | ≥2.1.0 | | 110019 | Failed to access the service address of the third-party device | ≥2.1.0 | #### e. Search for Sub-device Allow authorized users to enable or disable gateway search for sub-devices through this interface * 💡Note: Only supports searching for Zigbee sub-devices now. * 💡Note: Zigbee sub-devices will be added automatically after searching. Do not need to use the "Manually Add Sub-devices" interface :::tips * **URL**：/open-api/V2/rest/devices/discovery * **Method**: PUT * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------ | | enable | boolean | N | true (Start paring); false (Pause pairing) | | type | string | N | Searching Type: Zigbee | Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\* `200 OK` ::: **Response Example**: ``` { "error": 0, "data": {}, "message": "success" } ``` #### f. Manually Add the Sub-device Allow authorized users to add a **single** sub-device through this interface. * Note: Only RTSP Camera and ESP32 Camera are supported now :::tips * **URL**：/open-api/V2/rest/devices * **Method**：POST * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ----------------- | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------- | | name | string | N | Sub-device name | | display\_category | string | N | Device Type. Only support camera。 | | capabilities | CapabilityObject\[] | N | Capability list. When display\_category = camera, capabilities only include camera-stream capabilities. | | protocal | string | N | Device protocol. RTSP; ESP32-CAM | | manufacturer | string | N | Manufacturer. | | model | string | N | Device model | | firmware\_version | string | N | Device firmware version | CapabilityObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------------------------- | ------------ | --------------------------------------------- | | capability | string | N | Capability name. Only support "camera-stream" | | permission | string | N | Device permission. Only support read. | | configuration | CameraStreamConfigurationObject | Y | Camera stream configuration. | SettingsObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------------- | ------------ | ---------------------------- | | streamSetting | StreamSettingObject | N | Stream service configuration | StreamSettingObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------------------ | ------------ | ------------------------------------------------------- | | type | string | N | Stream service configuration | | permission | string | N | Capability permission. Only supports "11" (modifiable). | | value | StreamSettingValueObject | N | Specific configuration values | StreamSettingValueObject | **Attribute** | **Type** | **Optional** | **Description** | | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------- | | stream\_url | string | N | Stream URL Format | | Format:`://:/:@` | | | | | Example:`rtsp://admin:123456@192.168.10.115:554/streaming/channel01` | | | | | Schema Options: | | | | | `rtsp` (Real-Time Streaming Protocol) | | | | | `http` (Hypertext Transfer Protocol) — For ESP32-CAM devices | | | | | \*Note: Some cameras may not require a username or password. In such cases, you can omit the `` and `` fields from the URL. | | | | Successful data response: | **Attribute** | **Type** | **Optional** | **Description** | | -------------- | -------- | ------------ | --------------------------- | | serial\_number | string | N | Device unique serial number | :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ``` { "error": 0, "data": { "serial_number": "serial_number" }, "message": "success" } ``` Failure data response: empty Object :::tips **Condition**： 1. Camera stream address access error (format error, authorization failure, network exception, etc.) 2. Device already exists 3. If a single device fails to add, returns all devices fail to add. **Status Code**: 200 OK **Error code**： ● 110009 Camera IP address error ● 110010 Camera access authorization error ● 110011 Camera stream address error ● 110012 The Camera video encoding does not support ● 110013 Device already exists ::: **Response Example**: ``` { "error": 110009, "data": {}, "message": "camera ip access failed" } ``` #### g. Get List of Sub-devices Allow authorized users to obtain the list of gateway sub-device through this interface. :::tips * **URL**：/open-api/V2/rest/devices * **Method**: GET * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request Parameters: none Successful data response: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------------------- | ------------ | --------------- | | device\_list | ResponseDeviceObject\[] | N | Device list | ResponseDeviceObject | **Attribute** | **Type** | **Optional** | **Description** | | --------------------- | ------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique serial number | | third\_serial\_number | string | "N" when a third-party device is connected, otherwise "Y" | Third-party device unique serial number | | service\_address | string | "N" when a third-party device is connected, otherwise "Y" | Third-party service address | | name | string | N | Device name, if it is not renamed, will be displayed by the front end according to the default display rules. | | manufacturer | string | N | Manufacturer | | model | string | N | Device model | | firmware\_version | string | N | Firmware version. Can be an empty string. | | hostname | string | Y | Device hostname | | mac\_address | string | Y | Device mac address | | app\_name | string | Y | The name of the application to which it belongs. If the app\_name is filled in when obtaining the open interface certificate, then all subsequent devices connected through the certificate will be written into this field. | | display\_category | string | N | Device category | | capabilities | CapabilityObject\[] | N | Device capabilities | | protocol | string | "N" when a third-party device is connected, otherwise "Y" | Device protocol: zigbee, onvif, rtsp, esp32-cam | | state | object | Y | Device state object. For state examples of different capabilities, please check 【Support Device Capabilities】 | | tags | object | Y | JSON format key-value, custom device information. The function is as follows:- Used to store device channels- Used to store temperature units- Custom information for other third-party devices | | online | boolean | N | Online status: True for onlineFalse is offline | | subnet | boolean | Y | Whether it is in the same subnet as the gateway | CapabilityObject 💡Note: Please check the Examples of Supported Device Capabilities for \[Supported Device Capabilities]. | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | capability | string | N | Ability name. For details, check \[Supported Device Capabilities] | | permission | string | N | Capability permission. Possible values are "read" (readable), "write" (writable), "readWrite" (readable and writable). | | configuration | object | Y | Capability configuration information. Currently camera-stream is used, check \[Supported Device Capabilities] | | name | string | Y | The name field in toggle. The sub-channel number used to identify multi-channel devices. For example, if name is 1, it means channel 1. | :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ``` { "error": 0, "data":{ "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "My Device", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" }, { "capability": "rssi", "permission": "read" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ], } "message": "success" } ``` #### h. Update Specified Device Information or State Allow authorized users to modify the basic information of sub-device and issue control commands through this interface. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Method**：PUT * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | name | string | Y | Device name | | tags | object | Y | JSON format key-value, custom device information. | | state | object | Y | Device state object. For state examples of different capabilities, please check \[Support Device Capabilities] | | configuration | object | Y | Capability configuration information, currently only the camera\_stream capability supports modification. | Successful data response: :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK **Error Code**: * 110000 The sub-device/group corresponding to the id does not exist ::: **Response Example**: ``` { "error": 0, "data":{ "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "我的设备", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "1100" }, { "capability": "rssi", "permission": "0100" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true }, "message": "success" } ``` #### i. Delete Sub-device Allow authorized users to delete sub-devices through this interface. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Method**：DELETE * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Device name. | | tags | object | Y | Key-value pairs in JSON format used to store device channel names and other information about sub-devices. | | state | object | Y | Change device status; for specific protocol details, refer to "Supported Device Capabilities." | | capabilities | CapabilityObject \[] | Y | Capability configuration information; all capabilities that support setting configurations can be modified. Note that permissions cannot be changed. | Successful data response: :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK **Error Codes:** * 110000: The sub-device/group corresponding to the ID does not exist. * 110006: Failed to update device status. * 110019: Failed to access third-party device service address. * 110024: Failed to update device configuration. ::: **Response Example**: ``` { "error": 0, "data": {}, "message": "success" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // turn on device await axios({ url: `http:///open-api/v2/rest/devices/${serial_number}`, method: 'PUT', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${access_token}` }, data: { state: { power: { powerState: 'on' } } } }); })() ``` #### j. Delete Sub-Device Allows authorized users to delete sub-devices through this interface.\ :::tips * **URL**：`/open-api/v2/rest/devices/{serial_number}` * **Method**：`DELETE` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: None Successful data response: :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### k. Query Device Status Allows authorized users to query device status through this interface.\ :::tips * **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}` * **Method**：POST * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------- | | query\_state | object | N | Query device status; for specific protocol details, refer to "Supported Device Capabilities." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // turn on device await axios({ url: `http:///open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`, method: 'PUT', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${access_token}` }, data: { "query_state":{ "power-consumption":{ "type": "summarize", // Type of statistics, required "timeRange": { // Time range for summarization, required when type="summarize" "start": "2020-07-05T08:00:00Z", // Start time for power consumption statistics "end": "2020-07-05T09:00:00Z" // End time for power consumption statistics; if omitted, defaults to current time } } } }); })() ``` Successful data response: :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.4 Security Management #### a. Get Security List Allows authorized users to modify gateway settings through this interface. :::tips * **URL**：`/open-api/v2/rest/security` * **Method**：`GET` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: None Successful data response: | **Attribute** | **Type** | **Optional** | **Description** | | -------------- | ------------------------- | ------------ | --------------- | | security\_list | ResponseSecurityObject\[] | N | 响应设备列表 | ResponseDeviceObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | sid | int | N | 安防id | | name | string | N | 安防名称 | | enable | bool | N | 是否启用 | * true 启用 * false 禁用 | :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": { "security_list":[ { "sid": 1, "name": "Home Mode", "enable": true } ] }, "message": "success" } ``` #### b. Enable Specified Security Mode Allows authorized users to enable a specified security mode through this interface.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/enable` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: None Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### c. Disable Specified Security Mode Allows authorized users to disable a specified security mode through this interface.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/disable` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: None Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. One-Click Enable Security Setup Allows authorized users to enable the one-click security setup mode through this interface.\ :::tips * **URL**：`/open-api/v2/rest/security/enable` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: None Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### e. Disable Security Allows authorized users to disable security through this interface.\ :::tips * **URL**：`/open-api/v2/rest/security/disable` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request parameters: None Successful data response:empty Object {} :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*200 OK ::: **Response Example**: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 4. Third-party Device Access ### 4.1 Access Instruction #### Device Access
#### Third-party gateway Access
#### Access steps 1. Determine the classification of the device in the gateway. The detail please check the \[Supported Device Type]. 2. Determine the capabilities that the device can access. The detail please check the \[Supported Device Capabilities]. 3. Request the \[Discovery Request] interface to add the device to the gateway. 1. *Attention: You need to provide the service address for receiving the instructions issued by the gateway, which is used to receive the device control instructions issued by the gateway*. 4. If the status of the third-party device changes, you need to call the \[Device States Change Report] interface to send the latest status back to the gateway. 5. After adding, the third-party device will appear in the Device List, with most of the functions of the gateway (other non-third-party devices). The common open interfaces related to the device can be used normally. * Select the appropriate device category. The classification will affect the final display result of the UI after the device is connected to the gateway. * Choose the right device capability. The capability list will determine the status of the device state protocol. #### Program Process **a. Device Access**
**b. Third-party Gateway Access**
### 4.2 Access Example #### Switch, Plug **Sync third-party devices** ``` // Request URL：/open-api/v2/rest/thirdparty/event Method：POST Header： Content-Type: application/json Autorization: Bearer Body: { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "my plug", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "1100" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "firmware version", "service_address": "http://192.168.31.14/webhook" } ] } } } ``` ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number", "serial_number": "serial number" } ] } } ``` **Report device status** ``` URL：/open-api/V2/rest/thirdparty/event Method：POST Header： Content-Type: application/json Autorization: Bearer Body: { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } ``` **Report offline/online** ``` {  "event": {    "header": {      "name": "DeviceStatesChangeReport",      "message_id": "Unique identifier, preferably a version 4 UUID",      "version": "1"   },    "endpoint": {      "serial_number": "serial_number"   },    "payload": {       "online": true   } } } ``` ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } ``` **Receive the instructions about the gateway control device** ``` URL： Method：POST Header：  Content-Type: application/json B {  "directive": {    "header": {      "name": "UpdateDeviceStates",      "message_id": "Unique identifier, preferably a version 4 UUID",      "version": "1"   },    "endpoint": {      "third_serial_number": "third_serial_number",      "serial_number": "serial_number"   },    "payload": {       "state": : {         "power": {           "powerState": "on"         }       }   } } } ``` ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } ``` **Query device** ``` URL：/open-api/V2/rest/devices Method：GET Header：  Content-Type: application/json  Autorization: Bearer   Body: 无 ``` ``` { "error": 0, "data": { "device_list": [ { "serial_number": "serial number", "third_serial_number": "third_serial_number", "name": "my plug", "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "firmware version", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] }, "message": "success" } ``` ### 4.3 Web API #### Third-Party Request Gateway Interface **Request Format** Allow authorized users to send event requests to the gateway through this interface. :::tips * **URL**：/open-api/V2/rest/thirdparty/event * **Method**：POST * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------- | ------------ | ------------------------------------------ | | event | EventObject | N | Request event object structure information | EventObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------- | | header | HeaderObject | N | Request header structure information | | endpoint | EndpointObject | Y | Request endpoint structure informationNote: This field is empty when sync a new device list. | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Request name. optional parameter: DiscoveryRequest: Sync new devices DeviceStatesChangeReport: Device status update report DeviceOnlineChangeReport: Device online status report | | message\_id | string | N | Request message ID, UUID\_V4 | | version | string | N | Request protocol version number. Currently fixed at 1 | EndpointObject | **Attribute** | **Type** | **Optional** | **Description** | | --------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique serial number | | third\_serial\_number | string | N | Third-party device unique serial number | | tags | object | Y | JSON format key-value, custom device information. \[Device Management Function] - \[Tags Description] | PayloadObject According to the different header.name have different request structure. **Response Format** :::tips \*\*Status Code: \*\*200 OK **Response parameters:** ::: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | -------------------------------------- | | header | HeaderObject | N | Response header structure information | | payload | PayloadObject | N | Response payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | N | Response header name. optional parameters:Response: Successful response ErrorResponse: Error response | | message\_id | string | N | Response header message ID, UUID\_V4. Pass in the request message header.message\_id here\*If the request input parameter lacks message\_id, this field will be an empty string when responding. | | version | string | N | - Request protocol version number. Currently fixed at 1. | > Successful response--PayloadObject ： Depending on the request type, the response structure is different. For details, please refer to the specific request instruction document. > Failure response--PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | type | string | N | Error Types: | * INVALID\_PARAMETERS: Parameter error * AUTH\_FAILURE: Authorization error * INTERNAL\_ERROR: Internal service error | | description | string | N | Error description | **DiscoveryRequest Sync a new device list** * Note: After the device is synchronized to the gateway, it is online by default, that is, online=true. Subsequent online changes are completely dependent on synchronization with the third party through the DeviceOnlineChangeReport interface. **Request parameters:** EndpointObject\*\*：\*\*None PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------------- | ------------ | --------------- | | endpoints | EndpointObject\[] | N | Device List | EndpointObject: | **Attribute** | **Type** | **Optional** | **Description** | | --------------------- | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | third\_serial\_number | string | N | Third-party device unique serial number | | name | string | N | Device name | | display\_category | string | N | Device Category. See the \[Supported Device Type] for details. \*Three-party devices don't support adding cameras now. | | capabilities | CapabilityObject\[] | N | Capabilities list | | state | object | N | Initial state information | | manufacturer | string | N | Manufacturer | | model | string | N | Device model | | tags | object | Y | JSON format key-value, custom device information:Be used to store device channelsBe used to store temperature unitsOther third-party custom data | | firmware\_version | string | N | Firmware version | | service\_address | string | N | Service address. Such as | Example of Request : ``` { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "my plug", "display_category": "plug", "capabilities": [ { "capability": "power", "permission" "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "firmware version", "service_address": "http://192.168.31.14/service_address" } ] } } } ``` **Response parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------------- | ------------ | --------------- | | endpoints | EndpointObject\[] | N | Device list | EndpointObject: | **Attribute** | **Type** | **Optional** | **Description** | | --------------------- | -------- | ------------ | --------------------------------------- | | serial\_number | string | N | Device unique serial number | | third\_serial\_number | string | N | Third-party device unique serial number | Example of a correct response: ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "endpoints": [ { "serial_number": "serial number", "third_serial_number": "third_serial_number" } ] } } ``` Example of an error response: ``` { "header": { "name": "ErrorResponse", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "webhook cannot be empty" } } ``` **DeviceStatesChangeReport Device status change report** * Note: Repeated status reports may falsely trigger associated scene. **Request parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------------------ | | state | object | N | Devicce state, See \[Supported device cabilities] for detail | Example of Request : ``` { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Response parameters:** PayloadObject: Empty Object Example of a successful response: ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } ``` **DeviceOnlineChangeReport Device online status report** * Note: Repeated status reports may falsely trigger associated scene. **Request parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | -------------- | -------- | ------------ | --------------------------------- | | online | boolean | N | Device online status true: Online | | false: Offline | | | | Example of Request : ``` { "event": { "header": { "name": "DeviceOnlineChangeReport", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": true } } } ``` **Response parameters:** PayloadObject: Empty Object Example of a successful response: ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } ``` **DeviceInformationUpdatedReport Device Information Updated Report** * Note: Updating may affect existing scenes or security functions. **Request parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | capabilities | | | | \| CapabilityObject\[] \| N \| Capabilities List. Details can be found in the supported device capabilities section. \*\*Note: \*\*This parameter will only update the `value` of the `setting` key within the `CapabilityObject`, and updates are allowed only if the `permission` for the `setting` key is `11` or `01`. For the specific structure definition of the `setting` in `CapabilityObject`, refer to the detailed description in section 2.3 Device Display Categories & Device Capabilities. | | tags \| object \| Y \| JSON format key-value, custom device information. * Can be used to store device channels * Can be used to store temperature units * Other third-party custom data | Example of Request : ```json { "event": { "header": { "name": "DeviceInformationUpdatedReport", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "capabilities": [ { "capability": "detect", "permission": "0110", "settings":{ "detectInterval":{ "permission": "11", "type": "numeric", "value": 300, }, "detectSensitivity":{ "permission": "11", "type": "numeric", "value": 1000, } } } ] } } } ``` **esponse parameters:** PayloadObject: Empty Object Example of a successful response: ```json { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "payload": {} } ``` #### Gateway sends the instruction interface through the device service address * Note: 1. The three parties need to respond to the gateway's request within 3s. Otherwise, the gateway will judge the command processing timeout. 2. If the third-party service is offline, the gateway will set the device to an offline state, and the third-party service needs to report the device state (DeviceStatesChangeReport) or the online state (DeviceOnlineChangeReport) before returning to the online state. **Request format** Gateway sends instructions to the third-party through the device service address interface. :::tips * **URL**： * **Method**：POST * **Header**： * Content-Type: application/json ::: Request parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | --------------- | ------------ | -------------------------------------- | | directive | DirectiveObject | N | Directive object structure information | DirectiveObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------------- | ------------ | -------------------------------------- | | header | HeaderObject | N | Request header structure information | | endpoint | EndpointObject | N | Request endpoint structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | -------------------------------------------------------------------------- | | name | string | N | Request name. Optional parameters:UpdateDeviceStates: Update device states | | message\_id | string | N | Request message ID, UUID\_V4 | | version | string | N | Request protocol version number. Currently fixed at 1. | EndpointObject | **Attribute** | **Type** | **Optional** | **Description** | | --------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique serial number | | third\_serial\_number | string | N | Third-party device unique serial number | | tags | object | N | JSON format key-value, custom device information. \[Device Management Function] - \[Tags Description] | PayloadObject: According to different `header.name`, there is a specific request structure for each. Example of Request : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", "tags": {} }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Response format** :::tips \*\*HTTP Status Code: \*\*200 OK **HTTP Response Attribute：** ::: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------- | ------------ | ------------------------------------ | | event | EventObject | N | Response event structure information | EventObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Response header name. Optional parameter: UpdateDeviceStatesResponse: Update device states response ErrorResponse: Error response | | message\_id | string | N | Response header message ID, UUID\_V4. Pass in the request message header.message\_id here | | version | string | N | Request protocol version number. Currently fixed at 1. | > Successful response--PayloadObject： Depending on the request type, the response structure is different. For details, please refer to the specific request instruction document. > Failure response--PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ---------------- | | type | string | N | **Error Types**: | * **ENDPOINT\_UNREACHABLE**: Device is unreachable or offline * **ENDPOINT\_LOW\_POWER**: Device is in low power mode and cannot be controlled * **INVALID\_DIRECTIVE**: Abnormal directive from the gateway * **NO\_SUCH\_ENDPOINT**: Device does not exist * **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: Current mode does not support the operation * **INTERNAL\_ERROR**: Internal service error * **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Remote control key code not learned | :::tips **Conditions**: The request parameters are legal. \*\*Status Code: \*\*200 OK **Response parameters:** ::: ``` { "event": { "header": { "name": "UpdateDeviceStatesResponse", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } } ``` ``` { "event": { "header": { "name": "ErrorResponse", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "type": "ENDPOINT_UNREACHABLE" } } } ``` **UpdateDeviceStates** **Request parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------------------- | | state | object | N | Devicce state, See \[Supported device cabilities] for detail. | Example of Request : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": : { "power": { "powerState": "on" } } } } } ``` **Response parameters:** PayloadObject：empty Object Example of Successful Response ``` { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } ``` **QueryDeviceStates** **Request parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------------------- | | state | object | N | Devicce state, See \[Supported device cabilities] for detail. | Example of Request : ```json { "directive": { "header": { "name": "QueryDeviceStates", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "state": { "power-consumption": { "timeRange": { "start": "2020-07-05T08:00:00Z", // Start time for power consumption statistics, required. "end": "2020-07-05T09:00:00Z" // End time for power consumption statistics, required. } } } } } } ``` **Response parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------------------- | | state | object | N | Devicce state, See \[Supported device cabilities] for detail. | **Response example:** ```json { "event": { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "payload": { "state": { "power-consumption": { "electricityIntervals": [ // Divided into multiple records based on configuration.resolution { "usage": 26.5, // Power consumption value, required. Type: number. "start": "2020-07-05T08:00:00Z", // Start time, required. Type: date. "end": "2020-07-05T09:00:00Z" // End time, required. Type: date. If the interval between end and start is less than resolution, all reported records are considered invalid. }, { "usage": 26.5, // Power consumption value, required. Type: number. "start": "2020-07-05T09:00:00Z", // Start time, required. Type: date. "end": "2020-07-05T10:00:00Z" // End time, required. Type: date. If the interval between end and start is less than resolution, all reported records are considered invalid. } ] } } } } } ``` **ConfigureDeviceCapabilities** **Request parameters:** PayloadObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------------- | ------------ | --------------------------------------------------- | | capabilities | CapabilityObject\[] | N | 能力列表。详情可看支持的设备能力部分。注意，permission字段不可更改，传入同步时相同的值即可。 | Example of Request : ```json { "directive": { "header": { "name": "ConfigureDeviceCapabilities", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Type of temperature control detection, required. Optional values: humidity (humidity detection), temperature (temperature detection) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Supported detection settings, required. { "name": "lowerSetpoint", // Minimum value the detection should maintain. Either lowerSetpoint or upperSetpoint must be provided. "value": { // Detection range, optional. Fill in if there are preset conditions. "value": 68.0, // Temperature or humidity value, required. "scale": "f" // Temperature unit, required if name=temperature. Options: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Maximum value the detection should maintain. Either lowerSetpoint or upperSetpoint must be provided. "value": { // Detection range, optional. Fill in if there are preset conditions. "value": 68.0, // Temperature or humidity value, required. "scale": "f" // Temperature unit, required if name=temperature. Options: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } } ``` **Response parameters:** PayloadObject：empty Object Example of Successful Response ```json { "event": { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "2" }, "payload": {} } } ``` ## 5. Server-sent events > MDN EventSource interface description： ### 5.1 Instruction The gateway supports pushing messages to the client using SSE (Server-sent events). The client can monitor SSE messages after obtaining the access credentials and can parse the content of the push messages according to the development interface event notification protocol after receiving the messages pushed by the gateway. It should be noted that the gateway currently uses the HTTP1.1 protocol, so SSE on the browser side there will be a maximum of no more than 6 connections limit (Specific instructions can be found in the MDN EventSource interface description.) ### 5.2 Common Format :::tips * **URL**：/open-api/V2/sse/bridge * **Method**：`GET` ::: Request parameters: | Name | Type | Optional | Description | | ------------- | ------ | -------- | ------------ | | access\_token | string | N | Access Token | Note: When requesting an SSE connection, the gateway will check the access\_token, and it will return an authentication failure error if it is invalid. { "error": 401, "data": {}, "message": "invalid access\_token"} > \## For example: Module Name: device Version: 1,v2,v3 Message Type: addDevice Example: ```javascript const evtSource = new EventSource("http:///open-api/v2/sse/bridge?access_token=xxxxxx"); evtSource.addEventListener('device#v2#addDevice',function (event) { try { const data = JSON.parse(event.data); console.log('data', data); } catch (error) { console.error(`parse error`,error); } } ``` ### 5.3 Device Module #### a. Add Device Event :::tips Module Name：device Version：v2 Message Type：addDevice event.data parameters： ::: | Name | Type | Optional | Description | | ------- | ------------------------------------------------------------------------ | -------- | ------------------ | | payload | ResponseDeviceObjectObject - Interface the same with the Get Device List | N | device information | Example: ```json // event.data { "payload": { "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "Mydevice", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "1100" }, { "capability": "rssi", "permission": "0100" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } } ``` #### b. Update Device State Event :::tips Module Name：device Version：v2 Message Type：updateDeviceState event.data parameters： ::: | Name | Type | Optional | Description | | -------- | ---------------------------------------------- | -------- | ------------------ | | endpoint | EndpointObject | N | Device Information | | payload | object。 Structure the same as the device state | N | Device Status Data | EndpointObject: | Parameter | Type | Optional | Description | | --------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique Serial Number | | third\_serial\_number | string | Y | The unique serial number of the third-party device. For devices connected through open interfaces, this field is required. | Example: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "power": { "powerState": "on" }, "brightness": { "brightness": 100 } } } ``` #### c. Update Device Info Event :::tips Module Name：device Version：v2 Message Type：updateDeviceInfo event.data parameters： ::: | Name | Type | Optional | Description | | -------- | ------------------ | -------- | ------------------ | | endpoint | EndpointObject | N | Device Information | | payload | DeviceChangeObject | N | Device Change Data | EndpointObject: | Attribute | Type | Optional | Description | | --------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique Serial Number | | third\_serial\_number | string | Y | The unique serial number of the third-party device. For devices connected through open interfaces, this field is required. | DeviceChangeObject | Name | Type | Optional | Description | | ------------ | -------------------- | -------- | ------------------------------------------------------------------------------------------ | | name | string | N | Device Name | | capabilities | CapabilityObject \[] | Y | Device capabilities list. | | tags | object | Y | **tags**`object` \| Nullable \| JSON format key-value pairs for custom device information. | * Can be used to store device channels. * Can be used to store temperature units. * For other third-party custom data. | Example: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "name": "device name", "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Type of temperature control detection, required. Optional values: humidity (humidity detection), temperature (temperature detection) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Supported detection settings, required. { "name": "lowerSetpoint", // Minimum value the detection should maintain. Either lowerSetpoint or upperSetpoint must be provided. "value": { // Detection range, optional. Fill in if there are preset conditions. "value": 68.0, // Temperature or humidity value, required. "scale": "f" // Temperature unit, required if name=temperature. Options: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Maximum value the detection should maintain. Either lowerSetpoint or upperSetpoint must be provided. "value": { // Detection range, optional. Fill in if there are preset conditions. "value": 68.0, // Temperature or humidity value, required. "scale": "f" // Temperature unit, required if name=temperature. Options: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } ``` #### d. Delete Device Event :::tips Module Name：device Version：v2 Message Type：deleteDevice event.data parameters： ::: | \*\* Name \*\* | \*\* Type \*\* | \*\* Optional\*\* | \*\* Description \*\* | | -------------- | -------------- | ----------------- | --------------------- | | endpoint | EndpointObject | N | Device Information | EndpointObject: | Attribute | Type | Optional | Description | | --------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique Serial Number | | third\_serial\_number | string | Y | The unique serial number of the third-party device. For devices connected through open interfaces, this field is required. | Example: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" } } ``` #### e. Update Device Online Event :::tips Module Name：device Version：v2 Message Type：updateDeviceOnline event.data parameters： ::: | Name | Type | Optional | Description | | -------- | ------------------ | -------- | ------------------ | | endpoint | EndpointObject | N | Device Information | | payload | DeviceChangeObject | N | Device Change Data | EndpointObject: | Attribute | Type | Optional | Description | | --------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Device unique Serial Number | | third\_serial\_number | string | Y | The unique serial number of the third-party device. For devices connected through open interfaces, this field is required. | DeviceChangeObject | Name | Type | Optional | Description | | ------ | ------- | -------- | -------------------- | | online | boolean | N | Device Online Status | Example: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": false } } ``` ### 5.4 Gateway Module #### a. Security State Update Event :::tips Module Name：device Version：v2 Message Type：updateDeviceOnline event.data parameters： ::: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------------- | ------------ | ------------------ | | payload | SecurityStateObject | N | Device Information | SecurityStateObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | alarm\_state | string | N | | * `arming` | Armed * `disarming` | Disarmed | Example: ```json // event.data { "payload": { "alarm_state": "alarming" } } ``` ### 5.5 Security Module #### a. Arm State Update Event :::tips Module Name：device Version：v2 Message Type：updateDeviceOnline event.data parameters： ::: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------------- | ------------ | ------------------------- | | payload | ArmStateObject | N | rm and disarm information | ArmStateObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | arm\_state | string | N | | * `arming` | Armed * `disarming` | Disarmed | | detail | DetailObject | N | Arm/disarm details | DetailObject： | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | sid | int | N | 安防模式id | | name | string | N | 安防名称 | Example ```json // event.data { "payload": { "arm_state": "arming", "detail": { "sid": 1, "name": "Home Mode" } } } ``` ## 6. TTS (**Text-to-Speech) Engine Function** ### 6.1 Instruction #### Key Role * TTS Service Provider: The TTS service engine service provider is responsible for registering the TTS engine on the gateway and providing TTS services * Gateway Server：iHost * Gateway Open API Client #### 6.1.1 Registering TTS Engine Service 1. 【TTS Service Provider】Call the interface to register the TTS engine on the gateway. 2. 【Gateway Server】After successful registration, the gateway will store the basic information of the TTS engine (including the service address server\_address, and subsequent communication between the gateway and the TTS Service Provider will be carried out through the server\_address address), and allocate the TTS engine service ID within the gateway.
#### 6.1.2 Get the List of Synthesized Audio 1. 【Gateway Open API Client】Call the interface to obtain the list of registered TTS engine service. You can obtain the current list of registered TTS engines (including the ID of the TTS engine allocated by the gateway). 2. 【Gateway Open API Client】Call the interface to obtain the list of a specified TTS engine audio. The gateway will issue a synchronous audio list instruction to the specified TTS Service Provider and return the result.
#### 6.1.3 Speech Synthesis by Specifying a Speech Engine 1. 【Gateway Open API Client】Call the interface to obtain the list of registered TTS engine service. You can obtain the current list of registered TTS engines (including the ID of the TTS engine allocated by the gateway). 2. 【Gateway Open API Client】Call the interface to obtain the list of a specified TTS engine audio. The gateway will issue a synchronous audio list instruction to the specified TTS Service Provider and return the result.
#### 6.1.4 Synthesize Audio and Play TTS Speech. 1. 【Gateway Open API Client】Call the interface to obtain the list of registered TTS engine service. You can obtain the current list of registered TTS engines (including the ID of the TTS engine allocated by the gateway). 2. 【Gateway Open API Client】Call the interface to obtain the list of a specified TTS engine audio. The gateway will issue a synchronous audio list instruction to the specified TTS Service Provider and return the result. (including the TTS audio file address) 3. 【Gateway Open API Client】Record the TTS audio file address from the result returned in the previous step, call the play audio file interface, and play it through the gateway. ### 6.2 TTS Engine Module #### 6.2.1 Gateway Open Capability **a. Get the list of registered TTS engine services** :::tips * **URL**：`/open-api/V2/rest/tts/engines` * **Method**：`GET` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: none Correct data response: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ---------------- | ------------ | ------------------------------ | | engines | EngineObject \[] | N | List of registered TTS engines | EngineObject Structure | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------------- | | id | string | N | Engine ID assigned by gateway | | name | string | N | Name of TS engine service | :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` **Response Example:**： ::: ```json { "error": 0, "data": { "engines": [ { "id": "engine id", "name": "engine name" } ] }, "message": "success" } ``` **b. Get list of specified TTS engine audio** :::tips * **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list` * **Method**：`GET` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: none Correct data response: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | --------------- | ------------ | --------------- | | audio\_list | AudioObject \[] | N | Audio list | AudioObject Structure | **Attribute** | **Type** | **Optional** | **Description** | | -------------------------------------------------------- | -------- | ------------ | ---------------------------- | | url | string | N | Audio file URL, for example: | | | | | | | label | string | Y | Audio file label | :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` \*\*Error Code: \*\* * 190000 The engine is running abnormally **Response Example:**： ::: ```json { "error": 0, "data": { "audio_list": [ { "url": "tts audio address", // for example: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "tts audio label" } ] }, "message": "success" } ``` **c .Perform speech synthesis using the specified TTS engine** :::tips * **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize` * **Method**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Text used to synthesize the audio | | label | string | Y | Audio file label | | language | string | Y | Transparent field. Optional language code for the synthesis speech request. The specific list of supported language codes is provided by the TTS speech engine service provider. Note that the TTS engine service needs to support default language for speech synthesis, which means that if the language is not passed, the default language of the engine will be used for synthesis. | | options | object | Y | Transparent field. It is used to pass the configuration parameters required for synthesis to the TTS speech engine service. | Correct data response: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------- | ------------ | --------------- | | audio | AudioObject | N | Audio list | AudioObject Structure | **Attribute** | **Type** | **Optional** | **Description** | | -------------------------------------------------------- | -------- | ------------ | ---------------------------- | | url | string | N | Audio file URL, for example: | | | | | | | label | string | Y | Audio file label | :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` \*\*Error Code: \*\* * 190000 The engine is running abnormally **Response Example:**： ::: ```json { "error": 0, "data": { "audio": { "url": "tts audio address" // for example, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "tts audio label" } }, "message": "success" } ``` #### 6.2.2 Communication Between Gateway and TTS Service **a. Registering TTS engine service** > Send request to gateway by TTS Service Provider :::tips * **URL**：`/open-api/V2/rest/thirdparty/event` * **Method**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------- | ------------ | ------------------------------------------ | | event | EventObject | N | Request Event Object structure Information | EventObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------- | | name | string | N | Request name. Optional parameter. | * RegisterTTSEngine | | message\_id | string | N | Request message ID, UUID\_V4 | | version | string | N | Request protocol version number. Currently fixed at 1 | PayloadObject | **Attribute** | **Type** | **Optional** | **Description** | | ---------------- | -------- | ------------ | --------------------------------------- | | service\_address | string | N | Service Address. For example, http\:/// | | name | string | N | Service name | Request Example: ```json { "event": { "header": { "name": "RegisterTTSEngine", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "service_address": "service_address", "name": "tts service name" } } } ``` \*\*Correct response parameters: \*\* | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------------------------- | | name | string | N | Response header name. Optional parameter: | * Response (Successful response) * ErrorResponse (Error response) | | message\_id | string | N | Response header message ID, UUID\_V4. Incoming request message here: header.message\_id | | version | string | N | Request protocol version number. Currently fixed at 1 | PayloadObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------------- | | engine\_id | string | N | Engine ID assigned by gateway | :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` **Response Example:**： ::: Correct Response Example:： ```json { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "engine_id": "engine id" } } ``` \*\*Abnormal response parameters: \*\* | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | type | string | N | Error Type | * INVALID\_PARAMETERS (Parameters error) * AUTH\_FAILURE (Authentication failure) * INTERNAL\_ERROR (Service internal error) | | description | string | N | Error description | Error Response Example:： ```json { "header": { "name": "ErrorResponse", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address cannot be empty" } } ``` **b. Synchronize audio list command** > Send command to the TTS Service Provider by gateway. :::tips * **URL**：`` * **Method**：`POST` * **Header**： * Content-Type: application/json ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | --------------- | ------------ | ---------------------------------------- | | directive | DirectiveObject | N | Instruction object structure information | DirectiveObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------- | | name | string | N | Request name. Optional parameter: | * SyncTTSAudioList | | message\_id | string | N | Request message ID, UUID\_V4 | | version | string | N | Request protocol version number. Currently fixed at 1 | Request Example: ```json { "directive": { "header": { "name": "SyncTTSAudioList", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": {} } } ``` \*\*Correct response parameters: \*\* | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------------------------- | | name | string | N | Response header name. Optional parameter: | * Response (Successful response) * ErrorResponse (Error response) | | message\_id | string | N | Response header message ID, UUID\_V4. Incoming request message here: header.message\_id | | version | string | N | Request protocol version number. Currently fixed at 1 | PayloadObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | --------------- | ------------ | --------------- | | audio\_list | AudioObject \[] | N | TTS Audio list | AudioObject Structure | **Attribute** | **Type** | **Optional** | **Description** | | -------------------------------------------------------- | -------- | ------------ | ---------------------------- | | url | string | N | Audio file URL, for example: | | | | | | | label | string | Y | Audio file label | :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` **Response Example:**： ::: Correct Response Example:： ```json { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "audio_list": [ { "url": "tts audio url", "label": "tts audio label" } ] } } ``` \*\*Abnormal response parameters: \*\* | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | type | string | N | Error Type | * INVALID\_PARAMETERS (Parameters error) * AUTH\_FAILURE (Authentication failure) * INTERNAL\_ERROR (Service internal error) | | description | string | N | Error description | Error Response Example:： ```json { "header": { "name": "ErrorResponse", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address cannot be empty" } } ``` **c. Speech synthesis command** > Send command to the TTS Service Provider by gateway. :::tips * **URL**：`` * **Method**：`POST` * **Header**： * Content-Type: application/json ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | --------------- | ------------ | ---------------------------------------- | | directive | DirectiveObject | N | Instruction object structure information | DirectiveObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------------------------- | | name | string | N | Request name. Optional parameter: | * SynthesizeSpeech | | message\_id | string | N | Request message ID: UUID\_V4 | | version | string | N | Request protocol version number. Currently fixed at 1 | PayloadObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Text used to synthesize the audio | | label | string | Y | Audio file label | | language | string | Y | Transparent field. Optional language code for the synthesis speech request. The specific list of supported language codes is provided by the TTS speech engine service provider. Note that the TTS engine service needs to support default language for speech synthesis, which means that if the language is not passed, the default language of the engine will be used for synthesis. | | options | object | Y | Transparent field. It is used to pass the configuration parameters required for synthesis to the TTS speech engine service. | Request Example: ```json { "directive": { "header": { "name": "SynthesizeSpeech", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "text": "Input text to synthesize.", "label": "tts audio label" } } } ``` \*\*Correct response parameters: \*\* | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | ------------------------------------- | | header | HeaderObject | N | Request header structure information | | payload | PayloadObject | N | Request payload structure information | HeaderObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------------------------------- | | name | string | N | Response header name. Optional parameter: | * Response (Successful response) * ErrorResponse (Error response) | | message\_id | string | N | Response header message ID, UUID\_V4. Incoming request message here: header.message\_id | | version | string | N | Request protocol version number. Currently fixed at 1 | PayloadObject | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ----------- | ------------ | --------------- | | audio | AudioObject | N | TTS Audio | AudioObject Structure | **Attribute** | **Type** | **Optional** | **Description** | | -------------------------------------------------------- | -------- | ------------ | ---------------------------- | | url | string | N | Audio file URL, for example: | | | | | | | label | string | Y | Audio file label | :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` **Response Example:**： ::: Correct Response Example:： ```json { "header": { "name": "Response", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "audio": { "url": "tts audio url", "label": "tts audio label" } } } ``` \*\*Abnormal response parameters: \*\* | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | --------------- | | type | string | N | Error Type | * INVALID\_PARAMETERS (Parameters error) * AUTH\_FAILURE (Authentication failure) * INTERNAL\_ERROR (Service internal error) | | description | string | N | Error description | Error Response Example:： ```json { "header": { "name": "ErrorResponse", "message_id": "Unique identifier, preferably a version 4 UUID", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address cannot be empty" } } ``` ## 7. Multimedia Module ### 7.1 Play Audio File :::tips * **URL**：`/open-api/V2/rest/media/audio-player` * **Method**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------- | | audio\_url | string | N | Audio URL address | Correct data response: :::tips Conditions: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\*`200 OK` **Response Example:**： ::: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 8. Custom UI Card Custom UI cards allow you to display any content you want within the card. This content can be a webpage, an image, or any service with a UI. You just need to provide the URL of the content you wish to display. The UI card will automatically adapt its width and height, and the content will be rendered using an iFrame. ### 8.1 Instruction #### Key Role * **UI Service Provider**: The provider responsible for creating custom UI cards on the gateway. * **Gateway Server**: The gateway server (iHost). * **Gateway Open API Client**: The Open API client for the gateway. #### 8.1.1 Creating a Custom UI Card * **\[UI Service Provider]**: Calls the API to create a custom UI card on the gateway. * **\[Gateway Server]**: Upon successful registration, the gateway stores the basic information of the UI card (including size configuration and card resource URL) and assigns an internal UI card ID within the gateway.
#### 8.1.2 Retrieving the UI Card List * **\[UI Service Provider]**: Calls the API to retrieve the list of UI cards. * **\[Gateway Server]**: Returns the list of UI cards stored on the gateway, including custom UI cards not created by the caller.
#### 8.1.3 Modifying the Configuration of a Specified UI Card * **\[UI Service Provider]**: Calls the API to modify the configuration of a specified UI card, such as the size configuration and resource URL. * **\[Gateway Server]**: Upon successful modification, the gateway stores the updated UI card information, including the new size configuration and resource URL.
#### 8.1.4 Deleting a Custom UI Card 1. **\[UI Service Provider]**: Calls the API to delete a specified custom UI card. 2. **\[Gateway Server]**: The gateway will remove all information related to the specified UI card.
### 8.2 Custom UI Card Module #### 8.2.1 Creating a Custom UI Card > The UI Service Provider sends a request to the gateway to create a custom UI card. :::tips * **URL**：`/open-api/v2/rest/ui/cards` * **Method**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | -------------- | ------------------ | ------------ | -------------------------------------------------------------- | | label | string | Y | Card Label: Used to describe the card. It is the card's alias. | | cast\_settings | CastSettingsObject | Y | Cast Card Settings: Configuration settings for cast cards. | | web\_settings | WebSettingsObject | N | Web Card Settings: Configuration settings for web cards. | CastSettingsObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------------- | ------------ | -------------------------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Size Configuration: Must include at least one configuration. | | default | string | N | Default Specification: The default size specification is used, with optional parameters: 2x2 | WebSettingsObject: | **Attribute** | **Type** | **Optional** | **Description** | | ----------------- | ------------------- | ------------ | ------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Size Configuration: Must include at least one configuration. | | drawer\_component | DrawerObject | Y | Drawer Component Display Settings. | | default | string | N | Default Specification: | * 1x1 * 2x1 | DimensionObject: | **Attribute** | **Type** | **Optional** | **Description** | | --------------------------------------- | -------- | ------------ | ------------------------------------------------ | | src | string | N | Resource URL: For example: | | size | string | N | Size Specifications: | | CastSettingsObject Optional Parameters: | | | | * 2×2 WebSettingsObject Optional Parameters: * 1x1 * 2x1 | DrawerObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------ | | src | string | N | Resource URL: For example: | Successful data response: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ----------------- | | id | string | N | UI Card unique ID | :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. \*\*Status Code: \*\* `200 OK` ::: 请求示例： ```json { "label": "ewelink cube card", "cast_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×2" } ], "default": "2×2" }, "web_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×1" }, { "src": "https://ewelink.cc/ewelink-cube/", "size": "1×1" } ], "drawer_component": { "src": "https://ewelink.cc/ewelink-cube/" }, "default": "2×1" } } ``` Response Example: ```json { "error": 0, "data": { "id": "72cc5a4a-f486-4287-857f-b482d7818b16" }, "message": "success" } ``` #### 8.2.2 Retrieve UI Card List :::tips * **URL**：`/open-api/v2/rest/ui/cards` * **Method**：`GET` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: None Response Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | ------------- | ------------ | --------------- | | data | CardObject\[] | N | UI Card list | CardObjec Object: | **Attribute** | **Type** | **Optional** | **Description** | | -------------- | ------------------ | ------------ | ---------------------------------------------------------------------------------- | | id | string | N | Card ID: A unique identifier for the card. | | label | string | Y | Card Label: Used to describe the card. It serves as an alias or name for the card. | | cast\_settings | CastSettingsObject | Y | Card Label: Used to describe the card. It is the card's alias. | | web\_settings | WebSettingsObject | N | Cast Card Settings: Configuration settings for cast cards. | | app\_name | string | Y | Web Card Settings: Configuration settings for web cards. | CastSettingsObject: | **Attribute** | **Type** | **Optional** | **Description** | | ----------------------- | ------------------- | ------------ | ------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Size Configuration: Must include at least one configuration. | | default | string | N | Default Specification: | | Optional Parameter: 2x2 | | | | | used | string | N | Current Specification: | | Optional Parameter: 2x2 | | | | WebSettingsObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------------- | ------------------- | ------------ | ------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Size Configuration: Must include at least one configuration. | | drawer\_component | DrawerObject | Y | Drawer Component Display Settings. | | default | string | N | Default Specification: | | Optional Parameter: | | | | * 1x1 * 2x1 | | used | string | N | Current Specification: Optional Parameter: * 1x1 * 2x1 | DimensionObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------------- | -------- | ------------ | ------------------------------------------------ | | src | string | N | Resource URL: For example: | | size | string | N | Size Specifications: | | Optional Parameter: | | | | * 1x1 * 2x1 **Note**: Currently, cast cards only support the 2x2 specification. The 2x2 specification will not be effective. | DrawerObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------- | -------- | ------------ | ------------------------------------------------ | | src | string | N | Resource URL: For example: | Response Example: ```json { "error": 0, "data": [ { "id": "72cc5a4a-f486-4287-857f-b482d7818b16", "label": "ewelink cube card", "cast_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×2" } ], "default": "2×2", "used": "2×2" }, "web_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×1" }, { "src": "https://ewelink.cc/ewelink-cube/", "size": "1×1" } ], "drawer_component": { "src": "https://ewelink.cc/ewelink-cube/" }, "default": "2×1", "used": "2×1" }, "appName": "ewelink-cube" } ], "message": "success" } ``` #### 8.2.3 Modify Configuration of a Specified UI Card > Authorized users are allowed to modify the configuration of an existing UI card through this interface. Custom card service providers can only modify UI cards they have created. :::tips * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Method**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: | **Attribute** | **Type** | **Optional** | **Description** | | -------------- | ------------------ | ------------ | -------------------------------------------------- | | label | string | Y | Used to describe the card. It is the card's alias. | | cast\_settings | CastSettingsObject | Y | Cast Card Settings | | web\_settings | WebSettingsObject | Y | Web Card Settings | CastSettingsObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------------- | -------- | --------------------------------------------------------------------------------------------- | ---------------------- | | used | string | Y, Either `used` or `src` must be provided, but at least one of these parameters is required. | Current Specification: | | Optional Parameter: | | | | * 2x2 \| | src | string | Y, Either `used` or `src` must be provided, but at least one of these parameters is required. | Resource URL: | WebSettingsObject: | **Attribute** | **Type** | **Optional** | **Description** | | ------------------- | -------- | --------------------------------------------------------------------------------------------- | ---------------------- | | used | string | Y, Either `used` or `src` must be provided, but at least one of these parameters is required. | Current Specification: | | Optional Parameter: | | | | * 1x1 * 2x1 | | src | string | Y, Either `used` or `src` must be provided, but at least one of these parameters is required. | Resource URL: | Successful data response: :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. The UI card being modified must be created by the custom UI card service provider calling the interface. \*\*Status Code: \*\* `200 OK` **Error Code:** * **406**: No permission to access this resource ::: \*\*Response Example: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Request Example: \*\* ```json { "cast_settings": { "used": "2×2" }, "web_settings": { "used": "1×1" } } ``` #### 8.2.4 Delete Custom UI Card > Authorized users are permitted to delete an existing UI card using this interface. Custom card service providers can only delete UI cards that they have created. :::tips * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Method**：`DELETE` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Request Parameters: None Successful data response: :::tips **Conditions**: The request parameters are legal, and the user identity verification is passed. The UI card being modified must be created by the custom UI card service provider calling the interface. \*\*Status Code: \*\* `200 OK` **Error Code:** * **406**: No permission to access this resource. ::: \*\*Response Example: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` # Language Languages are ordered A–Z * [**Brazilian Portuguese - Português (Brasil)**](/english-pt-br/dongles-zigbee/desbloqueie-o-zigbee-com-dongle) * [**Chinese - 简体中文**](/english-zh/zigbee-dongle/shi-yong-dongle-jie-suo-zigbee) * [**English - English**](/zigbee-dongles/unlock-zigbee-with-dongle) * [**French - Français**](/cube-os-fr/cles-zigbee/debloquez-zigbee-avec-un-dongle) * [**German - Deutsch**](/german/zigbee-dongles/zigbee-mit-dongle-freischalten) * [**Italian - Italiano**](/english-it/dongle-zigbee/sblocca-zigbee-con-dongle) * [**Polish - Polski**](/english-pl/dongle-zigbee/odblokuj-zigbee-za-pomoca-dongla) * [**Portuguese - Português**](/english-pt/dongles-zigbee/desbloquear-zigbee-com-dongle) * [**Russian - Русский**](/cube-os-ru/dongly-zigbee/otkroite-zigbee-s-pomoshyu-dongla) * [**Spanish - Español**](/cube-os-es/dongles-zigbee/desbloquea-zigbee-con-un-dongle) * [**Thai - ไทย**](/english-th/zigbee/zigbee) # Unlock Zigbee with Dongle Expand compatibility. Bridge into Matter. Build a smarter, more open smart home - all without coding. ## Unlock Zigbee Power in eWeLink CUBE with One Dongle {% embed url="" %} A quick introduction to how the Dongle works with CUBE OS to bring Zigbee devices into your smart home. {% endembed %} ### What Does the Dongle Enable in CUBE OS？ With the Dongle, CUBE OS becomes a powerful local Zigbee hub, letting you pair lights, switches, plugs, and sensors with ease, bridge them into Apple Home, Google Home, Alexa, or SmartThings through the Matter Bridge, and enjoy a unified smart home experience without coding, without YAML, and with fully local, privacy-friendly control.
### Add Zigbee Devices & Check Compatibility Follow our step-by-step guide to start pairing your Zigbee devices in minutes: 👉 [**How to Add Zigbee Devices in CUBE OS**](/getting-started/add-devices/zigbee-devices)\ 👉 [**Zigbee Device Compatibility List**](/compatibility-check/zigbee) ### Dongle Series: Co-Developed with SONOFF Choose the right Dongle for your setup.\ Together with the SONOFF team, we offer five Dongle models designed for different Zigbee network sizes and performance needs:
Cover image
Dongle-LMG21/files/qKCQhDyOctjJnZ6OOeZwhttps://sonoff.tech/products/sonoff-dongle-lite-mg21-zigbee-thread-usb-dongle-dongle-lmg21/58
Dongle-PMG24/files/GwqUNheHGOkE2DKyOhDIhttps://sonoff.tech/products/sonoff-zigbee-thread-usb-dongle-dongle-plus-mg24/58
Dongle-MAX/files/WznBZGTJkZTS7XOTZckdhttps://sonoff.tech/products/sonoff-dongle-max-zigbee-thread-poe-dongle-dongle-m/58
ZBDongle-E/files/EviSXp5KMalye3fpMH4Phttps://sonoff.tech/en-us/products/sonoff-zigbee-3-0-usb-dongle-plus-zbdongle-e/58
ZBDongle-P/files/Sj6YxBuSOKPe5wyA7uGhhttps://sonoff.tech/en-us/products/sonoff-zigbee-3-0-usb-dongle-plus-zbdongle-p/58
### Ready to Get Started? Install CUBE OS, plug in your Dongle, and begin building a smarter, more open Zigbee + Matter smart home!
Cover image
Installation/pages/CyH2xJQs9yWJ1S8BYNav/files/XutfQroodcVdnX12ZY3R
Add Devices/pages/kkSyp1QxGf9lG0OXdHWh/files/ZbMhzEExWJPYsCLVEUu8
# FAQ - You Ask, We Answer We see many interesting questions coming from our users in the past months since CUBE OS v0.4 beta released - on Facebook, Discord, and different community groups. Some of you ask about hardware, some about compatibility, and others about the difference between CUBE OS and iHost. Instead of answering them one by one, we thought: why not make it easier for everyone? That’s why we are starting **“You Ask, We Answer”**. Every two weeks, we will collect the most common questions from the community and share clear answers here. Our goal is simple: help more users understand CUBE OS without digging through endless documents or forum threads.
# Episode 1 ## **What we cover in this post** In this first episode, we talk about: 1. **The relationship between CUBE OS, eWeLink Cloud, and iHost + how remote access works** 2. **How old devices (wifi & zigbee) can get a second life with CUBE OS** 3. **What hardware you can use to run CUBE OS (Raspberry Pi, NAS, Virtual Machines, etc.)** *** ### Q1: Does CUBE OS replace the official eWeLink Cloud? **User asked:** * Does this replace the official eWeLink server? * How do devices connect to the self-hosted server instead of the official server? * How does CUBE OS coexist with eWeLink Cloud? * What is the difference between CUBE and iHost? **Answer:**\ CUBE OS is **not a replacement**, but an **extra choice**. * **Work with cloud or not, up to you**: You can still use eWeLink Cloud as usual, and at the same time run CUBE OS locally, or go fully local by setting up CUBE OS. This gives you a smoother and more private control experience. Many WiFi devices can be managed directly in CUBE OS, so they are no longer affected by internet connection issues. * **Remote access**: CUBE OS has a **built-in secure remote access mechanism**. You can turn it on when needed, and the system will generate a **private access link** for you. With this link, you can safely reach your CUBE OS from anywhere. Of course, you can also use the Tailscale Addon to enable remote access. * **Difference from iHost**: iHost is a hardware device that already includes CUBE OS. But CUBE OS itself can also run on Raspberry Pi, NAS, or even in a virtual machine. That means you don’t need to buy extra dedicated hardware. *** ### Q2: What about old eWeLink and SONOFF devices? **User asked:** * How about old eWeLink devices and SONOFF? **Answer:**\ This is one of the highlights of CUBE OS. * Many **older WiFi devices** can get a second life. Thanks to the built-in **Matter Bridge**, they can now work with **Apple Home, Amazon Alexa, Google Home, and Samsung SmartThings**. * This new Matter Bridge connection does **not rely on cloud-to-cloud linking** anymore, and it is completely **free**. * For **Zigbee devices**, you can connect them to CUBE OS using a suitable Zigbee dongle. * With **ZigBee2CUBE**, many popular Zigbee devices from other brands can also be added into your CUBE OS system. * SONOFF is also launching **new dongles based on Silicon Labs MG24 chips**, which will support **Thread devices**. Please check [SONOFF official website](https://sonoff.tech/58) for more. *** ### Q3: What hardware can I use to run CUBE OS? **User asked:** * Synology? * What Pi is recommended? * Can CUBE OS run on Raspberry Pi 3B? * Does it have an Android app? * What Zigbee/Matter receiver is used? **Answer:** * **Where to run**: CUBE OS can run on Raspberry Pi, Synology NAS, Ugreen NAS, and also on **virtual machines** such as VirtualBox or VMware. * **Recommended Pi model**: We recommend Raspberry Pi 4B (2GB/4GB RAM). We have **not tested** Raspberry Pi 3B. * **How to control**: CUBE OS has a **built-in Web Portal**. You can open it in your browser at `cube.local` or your device IP. For remote access, use the private link generated by the system.\ CUBE also has the **CAST Dashboard** – a clean interface for daily control, with controls and settings separated to avoid mistakes. * **Zigbee & Matter support**: SONOFF already offers several Zigbee dongles. They can act as Zigbee/Matter receivers, and more options are coming. * **For Synology users**: We have prepared a step-by-step **guide for Synology installation**, available in our documentation. *** ## **In summary** CUBE OS is not about replacing, but about giving you **more choice**: * Run it locally and enjoy full privacy and control * Bring old devices back to life with Matter support for major platforms * Deploy flexibly on Raspberry Pi, NAS, or virtual machines - no extra hardware needed * Expand your system with more Zigbee and future Thread devices This is only the first episode of **“You Ask, We Answer”**. We will keep collecting your questions and share more answers every two weeks. Stay tuned! # Episode 2 ## **What we cover in this post** This time, we’re focusing on two hot topics: * **Where and how you can install CUBE OS** * **What’s coming for Zigbee, Matter, Thread, and beyond** Our goal is still the same: help you understand and get the most out of CUBE OS without digging through endless documents and shape its future together with your feedback. *** ### Q1: What installation methods does CUBE OS support during the public beta phase? **User asked:** Is it possible to flash CUBE OS into an Android TV box with 2 GB RAM?\ Can I install it on my old Mini PC without a VM?\ Does it work on Proxmox / Hyper-V?\ My Raspberry Pi 5 isn’t booting. Can it run on Pi 3B? **Answer:** For a smooth experience, we recommend at least **2 GB of RAM** when running CUBE OS. We haven’t officially tested setups with less than 2 GB, it may still work if get lucky, but performance and stability can’t be guaranteed. * **Virtual machines(Proxmox / Hyper-V): Our current test release is mainly provided as x86 VM images (VDI/VMDK). These run directly on VirtualBox or VMware.** We have had users successfully run CUBE OS on Proxmox/Hyper-V, but we have not officially tested it at this stage. It should be possible, but it can only run as a virtual machine and does not currently support LXC mode or bare-metal installation. * **Mini PC / Android TV box:** We don’t yet offer a bare-metal ISO image for direct installation. For now, you can use the provided x86 image and run CUBE OS on virtual machine. If more users request it, we’ll consider a native installer in future releases. * **Raspberry Pi:** We officially recommend Pi 4B (2 GB/4 GB RAM) for the smoothest experience. **Pi 5 is now supported in our latest builds** . **Please make sure that the bootloader of the Raspberry Pi you are using is the latest version** . You can follow the official tutorial from Raspberry Pi Documentation to [**update the bootloader**](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#bootloader_update_stable). In addition, Pi 3B is not optimized yet and may not run reliably. **In short:**\ Right now, CUBE OS is easiest to deploy on **Pi 4B / Pi 5** , NAS and virtual machine. More installation options will come as the project grows. *** ### Q2: Zigbee, Matter, Thread… what’s supported today and what’s next? **User asked:** Will CUBE OS be able to run both Zigbee and OpenThread at the same time?\ Will CUBE OS support Matter over Thread?\ Can I export energy data via Matter like I can in Home Assistant?\ Zigbee devices seem less stable than Wi-Fi - will Thread improve this? **Answer:**\ Today, CUBE OS already includes a built-in **Matter Bridge** : * You can bring many of your **old Wi-Fi devices** into Apple Home, Alexa, Google Home, and SmartThings - without relying on cloud-to-cloud linking. * With a suitable Zigbee dongle, you can also manage a wide range of Zigbee devices directly in CUBE OS. **What’s coming:** * **OpenThread:** Support is in our plans, but not in the current test version. Once CUBE OS firmware integrates Thread (via OpenThread), you’ll be able to use Matter over Thread with a multi-protocol Zigbee/Thread dongle. * **Energy data via Matter:** The Matter standard already defines clusters for energy monitoring, laying the foundation for future integration. While energy data is not yet synchronized over Matter in the current version of CUBE OS, this is an evaluation worth featuring. We’re actively exploring implementation paths and assessing both technical feasibility and user demand to determine the best time and approach to introduce energy data support via Matter. And if you guys have any suggestion or idea, or just have check that one of the big giants, like Apple or other one have onboard this feature via Matter, please let us know. *** ### **Q3: Why isn’t Zigbee support as flexible as Home Assistant?** **User asked (summary) :**\ “CUBE OS seems limited in Zigbee options. Home Assistant offers Zigbee2MQTT, ZHA, and wider device support. Why not make Zigbee more open and flexible, like adding custom scripts or alternatives?” **Answer:** Home Assistant is a great platform that gives developers and DIY enthusiasts a lot of options - but even HA can’t fully support every Zigbee device, especially those with complex capabilities or proprietary attributes. With **CUBE OS** , our starting point is a bit different: * Our goal is to provide average users with an out-of-the-box experience: guided UI, built-in dashboards, and a straightforward setup - making **local smart homes simpler, beginner-friendly and paired with a well-designed UI.** * For Zigbee compatibility, our Zigbee2CUBE framework dynamically maps device-reported capabilities to the mechanism and to gathering proper front-end UI, which makes it more flexible and significantly improves device support. * We’re confident the experience will keep getting smoother and we’re continuously enhancing Zigbee compatibility. If you have a specific device brand, model, or capability you’d like to see supported, please let us know - your input helps us evaluate and plan future integrations. *** ### Q4: Is CUBE OS only for Sonoff devices? **User asked:**\ CUBE OS is only for Sonoff devices, right? **Answer:** CUBE OS is designed to go far beyond just Sonoff devices: • **For Zigbee devices:** Through our Zigbee2CUBE framework, you can already connect and manage thousands of Zigbee devices from different brands, all unified in CUBE OS. • **For Wi-Fi devices:** At the moment, CUBE OS supports eWeLink-compatible Wi-Fi devices, including SONOFF’s. We’re continuously expanding to support more Wi-Fi brands. For example, **our partner Yeelight** has already released an official add-on to bring Yeelight Wi-Fi devices into CUBE OS. We also welcome any Brand or developer to help enhance this area of support. • **For Thread devices** : As mentioned before, support for Thread-based devices is on the way. In short, CUBE OS is built on open standards like Matter and Zigbee, and we’re steadily widening the ecosystem to integrate a broad range of products. *** ## In summary Episode 2 shows how CUBE OS keeps evolving: * More ways to run it on the hardware you already have * Built-in Matter Bridge to extend your devices to major platforms * Plans for OpenThread and other advanced features * Local-first, privacy-friendly, and simpler to set up than traditional DIY stacks Keep sending us your questions, and we’ll keep answering them every two weeks in **“You Ask, We Answer.”** # Add Your Devices into Apple Home ## Overview With **CUBE OS** and its built-in **Matter Bridge**, you can now bring your eWeLink LAN devices, Zigbee devices, and more into **Apple Home**. This gives many older WiFi devices a second life - they can now join ecosystems like **Apple Home** without relying on the eWeLink cloud, and be controlled through Apple Home, Siri, HomePod, Apple Watch, and other Apple ecosystem entry points. We’ve created this thread as a **master post** to guide you through the setup process and share device-specific experiences. Over time, we’ll keep updating this post with links to individual device tests so you can easily check compatibility and Apple Home features.
*** ## Step {% stepper %} {% step %} ### Add Devices into CUBE OS * Install eWeLink CUBE OS on your preferred host, check these [Installation guides.](/getting-started/quickstart) * **Zigbee Devices:** Plug your **Zigbee Dongle** into a USB port and pair Zigbee devices in CUBE OS. * **WiFi Devices:** Install the **eWeLink Smart Home Add-on** from the Docker tab in CUBE OS. * Log in with your eWeLink account and sync your LAN devices. * You’ll see the synced devices appear in CUBE OS and can assign rooms or rename them. {% endstep %} {% step %} ### Enable Matter Bridge * In the CUBE OS web UI, click the **Matter** logo on the sidebar. * Enable the feature → a **QR code** and **setup code** will appear. {% endstep %} {% step %} ### Pair with Apple Home * Open the **Camera app** on your iPhone/iPad and scan the QR code. * Tap **“Open in Home”** and follow the prompts. * Once added, you can rename devices and assign them to rooms. {% endstep %} {% step %} ### Control with Siri Once devices are added, you can try commands like: * *“Hey Siri, turn on the living room light.”* * *“Hey Siri, switch off the TX in bedroom.”* {% endstep %} {% endstepper %} *** ## Device Experiences Here’s a summary of how different devices behave in Apple Home through the CUBE OS Matter Bridge. This table will be updated continuously with new device tests.
Device TypeLink to PostExample ModelRename DeviceOn/Off ControlDimming / BrightnessColor Temp / Color ControlRoom AssignmentAutomation (Trigger/Action)Siri ControlNotes
SwitchRead moreSONOFF TX✔️✔️--✔️Both Trigger&Action✔️Switches in Apple Home support multi-channel splitting and “Display As” options, which affect how the device is shown and controlled by Siri.
LightWatch videoSONOFF B05-BL✔️✔️✔️✔️✔️Both Trigger&Action✔️Supports dimming and color control
PlugRead moreSONOFF S40✔️✔️--✔️Both Trigger&Action✔️
SensorComing soonSNZB-02✔️---✔️Only as Trigger-Can trigger automations
*** ## Next Steps * We’ll keep adding more device experiences (plugs, lights, sensors, gateways, etc.). * Feel free to share your own tests in the comments. Your feedback will help improve the Matter Bridge and guide compatibility work. # Switch - SONOFF TX One of the most exciting features in **CUBE OS** is the **Matter Bridge**.\ This gives many older WiFi devices a second life. They can now join ecosystems like **Apple Home** without relying on the eWeLink cloud and be controlled through Apple Home, Siri, HomePod, Apple Watch, and other Apple ecosystem entry points. In this post, I’ll share my hands-on experience: bringing my old **SONOFF TX wall switch** back to life, connecting it to the Apple ecosystem via CUBE OS.
## Steps {% stepper %} {% step %} Pick up an old TX wall switch I had lying around, wired it to a ceiling light, and got ready to see how well this experience works. [![IMG\_2218](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/optimized/2X/6/6e9e9397b053576eb006192454fd197cb3188a88_2_333x250.jpeg)](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/original/2X/6/6e9e9397b053576eb006192454fd197cb3188a88.jpeg) {% endstep %} {% step %} On my Ugreen NAS, I installed **CUBE OS** inside a virtual machine and got it running smoothly.\ Installation tutorials can be found in the [Installation & User Guide.](/getting-started/quickstart) [![IMG\_2220](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/optimized/2X/f/f52c37571015509e4feefbd732043d29acfdef2c_2_187x250.jpeg)](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/original/2X/f/f52c37571015509e4feefbd732043d29acfdef2c.jpeg) {% endstep %} {% step %} Once CUBE OS was up and running, I access to the interface via `cube.local` (or the IP of the CUBE).\ From the sidebar, I clicked on the **Docker (whale icon)**, installed the **eWeLink Smart Home Addon**, logged in with my eWeLink ID, and synced my WiFi devices into CUBE OS.\ This step pulls the control keys from the cloud - after that, you can say goodbye to eWeLink Cloud. [![image](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/original/2X/a/a188db46379d41bf306e3f1db82b2d1eb19af9ff.png)](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/original/2X/a/a188db46379d41bf306e3f1db82b2d1eb19af9ff.png) {% endstep %} {% step %} Next, from the CUBE OS sidebar, I clicked the **Matter** icon. Following the UI guide, I generated a pairing code, then scanned it with my iPhone in the **Apple Home** app.\ It felt exactly the same as adding a HomeKit device - no extra steps.\ If you see a prompt like *“Adding an uncertified device”*, just continue. (CUBE OS is currently under CSA certification.) [![image](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/optimized/2X/1/1b01e7f3e7ceb8362c4d742bc7e963161316aa15_2_517x151.png)](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/original/2X/1/1b01e7f3e7ceb8362c4d742bc7e963161316aa15.png) {% endstep %} {% step %} I customized the device name and assigned it to a room - the same steps as with any HomeKit device. [![IMG\_E0000C871DD3-1](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/optimized/2X/4/469395c49b845ebc6f857ad58fca773eabacac77_2_172x375.jpeg)](https://europe1.discourse-cdn.com/flex005/uploads/ewelinkforum/original/2X/4/469395c49b845ebc6f857ad58fca773eabacac77.jpeg) {% endstep %} {% step %} Now for the fun part - controlling my TX switch through Apple Home and Siri on different devices: * iPhone Apple Home * iPhone Siri * iPad Apple Home * iPad Siri * HomePod mini Siri * Apple Watch Apple Home * Apple Watch Siri {% endstep %} {% endstepper %} ## **Thought** The whole process was easy. The most “complex” part was installing CUBE OS on my NAS, but even that was straightforward with the tutorial. Once CUBE OS was running, everything else was just following the UI. My old **TX wall switch** now feels brand new, fully working inside the Apple ecosystem. Highly recommend everyone try CUBE OS to bring a second life to your older WiFi devices! # Light - SONOFF B05-BL Watch this video: {% embed url="" %} # Plug - SONOFF S40 Earlier in the community, we explored how to add the [**SONOFF TX Switch**](/blog/add-your-devices-into-apple-home/switch-sonoff-tx) to Apple Home through the **CUBE OS Matter Bridge**, showing how switch-type devices work seamlessly with Apple's ecosystem. This time, let's see how it performs with a **plug-type device** - the [**SONOFF Wi-Fi Smart Plug S40**](https://sonoff.tech/en-us/products/sonoff-iplug-series-wi-fi-smart-plug-s40-s40-lite/58) - to check how well it works inside Apple Home.
## What I Used * **Device:** SONOFF S40 Wi-Fi Smart Plug * **Appliance:** A simple plug-in fan * **Platform:** CUBE OS with Smart Home Add-on + Matter Bridge
## Setup Steps {% stepper %} {% step %} Power up your **S40 plug** and connect it to your **eWeLink account** as usual. {% endstep %} {% step %} Open **CUBE OS**, go to the **eWeLink Smart Home Add-on**, and sync your S40 device. {% endstep %} {% step %} Enable the **Matter Bridge** in CUBE OS and add the bridge to **Apple Home** following the steps in our [Getting Started guide](/blog/add-your-devices-into-apple-home). {% endstep %} {% step %} Once paired, your S40 plug will instantly appear in the Apple Home app - ready to control your fan or other appliances.
{% endstep %} {% endstepper %} ## Apple Home Experience Control works smoothly across all Apple platforms I tested:
DeviceTested Feature
📱 iPhoneApple Home app + Siri voice control
💻 iPadApple Home app + Siri
🏠 HomePod miniVoice control via Siri
⌚ Apple WatchApple Home app + Siri command
Response time is fast, and the state updates are almost instant. Turning the fan on and off feels natural and reliable through Apple's interface. ## Summary The SONOFF S40 works perfectly through the **CUBE OS Matter Bridge**, just like the TX switch - stable connection, low latency, and full Apple ecosystem support. If you have other plug-type or energy monitoring devices, give them a try and share your results below. It's exciting to see how many older Wi-Fi devices can get a second life inside Apple Home with CUBE OS. \ \ ---------------------------------- # Sensor - SNZB Sensors You've probably already seen how we've connected **switches, plugs, and lights** like the **SONOFF TX**, **S40**, and **B05-BL** to Apple Home through the **CUBE OS Matter Bridge** - all working smoothly and locally across Apple's ecosystem.
Now, it's time to explore how **sensor-type Zigbee devices** perform in Apple Home when bridged through CUBE OS.\ In this post, we'll walk through a hands-on test featuring the following SONOFF Zigbee sensors: | Device | Type | Function | | ------------------------------------------------------------------------------------------------------------ | ----------------------------- | --------------------------- | | [**SNZB-02P**](https://sonoff.tech/en-us/products/sonoff-zigbee-temperature-and-humidity-sensor-snzb-02p/58) | Temperature & Humidity Sensor | Measures ambient conditions | | [**SNZB-03P**](https://sonoff.tech/en-us/products/sonoff-zigbee-motion-sensor-snzb-03p/58) | Motion Sensor | Detects movement | | [**SNZB-04P**](https://sonoff.tech/en-us/products/sonoff-zigbee-door-window-sensor-snzb-04p/58) | Door/Window Sensor | Detects open/close status | | [**SNZB-05P**](https://sonoff.tech/en-us/products/sonoff-zigbee-water-leak-sensor-snzb-05p/58) | Water Leak Sensor | Detects moisture presence | | [**SNZB-06P**](https://sonoff.tech/en-us/products/sonoff-zigbee-human-presence-sensor-snzb-06p/58) | Human Presence Sensor | Detects occupancy | **Check the compatibility of Zigbee Sub-devices on your hand：** [cube-web.ewelink.cc](https://cube-web.ewelink.cc) ## **Setup Steps** Just follow the same steps as in the Getting Started guide:\ Power up your sensors → pair them to **CUBE OS** via a **Zigbee Dongle** → enable the **Matter Bridge** → scan the QR code to add everything into **Apple Home**.
All paired sensors will appear automatically under their respective categories. ## **Apple Home Experience** Here's how each sensor type behaves inside Apple Home via CUBE OS Matter Bridge: | Sensor | Display in Apple Home | Automation Support | Notes | | ------------------------------ | ------------------------------ | ------------------ | -------------------------------------------- | | **SNZB-02P (Temp & Humidity)** | Temperature shown in real-time | ✅ Yes | Humidity value display may vary | | **SNZB-03P (Motion Sensor)** | Detects motion events | ✅ Yes | May show as basic occupancy status currently | | **SNZB-04P (Door/Window)** | Shows open/close status | ✅ Yes | Excellent trigger performance | | **SNZB-05P (Water Leak)** | Displays “Wet/Dry” status | ✅ Yes | Instant alert on leak detection | | **SNZB-06P (Presence Sensor)** | Detects occupancy state | ✅ Yes | May show as basic occupancy status currently | ## **Automation Example** Let's create a simple automation to see it in action: When the **SNZB-04P Door Sensor** detects the door opening → turn on the **B05-BL smart bulb** instantly.
The automation setup in Apple Home is straightforward, and the response is nearly instant.\ It feels just like using native HomeKit accessories - all **local, fast, and reliable**.
*** ## **Summary: Sensor Experience in Apple Home** | **Tested On** | **Result** | | ------------- | ------------------------------------------------- | | iPhone / iPad | ✅ Displayed & responsive | | Apple Watch | ✅ Displayed & trigger available | | HomePod mini | ✅ Recognizes sensor triggers via Siri automations | Overall, these SONOFF Zigbee sensors perform **surprisingly well** in Apple Home through the CUBE OS Matter Bridge - stable connection, minimal delay, and seamless integration with Apple's automation system. 💡 **If you're already running CUBE OS**, try adding your Zigbee sensors and see how they bring your smart home automations to life in Apple Home - no cloud, no YAML, just local control made simple. # Add ONVIF Compatible Cameras Tried It: Adding ONVIF Compatible Cameras to CUBE OS CUBE OS now supports discovering and adding **any ONVIF compatible camera**, giving you a unified and local-first way to monitor multiple video streams, control supported features, and trigger smart home automations without relying on the cloud.
### Why ONVIF protocol Support in CUBE OS? With ONVIF integration, CUBE OS becomes your centralized monitoring hub, offering a simple and private way to integrate cameras from different brands into your home system. No extra coding or complicated setup is required - just discover your camera, and you're ready to experience **vision-based automation**. CUBE OS handles everything **locally**, keeping your video data private and secure while allowing cameras to interact directly with your smart home devices. **💡 In short: One dashboard, local data, and beginner-friendly visual smart home automation.** ### Feature Overview Here's what you can do with ONVIF compatible cameras in CUBE OS today: * 🎥 **Discovering and view cameras** directly from your local network * 🖥️ **Multi-channel live view** - monitor 10 cameras at once in the dashboard * 🎛️ **PTZ (Pan-Tilt-Zoom) control** for ONVIF-compatible cameras * ⚡ **Motion detection triggers** - use camera motion as automation conditions * 🔒 **Local-first operation** - no cloud streaming, your data stays in your network ### ONVIF Compatibility CUBE OS works with most **ONVIF-compliant cameras** across major brands.\ You can check whether your camera supports ONVIF from the official compatibility list below: 👉 [ONVIF Conformant Product List](https://www.onvif.org/conformant-products/) SONOFF cameras with ONVIF support can also take advantage of PTZ control directly in CUBE OS. ### Master ONVIF Compatible Cameras on eWeLink CUBE OS: Tutorial Series We are launching a dedicated tutorial series to help you get the most out of ONVIF compatible cameras on eWeLink CUBE OS.\ From setup to advanced automations, you will learn step by step how to connect, view, and integrate your cameras into your local smart home system. 1️⃣ [How to Connect Your ONVIF Compatible Cameras to eWeLink CUBE OS — setup and compatibility](/blog/add-onvif-compatible-cameras/how-to-connect-your-onvif-compatible-cameras-to-ewelink-cube-os) #### Coming up next: 2️⃣ Watch Multiple ONVIF Compatible Camera Feeds on the CUBE OS Dashboard — multi-view control\ 3️⃣ Use Camera Motion to Trigger Automations in CUBE OS — smart automation in action\ 4️⃣ Integrate ONVIF Compatible cameras with Matter Devices via CUBE OS — advanced integration We will keep updating this post with links as each tutorial goes live — stay tuned and follow the thread to explore the full series! #### Download the Latest Image on {% embed url="" %} ### Join the Community Have you tried connecting your own camera yet?\ Share your camera brand, setup experience, and performance in the comments below - your feedback will help us improve compatibility and inspire others to try it out. 👉 Let's see how far ONVIF and CUBE OS can take smart home intelligence - one camera at a time. # How to Connect Your ONVIF Compatible Cameras to eWeLink CUBE OS Setup and Compatibility CUBE OS supports discovering and adding **any ONVIF compatible camera**, making it easy to build a unified, local, and privacy-first monitoring setup for your smart home.\ This guide walks you through how to connect your ONVIF compatible cameras to eWeLink CUBE OS and get them streaming in minutes.
*** ### **1. Before You Start** To ensure a smooth setup, make sure the following requirements are met before adding an ONVIF compatible camera to CUBE OS: ✔ **Your camera's ONVIF feature is enabled**\ Open your camera's configuration page (usually via its IP address) and ensure that **ONVIF support is turned on**. ✔ **Your ONVIF compatible camera is connected to your home network**\ Either via Wi-Fi or Ethernet, depending on the device. ✔ **Your camera and CUBE OS are on the same LAN / VLAN / subnet**\ This ensures successful discovery during the setup process. ✔ **You have the camera's login credentials ready**\ CUBE OS will require these to authenticate access to the video stream and ONVIF services. Once all of the above are prepared, you're ready to add your camera into CUBE OS. ### **2. Add ONVIF Compatible Cameras in CUBE OS** CUBE OS makes the process simple with auto-discovery via ONVIF. {% stepper %} {% step %} **Open the CUBE OS Web Console** Visit the CUBE OS web UI from your browser. {% endstep %} {% step %} **Add a Camera Device** Click **Add Device** and then click **Start Setup.** CUBE OS will immediately scan your local network for ONVIF compatible cameras.
{% endstep %} {% step %} **Select Your Camera** When your camera appears in the discovery list: * Click it * Enter the authentication credentials
{% endstep %} {% step %} **Finish & Preview** Once added, go back to **All Devices**. Click your camera, and view the real-time video stream instantly. You should now see your ONVIF-compatible camera live inside CUBE OS.
{% endstep %} {% endstepper %} ### **3. Supported Features** ONVIF compatible cameras added to CUBE OS support: 🎥 Real-time live streaming 🔎 Auto-discovery on LAN 🕹 PTZ control (when supported by the camera) 🚨 Motion event detection ⚡ Local processing with no cloud dependency 🤖 Camera driven automations (covered in a later tutorial) This means your ONVIF camera becomes a fully functional component of your smart home. ### **4. Camera Compatibility** CUBE OS works with most ONVIF compatible cameras from various brands.\ You can verify whether your model is ONVIF compliant here: 👉 **ONVIF Conformant Product List**\ ### **5. Summary** Connecting an ONVIF compatible camera to CUBE OS is straightforward -\ auto-discovery, simple credential input, and instant live streaming. Your camera now runs locally, integrates cleanly, and becomes the foundation for more advanced camera driven smart home automations. # Q\&A for Preview Versions **Q: Why won't CubeOS find my Zigbee dongles?** A: As we can not include and maintain all the models in our compatibility list, only tested dongles will work with auto-discovery. If your CubeOS won't find it, please configure it manually. **Q: Are Built-in Matter components certified?** A: CubeOS is still in the developer preview stage, and is yet to obtain certification. **Q: Why do issues remain unfixed in new versions?** A: Due to the routine of the development team, some versions like V0.2 will focus on new features. Some identified bugs will be fixed in future versions. Additionally, certain bugs may not restore and require more efforts to navigate. **Q: When will CubeOS support xxx platforms?** A: As we don't have infinite developing resources, only popular installation methods are supported and verified. Alternative methods like Proxmax VE may work but are not recommended. # Feedback We value every piece of feedback that helps improve CUBE OS. Whether you’re sharing ideas, reporting issues, or starting discussions, our community is the best place to connect. ## **1. General Discussion & Technical Support** For all conversations, including general discussions, feature suggestions, troubleshooting, or sharing your experience. Please visit our official community forum: [**eWeLink Community Forum**](https://forum.ewelink.cc/c/ewelink-cube/23) You can browse topics, ask questions, get help from other users, and join ongoing discussions about CUBE OS and the broader smart home ecosystem. *** ## **2. Business & Collaboration** If you have business-related inquiries, partnership intentions, or potential collaboration opportunities, please contact us via email: *** ## **3. Translation Volunteers** If you’re interested in contributing translations for CUBE OS or helping improve our multilingual documentation, we warmly welcome community volunteers. *** ## **4. Feedback Survey** We’d love to hear how your experience has been so far. Whether it’s installation, device integration, or using Matter with third-party platforms, your feedback helps us improve CUBE OS for everyone. > 📝 **Take our 3-minute survey (choose your language):** > > * English (English)\ > > * Russian (Русский)\ > > * French (Français)\ > > * German (Deutsch)\ > > * Italian (Italiano)\ > > * Spanish (Español – España)\ > > * Portuguese (Português – Portugal)\ > > * Portuguese (Português – Brasil)\ > > * Polish (Polski)\ > ## **Thank You** Your participation keeps the CUBE OS community growing and evolving.\ Every suggestion, bug report, and shared idea helps us build a better open ecosystem for everyone. # Follow Us Stay connected with the latest updates, feature releases, tutorials, and community stories from the eWeLink and CUBE OS ecosystem. Follow us on our official channels to keep up with everything new. ## **Facebook - eWeLink Community**
Join our official Facebook community to get announcements, feature highlights, tips, and user stories. *** ## **YouTube - CUBE OS Video Playlist**
Explore tutorials, product walk-throughs, and quick-start videos to learn more about CUBE OS.