This Docker image containerizes the deCONZ software from Dresden Elektronik, which controls a ZigBee network using a Conbee USB or RaspBee GPIO serial interface. This image runs deCONZ in "minimal" mode, for control of the ZigBee network via the WebUIs ("Wireless Light Control" and "Phoscon") and over the REST API and Websockets, and optionally runs a VNC server for viewing and interacting with the ZigBee mesh through the deCONZ UI.

Conbee is supported on amd64, armhf/armv7, and aarch64/arm64 (i.e. RaspberryPi 2/3B/3B , and other arm64 boards) architectures; RaspBee is supported on armhf/armv7 and aarch64/arm64 (and see the "Configuring Raspbian for RaspBee" section below for instructions to configure Raspbian to allow access to the RaspBee serial hardware).

Builds of this image are available on (and should be pulled from) Docker Hub, with the following tags:

Current latest version: 2.05.82
Current stable version: 2.05.81

Before running the command that creates the deconz Docker container, you may need to add your Linux user to the dialout group, which allows the user access to serial devices (i.e. Conbee/Conbee II/RaspBee):

sudo usermod -a -G dialout $USER

docker run -d \
    --name=deconz \
    --net=host \
    --restart=always \
    -v /etc/localtime:/etc/localtime:ro \
    -v /opt/deconz:/root/.local/share/dresden-elektronik/deCONZ \
    --device=/dev/ttyUSB0 \
    marthoc/deconz

Use these environment variables to change the default behaviour of the container.

A docker-compose.yml file is provided in the root of this image's GitHub repo. You may also copy/paste the following into your existing docker-compose.yml, modifying the options as required (omit the version and services lines as your docker-compose.yml will already contain these).

version: "2"
services:
  deconz:
    image: marthoc/deconz
    container_name: deconz
    network_mode: host
    restart: always
    volumes:
      - /opt/deconz:/root/.local/share/dresden-elektronik/deCONZ
    devices:
      - /dev/ttyUSB0
    environment:
      - DECONZ_WEB_PORT=80
      - DECONZ_WS_PORT=443
      - DEBUG_INFO=1
      - DEBUG_APS=0
      - DEBUG_ZCL=0
      - DEBUG_ZDP=0
      - DEBUG_OTAU=0

Then, you can do docker-compose pull to pull the latest marthoc/deconz image, docker-compose up -d to start the deconz container service, and docker-compose down to stop the deconz service and delete the container. Note that these commands will also pull, start, and stop any other services defined in docker-compose.yml.

The --net=host option is not yet supported on Mac/Windows. To run this container on those platforms, explicitly specify the ports in the run command and omit --net=host:

docker run -d \
    --name=deconz \
    -p 80:80 \
    -p 443:443 \
    --restart=always \
    -v /opt/deconz:/root/.local/share/dresden-elektronik/deCONZ \
    --device=/dev/ttyUSB0 \
    -e DECONZ_WEB_PORT=80 \
    -e DECONZ_WS_PORT=443 \
    marthoc/deconz

Raspbian defaults Bluetooth to /dev/ttyAMA0 and configures a login shell over serial (tty). You must disable the tty login shell and enable the serial port hardware, and swap Bluetooth to /dev/S0, to allow RaspBee to work properly under Docker.

To disable the login shell over serial and enable the serial port hardware:

1. sudo raspi-config
2. Select Interfacing Options
3. Select Serial
4. “Would you like a login shell to be accessible over serial?” Select No
5. “Would you like the serial port hardware to be enabled?” Select Yes
6. Exit raspi-config and reboot

To swap Bluetooth to /dev/S0 (moving RaspBee to /dev/ttyAMA0), run the following command and then reboot:

`echo 'dtoverlay=pi3-miniuart-bt' | sudo tee -a /boot/config.txt`

After running the above command and rebooting, RaspBee should be available at /dev/ttyAMA0.

Firmware updates from the web UI will fail silently. Instead, an interactive utility script is provided as part of this Docker image that you can use to flash your device's firmware. The script has been tested and verified to work for Conbee on amd64 Debian linux and armhf Raspbian Stretch and RaspBee on armhf Raspbian Stretch. To use it, follow the below instructions:

