Add Zigbee to Home Assistant with ConBee II and deCONZ on QNAP TS-251

This tutorial shows how to use deCONZ and Phoscon App connected to a ConBee II USB Zigbee gateway for adding Zigbee devices to Home Assistant on a QNAP TS-251 NAS. The ConBee II device is a reliable USB device for a stable Zigbee network, ensuring a quality smart home setup.

What is a ConBee II USB Zigbee Gateway Device?

ConBee II small USB stick made by Phoscon that has a Zigbee radio within it for building a Zigbee device network into a smart home network. The ConBee 2 is a local device, meaning registration with a third party cloud service is not needed. This keeps all network data on the local network which reduces security concerns, leaking of your data, etc. The ConBee II device is the cornerstone of building a strong Zigbee network.

Full product details can be found on the dresden elektronik website. https://phoscon.de/en/conbee2

A ConBee II USB device can be purchased at many electronics retailers.

What is deCONZ

deCONZ is free software provided by Dresden Elektronik to visualize and configure a Zigbee network. deCONZ handles the API calls between the ConBee II device and the Zigbee devices. It has an open API that has been used by many device manufactures (like IKEA, Philips and Xiaomi/Aqara) as well as home automation systems like Home Assistant.

deCONZ runs silently in the background but does have a graphical component as well. Accessing the graphical component will be discussed later in this tutorial in the section titled: Setup VNC Viewer Connection to deCONZ, however in-depth usage of deCONZ will not be addressed here.

What is Phoscon App?

dresden elektronik provides the Phoscon App as a web based interface that is used for adding new devices to the Zigbee network via the deCONZ integration. The Phoscon App does have some basic home automation tools within it, and it would be possible to use this to build out some smart home automation. It is limited however in what it offers and thus Home Assistant can be used to make more complex automation schemes. This tutorial will focus on how to connect Zigbee devices to Home Assistant through the ConBee 2 and Phoscon App configuration should that layer be necessary.

Connect ConBee II to QNAP TS-251

Insert the ConBee II USB stick into an open USB port on the back of the QNAP TS-251.

Confirm the ConBee II device is seen by QNAP

SSH access to the QNAP NAS server is needed to confirm that the ConBee II device is recognized by the system and identify what address the device has been given. QNAP provides an article on how to setup SSH access: How do I access my QNAP NAS using SSH?.

To confirm that the device is recognized by the file system by running this command via the SSH terminal:

If the device is connected, a second line of output with the address of the device will be returned.

Troubleshooting

If the device doesn’t show, add the required drivers by calling this command via the SSH command line.

After adding the driver, unplug the device, plug it back in, and run ls /dev/ttyACM* again. The device show now be listed.

Install deCONZ with QNAP Container Station

deCONZ and Phoscon App will be installed via the QNAP Container Station application. Containers are essentially virtual machines. The container defines what the core software of the machine is, as well as configuration for how the machine should operate. This includes what hardware devices to connect to, where to store files, variables such as the local timezone, etc.

Container Station is a graphical interface for a Docker container, which has quickly grown to be an industry standard method for making portable virtual machines.

Create a Directory for Container Data

Device specific data should be stored in a local directory on the QNAP server to ensure it is not lost when the container is shut down or updated.

1. Open File Station
2. Create a new directory in a location you like for this data.
   • Example: Create a directory called Container at the root level.
3. Create a subdirectory under Container named deconz.

Create container in Container Station

1. In the QNAP web interface, open the Container Station application.
2. Click Create
3. Search for deconz and choose the deconzcommunity/deconz image from the Docker Hub tab.
4. Select the latest image version from the dropdown and click Next.

5. Set the basic configuration of the image.
   • Set the Name for the image.
   • Check the Auto start option.
   • Set the CPU Limit to 70%.
   • Set the Memory Limit to about 2/3 of the servers maximum memory.

