repository·master·Indexed 24 days ago
https://github.com/dresden-elektronik/deconz-rest-pluginA REST-API plugin for managing and controlling Zigbee 3.0, ZHA, and ZLL devices from manufacturers such as Xiaomi Aqara, IKEA TRÅDFRI, Philips Hue, innr, and Samsung. Requires compatible hardware like RaspBee or ConBee USB dongles. Documentation covers installation, headless configuration on Linux, build instructions for Linux (Qt5/Qt6), Windows (MSYS2), and macOS, as well as device-specific troubleshooting for IKEA, Lutron, Terncy, and Xiaomi hardware.
The deCONZ REST plugin provides a REST-API to control Zigbee 3.0 (Z30), Zigbee Home Automation (ZHA), and Zigbee Light Link (ZLL) devices. It supports various vendors including Xiaomi Aqara, IKEA TRÅDFRI, Philips Hue, innr, and Samsung.
To use the plugin, you must have compatible Zigbee hardware such as a RaspBee/RaspBee II shield for Raspberry Pi or a ConBee/ConBee II/ConBee III USB dongle.
Use CMake to build the plugin on older Debian versions using Qt5.
Install the following dependencies via apt-get.
Note: On newer Ubuntu versions, qt5-default is unavailable; use qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools instead.
apt-get update && \
apt-get install --no-install-recommends -y \
qt5-default \
lsb-release ca-certificates build-essential pkg-config git \
libqt5serialport5-dev libqt5websockets5-dev qtdeclarative5-dev \
sqlite3 libsqlite3-dev libgpiod-dev libssl-dev curl cmake ninja-buildgit clone https://github.com/dresden-elektronik/deconz-rest-plugin.gitcmake -DCMAKE_INSTALL_PREFIX=/usr -DQT_VERSION_MAJOR=5 -G Ninja -B build
cmake --build buildcmake --install build --prefix tmpThe resulting plugin is located at: tmp/share/deCONZ/plugins/libde_rest_plugin.so
git clone https://github.com/dresden-elektronik/deconz-rest-plugin.git
cmake -DCMAKE_INSTALL_PREFIX=/usr -DQT_VERSION_MAJOR=5 -G Ninja -B build
cmake --build build
cmake --install build --prefix tmpIf you are downloading precompiled .deb packages for Ubuntu, Debian, or Raspbian, use the following commands to install them and resolve any missing dependencies:
sudo dpkg -i <package name>.deb
sudo apt-get install -fBuilding on Windows requires the MSYS2 MINGW32 environment.
pacman:pacman -Sy mingw-w64-i686-qt5 mingw-w64-i686-openssl mingw-w64-i686-sqlite3git clone https://github.com/dresden-elektronik/deconz-rest-plugin.gitcd /c/src/deconz-rest-plugincmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/mingw32/lib/cmake -B build
cmake --build buildThe resulting plugin is de_rest_plugin.dll located in the build directory.
git clone https://github.com/dresden-elektronik/deconz-rest-plugin.git
cd /c/src/deconz-rest-plugin
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/mingw32/lib/cmake -B build
cmake --build buildCurrently, macOS support is limited to Intel Macs (x86_64).
Install dependencies using Homebrew:
brew install qt@5 ninja cmakegit clone https://github.com/dresden-elektronik/deconz-rest-plugin.gitcd deconz-rest-plugin./build-macos.shcp build/de_rest_plugin.dylib /Applications/deCONZ.app/Contents/PluginsThe compiled plugin is de_rest_plugin.dylib.
git clone https://github.com/dresden-elektronik/deconz-rest-plugin.git
cd deconz-rest-plugin
./build-macos.sh
cp build/de_rest_plugin.dylib /Applications/deCONZ.app/Contents/PluginsInstallation instructions vary based on your hardware (RaspBee vs ConBee) and operating system. Always refer to the official Phoscon website for specific platform/device instructions.
Important: Before updating from a previous version, always create a backup in the Phoscon App and review the changelog.
The deCONZ package includes a systemd script that allows the service to run without an X11 server (headless mode).
$ sudo systemctl enable deconzIf you are using a default installation or a dresden elektronik sd-card image, the GUI may autostart. Disable it using:
$ sudo systemctl disable deconz-gui
$ sudo systemctl stop deconz-gui$ sudo systemctl enable deconz
$ sudo systemctl disable deconz-gui
$ sudo systemctl stop deconz-guiUse CMake to build the plugin on modern Linux distributions like Debian Trixie that use Qt6. This method automatically pulls headers and sources from deconz-lib, so the deconz-dev package is not required.
Install the following dependencies via apt-get:
apt-get update && \
apt-get install --no-install-recommends -y \
lsb-release \
ca-certificates \
build-essential \
cmake \
pkg-config \
git \
sqlite3 \
libsqlite3-dev \
libgpiod-dev \
libssl-dev \
qt6-base-dev \
qt6-base-dev-tools \
qt6-serialport-dev \
qt6-websockets-dev \
qt6-declarative-dev \
qt6-5compat-dev \
dpkg-dev \
fakeroot \
curl \
wgetgit clone https://github.com/dresden-elektronik/deconz-rest-plugin.gitcmake -DCMAKE_INSTALL_PREFIX=/usr -DQT_VERSION_MAJOR=6 -G Ninja -B build
cmake --build buildcmake --install build --prefix tmpThe resulting plugin is located at: tmp/share/deCONZ/plugins/libde_rest_plugin.so
git clone https://github.com/dresden-elektronik/deconz-rest-plugin.git
cmake -DCMAKE_INSTALL_PREFIX=/usr -DQT_VERSION_MAJOR=6 -G Ninja -B build
cmake --build build
cmake --install build --prefix tmpBuilding via QMake is deprecated and will be removed in the future. This method is only supported on Linux.
Install the deCONZ development package:
sudo apt install deconz-devgit clone https://github.com/dresden-elektronik/deconz-rest-plugin.gitcd deconz-rest-plugin
git checkout -b mybranch HEADqmake && make -j2qmake && make (without the -j2 flag).sudo cp ../libde_rest_plugin.so /usr/share/deCONZ/pluginsgit clone https://github.com/dresden-elektronik/deconz-rest-plugin.git
cd deconz-rest-plugin
git checkout -b mybranch HEAD
qmake && make -j2
sudo cp ../libde_rest_plugin.so /usr/share/deCONZ/pluginsThe deCONZ-homebridge.sh script is a background management utility designed to automate the integration between deCONZ and Homebridge on Linux systems. It monitors the deCONZ database for new Zigbee devices and manages the Homebridge configuration, including API keys, bridge IDs, and PINs.
zll.db for new device timestamps. When new lights are discovered, it waits for discovery to stabilize and then restarts Homebridge to include the new devices.~/.homebridge/config.json file, ensuring the bridgeid, apikey, and pin match the deCONZ settings.managed, not-managed, disabled, or reset based on database configuration.systemctl to manage the homebridge and deconz-homebridge-install services.The script uses the homebridge key in the deCONZ config2 table to determine how to handle the Homebridge installation. The following values are supported:
| Value | Action |
|---|---|
managed | The script manages the Homebridge configuration, API keys, and service lifecycle. |
not-managed | The script detects an existing Homebridge setup but will not overwrite or manage its configuration. |
disabled | The script stops and disables the homebridge and deconz-homebridge-install services and kills any running Homebridge processes. |
reset | The script stops Homebridge and deletes the persist and config.json files in the Homebridge directory to allow a fresh setup. |
updated | Triggers a restart of the Homebridge process. |
The deCONZ-homebridge-install.sh script automates the installation of the Homebridge environment required to integrate deCONZ with Apple HomeKit.
zll.db) to retrieve configuration settings like the REST-API port, proxy settings, and timezone.sqlite3 to be installed on the system to query the deCONZ database.https://www.phoscon.de to verify connectivity. If a proxy is configured in the deCONZ database, the script will attempt to use it.The script performs the following tasks:
nodejs, npm, homebridge, homebridge-hue, and homebridge-config-ui-x are already installed.16.14.2, it installs/updates Node.js using the NodeSource repository.npm to globally install:homebridgehomebridge-libhomebridge-huehomebridge-config-ui-xbonjour-hap (if missing)timedatectl.installing, install-error) back to the deCONZ REST API.