1. Check your deCONZ container logs for the update firmware file name: type docker logs [container name], and look for lines near the beginning of the log that look like this, noting the .CGF file name listed (you'll need this later):

GW update firmware found: /usr/share/deCONZ/firmware/deCONZ_Rpi_0x261e0500.bin.GCF
GW firmware version: 0x261c0500
GW firmware version shall be updated to: 0x261e0500

2. docker stop [container name] or docker-compose down to stop your running deCONZ container (you must do this or the firmware update will fail).

3. Invoke the firmware update script: docker run -it --rm --entrypoint "/firmware-update.sh" --privileged --cap-add=ALL -v /dev:/dev -v /lib/modules:/lib/modules -v /sys:/sys marthoc/deconz

4. Follow the prompts:

• Enter the path (e.g. /dev/ttyUSB0) that corresponds to your device in the listing.
• Type or paste the full file name that corresponds to the file name that you found in the deCONZ container logs in step 1 (or, select a different filename, but you should have a good reason for doing this).
• If the device/path and file name look OK, type Y to start flashing!

5. Restart your deCONZ container (docker start [container name] or docker-compose up).

Q: Why does the script give an error about not being able to unload modules ftdi_sio and usbserial, or that the device couldn't be rest?

A: In order to flash the device, no other program or device on the system can be using these kernel modules or the device. Stop any program/container that could be using the modules or device (likely deCONZ) and then invoke the script again. If the error persists, you may need to temporarily remove other USB serial devices from the system in order allow the script to completely unload the kernel modules.

Setting the environment variable DECONZ_VNC_MODE to 1 enables a VNC server in the container; connect to this VNC server with a VNC client to view the deCONZ ZigBee mesh. The environment variable DECONZ_VNC_PORT allows you to control the port the VNC server listens on (default 5900); environment variable DECONZ_VNC_PASSWORD allows you to set the password for the VNC server (default is 'changeme' and should be changed!).

When using docker in swarm mode it is possible to use a docker secret for the VNC password.

1. Create a docker secret for the password: printf changeme | docker secret create deconz-vnc-password -

2. Update the docker-compose.yml:

version: '3.8'

services:
  deconz:
    image: marthoc/deconz
    volumes:
      - /opt/deconz:/root/.local/share/dresden-elektronik/deCONZ
      - /dev/conbeeII:/dev/conbeeII
    environment:
      - DECONZ_WEB_PORT=80
      - DECONZ_WS_PORT=443
      - DECONZ_DEVICE=/dev/conbeeII
      - DECONZ_VNC_MODE=1
      - DECONZ_VNC_PASSWORD_FILE=/run/secrets/deconz-vnc-password
    secrets:
      - deconz-vnc-password

secrets:
  deconz-vnc-password:
    external: true

3. Use docker stack command to deploy the service: docker stack deploy -c docker-compose.yml deconz

On some systems, the device name assigned to Conbee or RaspBee can change on reboot. This commonly happens when more than one dongle is used and happens to varying degrees on different host systems. UDEV support allows control over the name assigned to your device.

1. Set the UDEV environment variable to '1' when creating the container (-e UDEV=1) to enable UDEV support. (NOTE: the --privileged option is also required!)

2. Find the name assigned to your device in /dev/serial/by-id. E.g.: /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE1964292-if00.

3. Set the value of -e DECONZ_DEVICE to the value found in 2: -e DECONZ_DEVICE=/dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE1964292-if00. (Note that the --device parameter may not be required when using this method.)

Firmware updates from the web UI will fail silently and the Conbee/RaspBee device will stay at its current firmware level. See "Updating Conbee/RaspBee Firmware" above for instructions to update your device's firmware when a new version is available.

If you are NOT using host networking (i.e. --net=host), and wish to change the websocket port, make sure that both "ends" of the port directive (i.e. -p) are changed to match the port specified in the DECONZ_WS_PORT environment variable (otherwise, the websocket will not connect resulting in possibly no updating of lights, switches and sensors). For example, if you wish to change the websocket port to 4443, you must specify BOTH -e DECONZ_WS_PORT=4443 AND -p 4443:4443 in your docker run command.

Over-the-air update functionality is currently untested.

Please raise any issues with this container at its GitHub repo: https://github.com/marthoc/docker-deconz. Please check the "Gotchas / Known Issues" section above before raising an Issue on GitHub in case the issue is already known.

To contribute, please fork the GitHub repo, create a feature branch, and raise a Pull Request; for simple changes/fixes, it may be more effective to raise an Issue instead.

Pulling marthoc/deconz from Docker Hub is the recommended way to obtain this image. However, you can build this image locally by:

git clone https://github.com/marthoc/docker-deconz.git
cd docker-deconz
docker build --build-arg VERSION=`[BUILD_VERSION]` --build-arg CHANNEL=`[BUILD_CHANNEL]` -t "[your-user/]deconz[:local]" ./[arch]

Note: VERSION and CHANNEL are required arguments and the image will fail to build if they are not specified.

Dresden Elektronik for making deCONZ and the Conbee and RaspBee hardware.