Raspberry Pi OS

Supported Raspberry Pi models and distributions

• Raspberry Pi (all models, except Pico)
• Raspberry Pi OS

Installing the Operating System

1. Download and launch Raspberry Pi Imager from the website www.raspberrypi.com/software
   

2. Insert the SD card into your PC or an SD card reader.

3. Raspberry Pi Device: Select your Raspberry Pi model.

4. Operating System: Select a current operating system.

5. Storage: Select the SD card drive.

6. Use OS Customisation: Click No if the default settings are acceptable, for example, if you are using an Ethernet cable and have direct access via a connected mouse, keyboard, and monitor. Otherwise, click Yes to adjust the settings: hostname, username, password, Wi-Fi, time zone, and keyboard layout, and save them with save.
   

7. To access the Raspberry Pi remotely, i.e., without a connected mouse, keyboard, and monitor, it is important to enable the SSH interface under the Services menu. Furthermore, you should assign your own login credentials under Set username and password.

8. Write: Start the copying process

9. Remove the SD card from the card slot (eject it in Windows Explorer → right-click on the drive letter and select Eject)

10. Insert the microSD card into the Raspberry Pi’s SD card slot

11. Connect the USB cable to the Raspberry Pi. The operating system will start automatically after approximately three seconds and will be ready for use after approximately one minute.

Remote Access

Remote access to the Raspbian OS desktop is via the VNC interface. This must first be enabled after successful operating system installation.

1. To do this, log in to the Raspberry Pi using a suitable SSH console program via its IP address, with the previously assigned Username and Password, and enter the following command:

   sudo raspi-config

2. In the menu item 3. Interface Options, set the I3 VNC option to Enable.

3. Restart the Raspberry Pi

   sudo reboot

You can now access the Raspbian OS desktop using a suitable VNC program.

deCONZ Installation

1. Set user USB access rights

   sudo gpasswd -a $USER dialout

   Note: Changes to access rights only become active after logging out and in or after a restart.

2. Import Phoscon public key

   wget -qO- https://phoscon.de/apt/deconz.pub.key | gpg --dearmor | \
             sudo tee /etc/apt/trusted.gpg.d/deconz-keyring.gpg >/dev/null

3. Configure the APT repository for deCONZ

   Stable

   sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
               generic main' > \
               /etc/apt/sources.list.d/deconz.list"

   Beta (alternative)

   sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
               generic-beta main' > \
               /etc/apt/sources.list.d/deconz.list"

4. Update APT package list

   sudo apt update

5. Install deCONZ

   When using an older distribution (before Debian Bookworm)

   sudo apt install deconz

   When using a current distribution with Qt6 (from Debian Bookworm onwards)

   sudo apt install deconz-qt6

After the installation deCONZ can be started via the application menu.

Menu > Programming > deCONZ

Now the first Zigbee devices can be paired via the Phoscon App. Further information can be found in the Phoscon App documentation.

Auto start of the deCONZ GUI (optional)

Start the GUI service every time the system starts.

sudo systemctl enable deconz-gui

Troubleshooting

If problems occur during the installation, the Support section answers frequently asked questions (FAQ) and provides further assistance.

Zigbee2MQTT

The installation instructions show how to start up Zigbee2MQTT with the ConBee II on a Raspberry Pi 5 with Raspberry Pi OS (Debian Trixie) installed.

Requirement

• Raspberry Pi 5
• Raspberry Pi OS → Installing the operating system see here

Installation with onboarding (web browser wizard)

This guide is based on the official description of Zigbee2MQTT on Linux.

1. Installation of MQTT Broker: Instructions

2. Installation of the necessary environment and Zigbee2MQTT: Instructions

3. Connect ConBee II to Raspberry Pi

4. Open the console and run the first start of Zigbee2MQTT

   cd /opt/zigbee2mqtt
   pnpm start

5. Open the web browser on the Raspberry Pi and start the Zigbee2MQTT onboarding via the address http://localhost:8080

   or

   Start Zigbee2MQTT onboarding via the Raspberry Pi using an external web browser from a PC or laptop:

   Method 1: http://raspberrypi:8080
   Method 2: [Raspberry_Pi_Hostname]:8080
   Method 3: [Raspberry_Pi_IP_Address]:8080

6. Select the ConBee II and check that the baud rate 115200 and the adapter deconz are set

7. Activate Zigbee2MQTT frontend and click Submit.

8. After about 30 seconds the Zigbee2MQTT frontend will be loaded

