How to set up deCONZ and Phoscon on a Raspberry Pi and control all your ZigBee devices



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.

Necessary equipment

  • Raspberry Pi 1, 2B, 3B or 3B+ with power-supply and a compatible (≥8 GB) SD-card.
  • ConBee, ConBee II or RaspBee ZigBee interface.
Conbee, Conbee 2 and Raspbee

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:

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 http://<IP>/pwa/login.html.
    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:

Phoscon – 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 –
HomeSeer JowiHue plugin –
Domoticz plugin –
openHAB binding –


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.

deCONZ GUI in RealVNC Viewer