What is deCONZ and why should you use it?
Dresden Elektronik’s deCONZ is a free software to control ZigBee devices from a wide range of vendors like Ikea Trådfri, Philips Hue, Xiaomi Aqara, Osram Smart+ and many more.
This means you only need one hub to control them all, not one for each brand.
deCONZ also have an open API and has integrations for a lot of home automation systems like Home-Assistant, Domoticz, HomeSeer and openHAB.
- Raspberry Pi 1, 2B, 3B or 3B+ with power-supply and a compatible (≥8 GB) SD-card.
- ConBee, ConBee II or RaspBee ZigBee interface.
Download SD-card image
The absolute easiest way to install deCONZ on a Respberry Pi is to download a complete and ready Raspbian Stretch SD-card image with deCONZ and Phoscon already installed.
Phoscon is a easy web GUI to to control and configure deCONZ.
These images can be downloaded here:
I recommend downloading the last stable desktop release which is Phoscon_Gateway_2019-04-15.xz at the time of writing this guide.
If you want it is also possible to use a headless version.
However I recommend the desktop version over the headless version because even if you only need the Phoscon web-interface in the day-to-day use, the desktop version will make it possible to interact with deCONZ directly. A helpful tool for future diagnostics.
Flash the SD-card
To flash the image to your SD-card download and install/run Etcher
Download Etcher here: https://www.balena.io/etcher
After installation insert the SD-card in your computer and start Etcher.
Press Select image and select the Raspbian Stretch image file. Then click Select drive and select your SD-Card.
Click Flash! and wait until finish.
Now connect your ConBee, ConBee II or RaspBee ZigBee interface to the Raspberry Pi and Insert the SD-card.
Connect the Raspberry Pi to your router with an Ethernet cable and then connect the power supply.
The Raspberry Pi will now automatically boot and start deCONZ with the Phoscon app.
It should in a short time be ready to go, open your routers DHCP lease table to find the Raspberry Pi’s IP-address.
Connect and log in
There is three ways to log in to the device.
- Hypertext Transfer Protocol (HTTP)
Access the Phoscon app by a web-browser, go to
This is the main way to configure and control the ZigBee network.
- Secure Shell (SSH)
Access the Linux terminal with a SSH client. eg mRemoteNG or PuTTY.
- Virtual Network Computing (VNC)
Access the Linux desktop and the deCONZ GUI with a VNC client. eg Real VNC Viewer.
The default username/password is pi/raspbeegw
(It is recommended to change this password)
Adding ZigBee devices
Log in to the Phoscon web interface and select your ZigBee interface, then log in.
To get to the menu click the three horizontal lines up in the left corner.
Under Devices you have Lights, Switches and Sensors. Click the relevant category and then Add new lights/switch/sensor.
If you are adding a light the Searching for new device will start. If you are adding a switch or sensor the vendor and type must be selected (Just follow the instructions).
If the device is not found try moving closer to the ZigBee interface.
For ConBee/Conbee II a USB extension cable can improve stability.
Example of pairing with Ikea Trådfri remote control:
When you are finished with adding devices you can can configure remotes, lights, rules, scenes etc in the main menu:
Integration with other Systems
In the menu select “Gateway” under “Settings”. This is where you can connect to 3rd party systems.
Home-Assistant component – https://www.home-assistant.io/components/deconz/
HomeSeer JowiHue plugin – http://www.vuyk.info/hs/jowihue/start
Domoticz plugin – https://github.com/Smanar/Domoticz-deCONZ
openHAB binding – https://www.openhab.org/addons/bindings/deconz/
If you log in by VNC the deCONZ GUI will be visible. Here you can se more details about you ZigBee network and do more advanced configuration, but this is above the scope of this guide.