ZigBee for Dummies - dresden-elektronik/deconz-rest-plugin GitHub Wiki

(Work in progress)

Nodes

Router

End Device

Coordinator

Gateway

Endpoints

Clusters

Clusters come in pairs: a server cluster (blue number in the deCONZ GUI) and a client cluster (grey number in the deCONZ GUI).

In my experience, the server is the one that implements state, but there's probably some exceptions to that. Request commands are sent from a client cluster to the corresponding server cluster; responses and notifications from a server cluster to the corresponding client cluster. So the OnOff server cluster provides the OnOff attribute and receives On and Off commands; the client OnOff cluster sends On and Off commands.

Actuators

An actuator is a device that implements a server cluster (e.g. On/Off) to control a real-world state (turning a light on or off).

Sensors

A sensor is a device that implements a server cluster (e.g. Temperature Measurement), providing reports about the real-world state (e.g. Current Temperature).

Note that not all devices though of as sensors actually are. E.g. the IKEA Trådfri motion sensor actually works as a controller.

Controllers

A controller implements a client cluster (e.g. On/Off), to control an actuator through the corresponding server cluster.

Note that not all devices thought of as controllers actually are. E.g. the Hue dimmer switch actually acts as a sensor.

Bindings

Groups

Zigbee has groups alright, but they’re completely different from the /groups resources in the API and from how home automation systems handle groups.

A Zigbee group is best seen as a multicast address, to which a device subscribes. This is handled through the Groups server cluster. So rather than adding a /lights resource to a /groups resource, as the API exposes, in Zigbee, you add the group (address) to the device (light).

There’s no central object nor administration for a Zigbee group. To populate the lights array in a /groups resource, the API plugin needs to query all lights for the groups they’re subscribed to. There is no group state in ZigBee, state.all_on and state.any_on are computed by the API plugin from state.on of the /lights resources linked to from the /groups resource.

Controllers can be configured to send a command to a group (address) by binding the corresponding client cluster (On/Off, Level Control, Color Control, Scenes, Window Covering) to the group address. The API sends a command to a group (address) when doing a PUT to the action of the /groups resource. These commands consist of a single Zigbee broadcast message, typically causing all lights to react at the same time (to the human eye).

Groups in home automation systems typically are just a collection of lights. When changing the group state, the home automation system translates this to a series of commands, one per light. In deCONZ API speak, to a series of PUTs of the state of each /lights resource. The API plugin translates this to a unicast Zigbee message per light. Which large groups, this effectively amounts to a denial-of-service attack; in Homebridge Hue I need to throttle the rate of sending commands to deCONZ to handle HomeKit groups.

Morale: you want to use Zigbee / deCONZ API groups over home automation groups. Not only is this more resource efficient and does this provide a better user experience, it’s also invulnerable to routing issues on the Zigbee network (because broadcasts don’t use routing).

Homebridge Hue can expose groups as Lightbulb or Outlet accessories to HomeKit.

Scenes