6. Click on the Advanced settings >> link
7. On the Environment tab, configure / add the following settings:
   • DECONZ_DEVICE = /dev/ttyACM0
     • Note that this is the same device name was identified earlier in this tutorial via SSH. If for some reason the device is at a different path, adjust accordingly.
   • DECONZ_WEB_PORT = 9090
     • Port to connect to deCONZ via a web connection. Avoid using port 80, 8080, and any other ports that are known to be used already on the network.
   • DECONZ_WS_PORT = 9091 (optional)
     • Port to connect to deCONZ via a web connection via HTTPS. Avoid using port 443, and any other ports that are known to be used already on the network.
   • DECONZ_VNC_PORT = 5900
     • The port that a VNC connection will communicate on. Can be changed if needed
   • DECONZ_VNC_MODE = 1
     • This allows/blocks access to the deCONZ server via VNC (remote access). 0 = false, 1 = true.
   • DECONZ_VNC_PASSWORD = yourSecurePasswordHere
     • This password will be used for connecting via VNC Viewer
   • TZ = America/Chicago
     • Set to the desired time zone. The full list of possible time zone names can be found here. The TZ database name column is what value is expected here.

8. On the Network tab, choose Host for the Network Mode option.

9. On the Device tab, configure the following:
   1. Check the Run containers in privileged mode. checkbox.
   2. Add ConBee II device
      1. Click the Add button.
      2. Select TTY (4) from the Device dropdown. Ensure that both Read and Write are checked.

10. On the Shared Folders tab, configure the following:
    1. Volume from host
       1. Click the Add button in the Volume from host section.
       2. Set the Volume from host to the directory created previously (ie. /Container/deconz).
       3. Set the Mount Point to /config and ensure the Read and Write options are checked.

11. Click the Create button.
12. On the review page, click the OK button.
13. Wait just a few minutes as the container is created and booted up. The deCONZ container will show on the Overview tab of the Container Station application.

Access the Phoscon App Web Interface

Once the deCONZ container is up and running, the Phoscon App can be accessed through a web browser using the IP address of the QNAP NAS and the port defined on the Environment tab while configuring the container.

Phoscon App Web Interface URL

The URL to the deCONZ website interface uses the IP address of the QNAP server with the port used for setting DECONZ_WEB_PORT for the Container Station configuration.

• http://<your.ip.address.here>:<DECONZ_WEB_PORT>
• http://192.168.0.10:9090

Phoscon App Web Interface Initial Setup

1. Click on the icon on the screen with the IP address to start the login process.

1. Create a password and click the Next button.

3. The next screen wants to setup lights, which you can skip by clicking Proceed without lights if you don’t have any to setup at this time.

4. Next is a prompt to create a group of devices. This is can be used to group all of the lights in the house together, or devices in the same room, etc. This is an optional configuration. In the case of this tutorial, Home Assistant will be used for automation and the Phoscon app is only needed for adding devices to the deCONZ api. For that reason, the group setup can be skipped. Click the X to close.

Confirm the ConBee II Device is Recognized by deCONZ

Now that the Phoscon App website interface has been setup, confirm that the ConBee II USB device is recognized by Phoscon App / deCONZ.

Click on the hamburger menu in the top left and choose Gateway. Look at what the Firmware is set to. If it says Not connected, Phoscon App is not recognizing the ConBee II USB stick yet. To resolve this issue, the firmware on the the ConBee II device needs to be updated. This is done through an SSH connection using Docker.

If a firmware version is listed, it would be wise to check if there is a newer version of firmware with the steps below.

If the firmware does not need to be updated, skip past the Update the Firmware on the ConBee II Device section.

Update the Firmware on the ConBee II Device

The tutorial steps below walks through the steps to update the firmware on the ConBee 2 USB device. These steps are based on the steps provided by the deCONZ docker Github page. Additional information can be found at the Phoscon website (manufacturer of the ConBee II and deCONZ).

Run Docker command via SSH on the QNAP TS-251

The deCONZ API and Phoscon App web interface are running through a Container Station image, which really is a Docker image. Docker is a framework for running virtual servers and can be managed via the SSH command line.

