Pairing Devices

Pairing devices to deCONZ typically involves the following steps:

Joining the ZigBee network formed by the RaspBee or ConBee;
Reading the device configuration;
Creating the REST API resources to expose the device;
Configuring the device;
Setting up the device in your applications (Phoscon, old web app, plugin for homebridge, Home Assistant, Domotic, ...).

1. Joining the ZigBee network

How a device connects to the ZigBee network depends on the type of device:

ZigBee routers (typically mains-powered devices) connect to multiple neighbouring routers, forming the mesh network. The coordinator (the RaspBee or ConBee) is a router (with additional functionality). Routers are coloured yellow in the deCONZ GUI, the coordinator is blue. The radio of a router is always on;
ZigBee end devices (typically battery-powered devices) connect to a single parent router. End-devices are coloured grey in the deCONZ GUI. Typically, the radio of an end-device is off most of the time, so it cannot receive requests. Requests to the device are sent to its parent, who caches the request (for like 7 seconds). When the device wakes, it needs to poll its parent to receive any pending requests. Some devices (e.g. the Hue motion sensor) poll their parent very often, appearing to be reachable all the time; others (e.g. most Xiaomi end devices) only poll once an hour. Some devices poll shortly after sending a command or report, some (again, most Xiaomi end devices) only poll at fixed intervals. See End Device Polling for more details.

Joining the network requires two steps: a) One or more routers in the network need to accept new devices. On opening the network, the coordinator sends a broadcast request to all routers to accept new devices; b) The device needs to be searching for a network to join, i.e. for a router that accepts new connection. Typically, the device needs to be factory reset for this. How this is done, depends on the device: holding a reset button for several seconds, cycling the power in a certain pattern, or using touchlink. Touchlink typically only works for a limited time after the device is powered. Some devices need to be power-cycled after they are reset.

After the device has joined the network, the corresponding node becomes visible in the deCONZ GUI. Sometimes the new node is hidden behind an existing node - you might want to check the Node List panel.

If no new node becomes visible in the deCONZ GUI, power down all you ZigBee routers (except the coordinator), and move the device close to coordinator. If you cannot move the device, use a USB extension cable to move the ConBee, or use a USB power bank to move the Raspberry Pi with the RaspBee.

If you run deCONZ on a headless server, you can still run the deCONZ GUI over VNC or SSH, see Access deCONZ GUI in headless setup