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

deCONZ Core

In essence, deCONZ is a graphical application to configure and control Zigbee devices.

deCONZ is highly configurable: the user interface is created dynamically. The supported Zigbee clusters, commands, and attributes are configured through a configuration file, general.xml, which can be modified by the user.

Normally deCONZ runs with the graphical user interface (GUI) enabled, but it can also run without displaying the GUI. While not recommended, this might be needed on "light" operating system installations, that don't provide a graphical environment, like Raspbian Lite, without the Raspbian Desktop. Note that deCONZ runs perfectly fine with the GUI enabled on a headless system (without monitor, keyboard or mouse), as long as the system provides and has started the graphical environment. In that case, use remote desktop or screen sharing software, like VNC, to access the GUI remotely.

The standard distribution of deCONZ includes the definition for two services: deconz-gui and deconz. Both these services start the same deCONZ programme, but deconz starts it without enabling the GUI. Only one of these services can be started at a time.

Note that the deCONZ core is not open source.

Radio Device

deCONZ uses a RaspBee, RaspBee II, ConBee, ConBee II, or ConBee III as Zigbee radio device. The radio device provides the Zigbee coordinator function in firmware; deCONZ provides the Zigbee application on top of that. The ConBee, ConBee II, and ConBee III provide a USB serial port for communication; the RaspBee and RaspBee II connect to the serial port on the Raspberry Pi using GPIO pins. deCONZ communicates with the radio device over the serial protocol.

Note that deCONZ needs to have permissions to access the serial port. On Raspbian buster, the user running deCONZ needs to be member of the dialout group.

Note that the device firmware is not open source. Also note the device firmware version, 0x26xx0500 (for Raspbee and ConBee), 0x26xx0700 (for ConBee II and RaspBee II), or 0x26xx0900 (for ConBee III) versus the deCONZ version: 2.05.xx. The device firmware is updated by the GCFFlasher_internal programme. Type GCFFlasher_internal -h for help. The latest released firmware is published on dresden-elektronik.de.

The endpoints and clusters advertised by the coordinator can be configured through the Endpoints tab of the deCONZ Network Settings popup window in the GUI. The implementation of these clusters, however, needs to be handled by a plugin, see below.

Plugins

deCONZ is extensible: plugins provide additional functionality, on top of the basic configuration and control of Zigbee devices.

The table below gives an overview of known plugins, whether they're open source (O) and whether they're bundled (B) with the deCONZ distribution:

Plugin	Description	O	B
REST API plugin	Gateway providing the REST API to Zigbee devices.	Y	Y
STD OTAU plugin	Over-the-Air-Upgrade (OTAU) server.	Y	Y
Signal Monitor Plugin	Test signal strength.	N	Y
Basic APS plugin	Example for plugin developers, showing the use of the deCONZ C++ API.	Y	N
CLI plugin	Gateway providing a command-line interface to Zigbee devices.	Y	N
XBee plugin	Experimental support for the XBee.	Y	N

Technically, these plugins are shared libraries, loaded by the deCONZ core programme on startup. They communicate with the core programme using the deCONZ C++ API. The header files for this interface do contain in-line documentation. These are installed to /usr/include/deconz by the deconz-dev package.

To use a plugin that isn't included in the deCONZ distribution, or to use a developer version of a plugin, you need to compile it yourself. See the instructions of the REST API plugin.

Phoscon

Phoscon is a user-friendly web application to control Zigbee devices. It comes with extensive user documentation.

Phoscon runs in a web browser. Technically, it's a bunch of HTML5 and client-side Javascript files. These use the REST API to communicate with the REST API plugin, which, in turn, communicates with the deCONZ core, which, in turn, communicates with the Zigbee radio device. Phoscon is bundled with deCONZ, installed to /usr/share/deCONZ/webapp/pwa, and served from the same web server as the REST API. Even so, it's not linked to the server it loads from.

Phoscon is not open source. The latest developer version can be run from phoscon.de.

