RaspBee II Installation

Installation

The deCONZ application is a tool to configure, control and monitor Zigbee networks with the RaspBee II.

The following sections describe the installation steps of deCONZ for various platforms.

Supported platforms

Raspberry Pi OS
Docker

Connection

Insert the battery of type 337/SR416SW as shown in the battery slot.
The RaspBee II must be placed on the Raspberry Pi header as follows:

Important: The RaspBee II must not be placed in an offset position, as this will damage the module!

Note

Connection problems can occur if USB 3.0 devices - such as external hard drives or memory sticks - are located in the immediate surroundings of the Raspberry Pi on which the RaspBee II is plugged.
This can be avoided by using a USB extension cable.

RaspBee II placed on Raspberry Pi Header perspective

Raspberry Pi OS

Supported Raspberry Pi models and distributions

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

Note

The following steps describe the manual installation of deCONZ. Alternatively a preinstalled SD-card image can be used.

Installing the Operating System

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

Insert the SD card into your PC or an SD card reader.
Raspberry Pi Device: Select your Raspberry Pi model.
Operating System: Select a current operating system.
Storage: Select the SD card drive.
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.

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.
Write: Start the copying process.
Remove the SD card from the card slot (eject it in Windows Explorer → right-click on the drive letter and select Eject)
Insert the microSD card into the Raspberry Pi’s SD card slot.
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.

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
```
In the menu item 3. Interface Options, set the I3 VNC option to Enable.
Restart the Raspberry Pi
```
 sudo reboot
```

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

deCONZ Installation

Configure user access rights of the serial interface
```
 sudo raspi-config
```
Interface Options → Serial Port
- Would you like a login shell accessible over serial? → No
- Would you like the serial port hardware to be enabled? → Yes
Note: Changes to access rights only become active after a restart.

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

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"

Update APT package list
```
 sudo apt update
```
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.

Note

After restarting the Raspberry Pi, deCONz starts automatically.

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.

RTC Installation

The real-time clock (RTC) is not mandatory for using the RaspBee II as a ZigBee coordinator. The RaspBee II requires the firmware version 0x26610700 or higher. The firmware update is described here.

When using an older distribution (before Debian Trixie)

Update and restart Raspberry Pi

 sudo apt update
 sudo apt upgrade
 reboot

Install dependencies

 sudo apt install i2c-tools build-essential

Download installation archive

 curl -O -L https://github.com/dresden-elektronik/raspbee2-rtc/archive/master.zip
 unzip master.zip

Change into extracted directory
```
 cd raspbee2-rtc-master
```
Compile RTC kernel module
```
 make
```
Install RTC kernel module
```
 sudo make install
```
Reboot Raspberry Pi
```
 sudo reboot
```
Configure system time to RTC module
```
 sudo hwclock --systohc
```

Test that RTC is working

 sudo hwclock --verbose

Waiting in loop for time from /dev/rtc0 to change
 ...got clock tick
 Time read from Hardware Clock: 2020/03/06 13:55:21
 Hw clock time : 2020/03/06 13:55:21 = 1583502921 seconds since 1969
 Time since last adjustment is 1583502921 seconds
 Calculated Hardware Clock drift is 0.000000 seconds
 2020-03-06 14:55:20.017097+01:00

When using a current distribution (from Debian Trixie)

Update and restart Raspberry Pi

 sudo apt update
 sudo apt upgrade
 reboot

Install dependencies
```
 sudo apt install i2c-tools build-essential
```
The linux-headers-rpi-xx package is usually already installed. If not, the correct version must be installed. The required version can be checked with uname -a.

The correct suffix of the necessary package is output.
```
 uname -a
```
for Raspberry Pi 1 | Raspberry Pi Zero: rpi-v6
```
 sudo apt install linux-headers-rpi-v6
```
for Raspberry Pi 2: rpi-v7
```
 sudo apt install linux-headers-rpi-v7
```
for 32-Bit Raspberry Pi 3, 4 und Zero2: rpi-v7l
```
 sudo apt install linux-headers-rpi-v7l
```
for 64-Bit Raspberry Pi 3, 4, 5: rpi-v8
```
 sudo apt install linux-headers-rpi-v8
```

Download installation archive

 curl -O -L https://github.com/dresden-elektronik/raspbee2-rtc/archive/master.zip
 unzip master.zip

Change into extracted directory
```
 cd raspbee2-rtc-master
```
Compile RTC kernel module
```
 make
```
Install RTC kernel module
```
 sudo make install
```
Reboot Raspberry Pi
```
 sudo reboot
```
Configuring and testing the RTC
```
 timedatectl
```

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.

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:

Stop the GUI service immediately.

  sudo systemctl disable --now deconz-gui

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:

Stop the headless service immediately.
```
  sudo systemctl disable --now deconz
```
Start the GUI service now and every time the system starts.
```
  sudo systemctl enable --now deconz-gui
```

Firmware Update

The firmware of the RaspBee II can be updated manually.

The individual steps, are described in the FAQ.