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.

Zigbee in Home Assistant with deCONZ and ConBee II

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.

conbee II USB Zigbee Coordinator
ConBee II USB Zigbee Coordinator

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.
Create a Deconz container in Container Station in QNAP QTS
Create a Deconz container in Container Station in QTS
  1. 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.
Basic configuration of the QNAP Container Station Deconz image
  1. Click on the Advanced settings >> link
  2. 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.
Deconz container environment variables
  1. On the Network tab, choose Host for the Network Mode option.
Configure the network settings for the Deconz container
  1. 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.
Configure the Device settings for the Deconz container.
  1. 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.
Configure the Shared Folders for deCONZ in QNAP Container Station
  1. Click the Create button.
  2. On the review page, click the OK button.
  3. 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.
Deconz container is running in Container Station in QNAP QTS

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.
Login screen of the Phoscon Deconz web application
  1. Create a password and click the Next button.
Password screen of Phoscon Deconz web application
  1. 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.
Light setup screen in the setup phase of the Phosocon Deconz web application
  1. 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.
Group configuration option in Phoscon Deconz web app.

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.

The Firmware on the ConBee II is listed as Not Connected in the deCONZ web interface
The Firmware on the ConBee II is listed as Not Connected in the deCONZ web interface. To fix this problem. the firmware on the ConBee II device needs to be updated with Docker via the SSH terminal.

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.

The firmware version is now set for the ConBee II device in the deCONZ web interface
The firmware version is listed indicating that deCONZ is connected to 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.
Add a new sensor in the deCONZ Phoscon main menu via the ConBee II
  1. On the Select vendor screen choose Other.
Sensor vendor selection in the Deconz Phoscon sensor setup screen.
  1. Phoscon App is searching for a new sensor. Follow the device instructions for pairing devices.
deCONZ add sensor screen searching for a sensor.
  1. When the device is found a green bar at the bottom indicates Sensor ready.
deCONZ with ConBee II connecting to Aqara TVOC Temperature Sensor without an Aqara hub
Phoscon App with ConBee II connected to Aqara TVOC Temperature Sensor without an Aqara hub

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.
Search for the deCONZ integration in Home Assistant.
  1. A configuration screen comes up. Enter the IP address and port of the Phoscon deCONZ gateway (web application address). Click the Submit button.
Configure the address to the deCONZ gateway in the Home Assistant integration.
  1. A screen of instructions displays instructing how to link to the deCONZ gateway.
Home Assistant prompt to link the integration to the deCONZ server
  1. Log into the Phoscon App web application via the IP address and port.
  2. Click on the Hamburger menu, choose Gateway, and Advanced (bottom).
  3. 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.
Navigate to the Advanced settings of the ConBee II device in the deCONZ web application.
Advanced settings of the ConBee II device.
  1. Home Assistant should connect to deCONZ and show the Success screen. If not, try again until it connects.
The Home Assistant deCONZ integration successfully connected to the Phoscon deCONZ web application.

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.

deCONZ graphical interface via VNC Viewer
deCONZ graphical interface via VNC Viewer

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
deCONZ VNC Viewer connection setup
deCONZ VNC Viewer connection setup
  1. 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.
deCONZ VNC Viewer authentication prompt
deCONZ VNC Viewer authentication

Resources:

This post may contain affiliate links, which means I'll receive a commission if you purchase through my links, at no extra cost to you. Please read full disclosure for more information.