REST API

Most apps (including Phoscon) and home automation integrations with "deCONZ" are based on the REST API provided by the REST API plugin. However, some home automation systems integrate directly with the radio device over the serial protocol, bypassing deCONZ and the REST API altogether.

The deCONZ REST API is very similar to the Hue API, so most apps and integrations for the Hue bridge tend to work with deCONZ as well. The APIs are not exactly the same, though, so some functionality might not work.

The deCONZ core supports out-of-the-box "all" Zigbee 3.0, Zigbee Home Automation (ZHA), and Zigbee Light Link (ZLL) devices. These devices should be able to join the Zigbee network formed by the radio device, showing up in the GUI. The ZCL configuration file, general.xml, might need to be extended with not yet supported clusters.

The REST API plugin provides basic out-of-the-box support for most "light-like" functionality (lights, plugs, wired switches, window coverings, exposed as /lights resources). Support must be added explicitly for advanced configuration and for sensor-like functionality (sensors, wireless switches, exposed as /sensors resources).

Once a device is supported by the REST API, it doesn't necessarily mean it's supported by apps (including Phoscon) or home automation integrations. Some devices might be supported out-of-the-box; others might need changes by the app and/or integration. To request support, please contact the provider of the app or integration.

Documentation how to access the REST API is found here.

ZShark

ZShark is a tool for capturing (sniffing) the packets sent over a Zigbee network. It integrates with WireShark to analyse the packets. It communicates directly with the radio device, by passing deCONZ, so you need a second device to sniff the network formed by the device connected to deCONZ.

ZShark is not open source. The latest version can be obtained from phoscon.de. It comes bundled with special sniffer firmware for the RaspBee and ConBee. The ConBee II and RaspBee II are not yet supported.

deCONZ GUI

The deCONZ GUI is far less user-friendly than Phoscon, as it exposes Zigbee in a raw fashion. It does provide some essential functionality that isn't available over the REST API. To understand the GUI, please read the deCONZ User Manual, available under the Help menu. It's rather old, but then so is deCONZ.

Below is some information missing from the user manual:

Node Status "LED"

I'm pretty sure Manuel posted a comment explaining the meaning of the colours of the status "LED" somewhere, but I cannot find it. Below an overview of what I've been able to find.

Colour	Meaning	Source
Grey	No activity
Blue	Message has been received from node, or from intermediary node en route to the node.	#849
Green	Poll request received from end-device connected to coordinator.	#871
Yellow	Message has been sent, but no ACK received	#82
Red	Timeout: no response received to message sent.

Keyboard Shortcuts

The deCONZ GUI supports the following keyboard shortcuts:

Key	Meaning
`0`	Send a Network Address Request for the selected node.
`1`	Send a Node Descriptor Request to the selected node.
`2`	Send a Power Descriptor Request to the selected node.
`5`	Send a Match Descriptor Request to the selected node for the On/Off cluster.Not documented, but discovered while sniffing.
`7`	Send an Active Endpoint Request to the selected node.
`8`	Send a Simple Descriptor(s) Request to the selected node.
`9`	Send a Discover Attributes to the selected node, for the previously selected cluster.You need to select a cluster, then select the node, and then press `9`.Not documented, but discovered while sniffing. Doesn't seem to work for manufacturer-specific clusters that require a Manufacturer Code, though.
`A`	Send Device Announcement for the coordinator.
ctrl-`B`	Send a Binding Table Request to the selected node (as of v2.05.81).
`L`	Request Management Leave (with rejoin) for the selected node.Don't use with innr lights, for they won't rejoin.
`R`	Request Routing Table of selected node.This will also colour the lines corresponding to these routes blue.
F5	Refresh selected node, i.e. send Node Descriptor Request, Active Endpoint Request, and Simple Descriptor(s) Request.
Del	Delete selected nodeNote that this does not (yet) reset the node - it will be back. See #2377.

Source: #1261