The first Zigbee devices can now be trained via the web frontend.

Installation via console

This guide is based on the official description of Zigbee2MQTT on Linux.

1. Installation of MQTT Broker: Instructions

2. Installation of the necessary environment and Zigbee2MQTT: Instructions

3. Connect ConBee II to Raspberry Pi and start the console

4. Determine the connection port

   ls -l /dev/serial/by-id

   

5. Open directory for configuring Zigbee2MQTT

   cd /opt/zigbee2mqtt/data/

6. Create configuration file configuration.yaml

   nano configuration.yaml

7. Enter the previously determined connection port, the baud rate 115200 and the adapter deconz and save the configuration file

   Example with generic interface name ttyACM0:

   mqtt:
        base_topic: zigbee2mqtt
        server: mqtt://localhost:1883
   serial:
        port: /dev/serial/ttyACM0
        baudrate: 115200
        adapter: deconz
   advanced:
        log_level: info
        network_key: GENERATE
        pan_id: GENERATE
        ext_pan_id: GENERATE
   frontend:
        enabled: true
        port: 8080
   homeassistant:
        enabled: false
   onboarding: false

   Example with defined ConBee II device name:

8. Start the Zigbee2MQTT application. If configured correctly, no error messages should appear.

   pnpm start

   

9. Open the web browser on the Raspberry Pi and start the Zigbee2MQTT frontend via the address http://localhost:8080

   or

   Start the Zigbee2MQTT frontend with an external web browser from a PC or laptop via the Raspberry Pi:

   Method 1: http://raspberrypi:8080
   Method 2: [Raspberry_Pi_Hostname]:8080
   Method 3: [Raspberry_Pi_IP_Address]:8080

   

The first Zigbee devices can now be trained via the web frontend.

Ubuntu

Supported Ubuntu versions

• Ubuntu 18.04 LTS 64-Bit PC (AMD64)
• Ubuntu 20.04 LTS 64-Bit PC (AMD64)

Installation

1. Set user USB access rights

   sudo gpasswd -a $USER dialout

   Note: Changes to access rights only become active after logging out and in or after a restart.

2. Import Phoscon public key

   wget -qO- https://phoscon.de/apt/deconz.pub.key | gpg --dearmor | \
             sudo tee /etc/apt/trusted.gpg.d/deconz-keyring.gpg >/dev/null

3. Configure the APT repository for deCONZ

   Stable

   sudo sh -c "echo 'deb [arch=amd64] http://phoscon.de/apt/deconz \
               generic main' > \
               /etc/apt/sources.list.d/deconz.list"

   Beta (alternative)

   sudo sh -c "echo 'deb [arch=amd64] http://phoscon.de/apt/deconz \
               generic-beta main' > \
               /etc/apt/sources.list.d/deconz.list"

4. Update APT package list

   sudo apt update

5. Install deCONZ

   When using an older distribution (before Ubuntu 24.04)

   sudo apt install deconz

   When using a current distribution with Qt6 (from Ubuntu 24.04 onwards)

   sudo apt install deconz-qt6

After the installation deCONZ can be started via the application menu.

Now the first Zigbee devices can be paired via the Phoscon App. Further information can be found in the Phoscon App documentation.

Auto start of the deCONZ GUI (optional)

1. Open the Startup Application Preferences via the application menu

   gnome-session-properties

2. Add a new entry with the following commandline:

   deCONZ --http-port=80 --auto-connect=1

   

Troubleshooting

If problems occur during the installation, the Support section answers frequently asked questions (FAQ) and provides further assistance.

Linux Headless

The SD card images as well as the standard installation method start automatically with graphical user interface.

Switch off graphical user interface (headless)

To switch off the graphical user interface (GUI), the following commands must be entered in the console:

1. Stop the GUI service immediately.

   sudo systemctl disable --now deconz-gui

2. Start the headless service now and every time the system starts.

   sudo systemctl enable --now deconz

Switch on graphical user interface (GUI)

To switch on the graphical user interface (GUI), the following commands must be entered in the console:

1. Stop the headless service immediately.

   sudo systemctl disable --now deconz

2. Start the GUI service now and every time the system starts.

   sudo systemctl enable --now deconz-gui

Docker

Supported host systems

• Linux x86_64/amd64
• Linux armv7 (e.g. Raspberry Pi)
• Linux arm64

To run deCONZ in a Docker container, we recommend the Docker image deconz-community/deconz-docker, which is maintained by the community.

The installation steps are described on https://github.com/deconz-community/deconz-docker.