Homebridge deCONZ


Homebridge plugin for deCONZ

$3

Homebridge deCONZ is the successor of Homebridge Hue for exposing Zigbee devices connected to a deCONZ gateway.
See Future Development of Homebridge Hue for more details.

$3

You need a server to run Homebridge.
This can be anything running Node.js: from a Raspberry Pi, a NAS system, or an always-on PC running Linux, macOS, or Windows.
I strongly recommend to use a standard Homebridge installation, see the Homebridge Wiki for details.
I recommend to run deCONZ and Homebridge deCONZ on the same server, avoiding any network latency between deCONZ and Homebridge deCONZ, and preventing any potential network issues.
I strongly recommend to run Homebridge deCONZ in a separate child bridge.

To interact with HomeKit, you need an Apple device with Siri or a HomeKit app.
Please note that Siri and Apple's Home app only provide limited HomeKit support.
To use the full features of Homebridge deCONZ, you need another HomeKit app, like Eve (free) or Matthias Hochgatterer's Home+ (paid).
As HomeKit uses mDNS (formally known as Bonjour) to discover Homebridge, the server running Homebridge must be on the same subnet as your Apple devices running HomeKit.
Most cases of _Not Responding_ accessories are due to mDNS issues.
For remote access and for HomeKit automations (incl. support for wireless switches), you need to setup an Apple TV (4th generation or later), HomePod, or iPad as home hub.
I recommend to use the latest released non-beta version of the Apple device OS: iOS, iPadOS, macOS, ...
HomeKit doesn't seem to like using different Apple device OS versions.

$3

Homebridge deCONZ provides a Configuration API to change the run-time settings.
These changes take effect immediately, and are persisted across Homebridge restarts.
See Dynamic Configuration in the Wiki for details.
For now, these dynamic settings are managed through the ui command-line tool.
Eventually, Homebridge deCONZ might provide a configuration user interface to the Homebridge UI, using this configuration API.

When it connects to a deCONZ gateway for the first time, Homebridge deCONZ will try to obtain an API key for two minutes, before exposing the gateway accessory.
Unless Homebridge deCONZ runs on the same server as the deCONZ gateway, you need to unlock the gateway to allow Homebridge deCONZ to obtain an API key.
If you don't, Homebridge deCONZ will give up, after two minutes.
In this case, you need to set expose on the gateway dynamic settings, to retry obtaining an API key.
Homebridge deCONZ will not retry to obtain an API key on Homebridge restart.

Once it has obtained an API key, Homebridge deCONZ will expose all Zigbee devices connected to the gateway, by default.
Use the dynamic settings to exclude devices from being exposed, to change how devices are exposed, and to expose virtual devices like groups or CLIP sensors.
Homebridge deCONZ exposes a gateway accessory for each deCONZ gateway.
In Apple's Home app, this accessory looks like a wireless switch; you'll need another HomeKit app to use the other features of this accessory.

Note that HomeKit doesn't like configuration changes.
After adding or removing accessories, allow ample time for HomeKit to sync the changed configuration to all Apple devices.

$3

Each command-line tool takes a -h or --help argument to provide a brief overview of its functionality and command-line arguments.

$3

#### Check Dependencies
If you run into Homebridge startup issues, please double-check what versions of Node.js and of Homebridge have been installed.
Homebridge deCONZ has been developed and tested using the latest LTS version of Node.js and the latest version of Homebridge.
Other versions might or might not work - I simply don't have the bandwidth to test these.

#### Run Homebridge deCONZ Solo
If you run into Homebridge startup issues, please run Homebridge deCONZ in a separate child bridge.

#### Debug Log File
Homebridge deCONZ outputs an info message to the Homebridge log, for each HomeKit characteristic value it sets and for each HomeKit characteristic value change notification it receives. Make sure that logLevel of the corresponding accessory is at least 1, to see these info messages.

Homebridge deCONZ outpits a debug message to the Homebridge log, for each interaction with a deCONZ gateway.
Make sure to run Homebridge in DEBUG mode, and that logLevel of the corresponding accessory is at least 2, to see these debug messages. Set logLevel to 3 to log the payload of the interaction with deCONZ as well.

#### Debug Dump File
To aid troubleshooting, on startup, Homebridge deCONZ dumps its environment, including its config.json settings, dynamic settings, and the full state of all gateways into a compresed json file, homebridge-deconz.json.gz.
This file is located in the Homebridge user directory.

#### Getting help
If you have a question about Homebridge deCONZ, please post a message to the #deconz channel of the Homebridge community on Discord.

If you encounter a problem with Homebridge deCONZ, please open an issue on GitHub.
Please attach a copy of homebridge-deconz.json.gz to the issue, see Debug Dump File.
Please attach a copy of the (compressed) Homebridge log file to the issue, see Debug Log File.
Please do not copy/paste large amounts of log output.

$3

Having said that, adding support for new devices, in Homebridge deCONZ, and in the deCONZ REST API plugin, is very hard without having physical access to the device.
Since this is a hobby project, I cannot afford to spend money on devices I won't be using myself, just to integrate them for the benefit of others.
I am happy to receive small donations in the form of new devices to integrate, or the money to buy these devices myself.
I am also happy to return the devices afterwards, if you provide the shipping costs.
Please contact me by email or on Discord for shipping details.

$3