QNAP does not expose the docker command by default. For that reason, it needs to be exposed before proceeding. This can be done by running the following command (more information can be found about at this article: Accessing Docker Command on QNAP):

Get the Docker Image ID

Running this command will list all of the docker containers and search (using grep) for those named deconz. The first column is the container ID and is needed on the next step to check if there is a firmware update available.

Identify Available Firmware Versions

This searches the docker log data, looking for if an updated firmware version exists. Change <container_id> to the container ID found in the step above.

If an output similar to this is found, there is a firmware version update needed and the firmware found is needed in the next steps.

Stop the deCONZ Container

The deCONZ Container Station image needs to be stopped before proceeding. This can be done in the QNAP web interface in the Container Station application by clicking the square icon to stop the server.

It can also be stopped via the command line with the docker command:

Update the ConBee II Firmware via SSH

Run this docker command to initiate the firmware update. This starts a docker container that initiates the firmware update script (entrypoint). The script is interactive and will prompt for which device to update as well as which firmware version to apply.

This is an example of the interactive script that will run.

NOTE: When prompted for the Device path, an auto-filled 0 is on the command line that needs to be deleted before typing in the device path of the ConBee II device. If you don’t delete the 0, the firmware update will fail.

Start the deCONZ Container

Now that the firmware has been updated, the Container Station container should be started. This can be done via the QNAP web interface in the Container Station application.

It can also be started via the command line with the docker command:

Wait until the container has fully started before proceeding.

Confirm ConBee 2 Firmware has Been Updated

The firmware update should be complete. Login to the Phoscon App web interface to confirm that the update resolved the issue of the ConBee II device not being found.

Go back to the Gateway page by clicking on the hamburger menu in the top left and choose Gateway. The firmware version should now be listed on the Firmware row. This indicates that the deCONZ API is connected and communicating with the ConBee II device.

Add a Device in the Phoscon App Website Interface

1. Login to Phoscon App
2. Click on the three line hamburger menu in the top left and choose Sensors. Then click the Add new sensor button.

3. On the Select vendor screen choose Other.

4. Phoscon App is searching for a new sensor. Follow the device instructions for pairing devices.

5. When the device is found a green bar at the bottom indicates Sensor ready.

Integrate deCONZ with Home Assistant

In Home Assistant, go to:

1. Configuration -> Integrations
2. Click the Add Integration button.
3. Type deCONZ in the search box and click the result.

4. A configuration screen comes up. Enter the IP address and port of the Phoscon deCONZ gateway (web application address). Click the Submit button.

5. A screen of instructions displays instructing how to link to the deCONZ gateway.

6. Log into the Phoscon App web application via the IP address and port.
7. Click on the Hamburger menu, choose Gateway, and Advanced (bottom).
8. Click the Authenticate app button. A countdown timer will begin. Before the timer runs out, switch back to Home Assistant and click the Submit button.

9. Home Assistant should connect to deCONZ and show the Success screen. If not, try again until it connects.

Troubleshooting: IP Address Changed for deCONZ Server

This is a troubleshooting step for an established system – this step is not needed for the initial setup.

If the IP address of the deCONZ server has changed, Home Assistant will no longer know where to find deCONZ and thus the integration fails. Some may say that a solution to this issue is to delete the deCONZ Home Assistant integration and re-add it. But that introduces risk as all of the devices added, assigned to automations, etc. may get lost as well. There’s a better way – just update the IP address in the Home Assistant configuration! Sadly this isn’t available from within the Home Assistant web interface. So this needs to be done on the file system. The file can be edited through an SSH connection, but just saying SSH connection may scare some users. So this tutorial will show how to do this in the QNAP admin.

To do this though, you’ll need to know where the Home Assistant configuration files are stored. If Home Assistant is running on QNAP via Container Station, it’s likely in a directory like Container/homeassistant

1. Login to the QNAP admin
2. Open the Text Editor app
3. Chose File -> Open and select the .system/core.config_entries file in the Home Assistant configuration directory (ie. Container/homeassistant/.system/core.config_entries)
4. Change the old IP address in this file to the new IP address.
   • Ctrl+F will bring up a search box to help find it.
