homebridge-deconz

Homebridge plugin for deCONZ

Usage no npm install needed!

<script type="module">
  import homebridgeDeconz from 'https://cdn.skypack.dev/homebridge-deconz';
</script>

README

Homebridge deCONZ

Downloads Version Homebridge Discord

GitHub issues GitHub pull requests JavaScript Style Guide

Homebridge plugin for deCONZ

Copyright © 2022 Erik Baauw. All rights reserved.

Work in Progress

See Future Development of Homebridge Hue for positioning Homebridge deCONZ versus Homebridge Hue.

Homebridge deCONZ is still under development. See Releases for more details.

If you have a question, please post a message to the #hue channel of the Homebridge community on Discord.

Introduction

This Homebridge plugin exposes to Apple's HomeKit ZigBee devices (lights, plugs, sensors, switches, ...) and virtual devices on a deCONZ gateway by dresden elektronik. Homebridge deCONZ communicates with deCONZ over its REST API, provided by its REST API plugin. It runs independently from the Phoscon web app, see deCONZ for Dummies.

Prerequisites

You need a deCONZ gateway to connect Homebridge deCONZ to your ZigBee devices (lights, plugs, sensors, switches, ...). For Zigbee communication, the deCONZ gateway requires a ConBee II or Conbee USB stick, or a RaspBee II or RaspBee Raspberry Pi shield.
I recommend to run deCONZ with its GUI enabled, even on a headless system. When needed, you can access the deCONZ GUI over screen sharing.

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 Homebridge installation, with the Homebridge UI as only other plugin, or in a separate child bridge, in a Homebridge installation with other plugins.

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 configure Homebridge deCONZ, and to use its full features, 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 version of the Apple device OS: iOS, iPadOS, macOS, ... HomeKit doesn't seem to like using different Apple device OS versions.

Configuration

Most settings for Homebridge deCONZ can be changed at run-time from HomeKit, by the owner of the HomeKit home. These settings are persisted across Homebridge restarts. In config.json, you only need to specify the platform, and maybe the hostname or IP address and port of your deCONZ gateway(s). See the Wiki for details and examples.

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 configure the accessory.

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. After two minutes, Homebridge deCONZ will give up, exposing the gateway accessory anyways, but marking it inactive. Set Expose on the Gateway Settings service of the gateway accessory to retry obtaining an API key. Homebridge deCONZ will not retry to obtain an API key on Homebridge restart.

After setting Expose Lights, Expose Sensors, or Expose Groups on the Gateway Settings service, Homebridge deCONZ will expose a device accessory for each of the corresponding devices. When clearing the characteristic, the corresponding device accessories are removed from HomeKit.
Each device accessory has a Device Settings service, to configure the device. Clear Expose on that service, to blacklist the device, and remove the associated accessory from HomeKit.
The gateway accessory gains an additional Device Settings service for each blacklisted device. To re-expose the corresponding accessory, set Expose on that service.
Note that, unlike Homebridge Hue, Homebridge deCONZ handles blacklisting per device, instead of per resource. Setting Expose Lights will include the ZHAConsumption and ZHAPower /sensors resources for smart plugs, and the ZHABattery for window covering devices; setting Expose Sensors will exclude these.
Note that HomeKit doesn't like configuration changes. Allow ample time after exposing or removing accessories for HomeKit to sync the changed configuration to all Apple devices.

Command-Line Utility

Homebridge deCONZ includes the deconz command-line utility, to discover, monitor, and interact with a deCONZ gateway. For more details, issue:

deconz --help