5. Choose File -> Save to save the file
6. Go to the Home Assistant web interface
7. Choose Developer Tools from the left hand menu
8. Click the Restart button on the YAML tab under the Check and Restart section
9. Wait for Home Assistant to reload
10. Choose Settings from the left hand menu
11. Click Devices & Services
12. The deCONZ integration should now show with the updated IP address and state that it needs to be reconfigured. Keep this page open, but the deCONZ web admin needs to be opened first.
13. Login to the deCONZ web admin
14. Click on the hamburger in the top left and click on Settings -> Gateway
15. Click on Advanced at the bottom
16. In the Home Assistant web admin, click the Reconfigure button for the deCONZ integration
17. In the deCONZ web admin, click on the Authenticate app button
18. In the Home Assistant web admin, click the Submit link

After this sequence of steps deCONZ should now be successfully integrated into Home Assistant to the new IP address of the deCONZ server.

Access deCONZ Graphical Interface via VNC Viewer

deCONZ offers a graphical interface to view and monitor the Zigbee network. The VNC Viewer software is needed to access this part of deCONZ. The VNC Viewer software can be downloaded here.

Setup VNC Viewer Connection to deCONZ

1. Open VNC Viewer software
2. Click File -> New Connection
3. In the VNC Server field enter IP address of the QNAP server and the VNC port configured in the Container Station Environment Settings section.
   1. <your.ip.address.here>:<DECONZ_VNC_PORT>
4. In the Name field use a recognizable like deCONZ.
5. Click OK

6. A list of VNC server connections is shown. Double click on the newly created server to connect. An authentication screen is shown. Use the password specified in the Container Station Environment Settings section.

ConBee III

This tutorial is focused only on the ConBee II, though at this time it is an outdated device as the ConBee 3 has been released. While not tested, this tutorial should work but requires one additional option to be added to the containers Environment variables.

[source: deCONZ Docker Container on GitHub]

Resources:

• Troubleshooting ConBee II Connection Issues
  • https://phoscon.de/en/support#conbee2-connection-issues
• deCONZ Docker Container: Firmware Update
  • https://github.com/deconz-community/deconz-docker#updating-conbeeraspbee-firmware
• deCONZ Change Log
  • https://phoscon.de/en/changelog
• deCONZ Docker Container on GitHub
  • https://github.com/deconz-community/deconz-docker
• dresden elektronik Software
  • https://phoscon.de/en/conbee2/software
  • https://www.dresden-elektronik.de/funk/software/deconz.html
• Home Assistant deCONZ Integration
  • https://www.home-assistant.io/integrations/deconz/
• Related Tutorials
  • https://sprut.ai/blog/ustanovka-deconz-v-doker-na-qnap
  • https://www.youtube.com/watch?v=_EZDYUfVnZY
  • https://flemmingss.com/how-to-set-up-deconz-and-phoscon-on-a-raspberry-pi-and-control-all-your-zigbee-devices/

Products Related to this Post from Amazon

Phoscon ConBee II - Universal Zigbee 3.0 USB Gateway, incl. deCONZ & Phoscon App, Home Automation, Home Assistant, ioBroker, Zigbee2MQTT

-37%$23.34

QNAP TS-233-US 2 Bay Affordable Desktop NAS with ARM Cortex-A55 Quad-core Processor and 2 GB DDR4 RAM (Diskless)

$199.00

QNAP TS-253E-8G-US 2 Bay High-Performance Desktop NAS with Intel Celeron Quad-core Processor, 8 GB DDR4 RAM and Dual 2.5GbE (2.5G/1G/100M) Network Connectivity (Diskless)

$499.99

QNAP QM2-2P10G1TB 2 x PCIe Gen3 NVMe SSD & 1 x 10GbE (10G/5G/2.5G/1G/100M) Port Expansion Card to Enhance Performance

$219.00