Homebridge Hue


Homebridge plugin for Philips Hue

$3

Note that Hue was originally developed by Philips, before they split off their Lighting division into Signify.
Signify are still using the Philips Hue brand name.

See the Wiki for a list of Homebridge Hue features and supported devices, including a comparison of the features of:
- The native HomeKit function of the gen-2 (square) Hue bridge; of
- The native Matter function of the gen-2 (square) Hue bridge, connected to HomeKit; of
- Homebridge Hue in combination with a Hue bridge; and of
- Homebridge deCONZ in combination with a deCONZ gateway.

Homebridge Hue does automatic discovery of Hue bridges.
It supports multiple bridges from one installation.
It supports both the v2 (square) and v1 (round) Hue bridge.
It works in combination with the native HomeKit functionality of the v2 Hue bridge.

Please see the Wiki for a detailed description of Homebridge Hue.

$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.
See the Homebridge Wiki for details.
I recommend using wired Ethernet to connect the server running Homebridge, the Hue bridge, and the AppleTV acting as home hub.

To interact with HomeKit, you need Siri or a HomeKit app on an iPhone, Apple Watch, iPad, iPod Touch, or Apple TV (4th generation or later).
I recommend to use the latest released versions of iOS, watchOS, and tvOS.
Please note that Siri and even Apple's Home app still provide only limited HomeKit support.
To use the full features of Homebridge Hue, you might want to check out some other HomeKit apps, like the Eve app (free) or Matthias Hochgatterer's Home+ app (paid).

As HomeKit uses multicast-DNS (a.k.a. Bonjour) to discover Homebridge, the server running Homebridge must be on the same subnet as your iDevices running HomeKit.
For remote access and for HomeKit automations (incl. support for wireless switches), you need to setup an Apple TV (4th generation or later) or HomePod as home hub.

$3

Issue ph -h or ph --help to provide a brief overview of its functionality and command-line arguments.

$3

- Edit config.json and add the Hue platform provided by Homebridge Hue, see Configuration;
- Run Homebridge Hue for the first time, press the link button on (each of) your bridge(s). Note the bridge ID/API key pair for each bridge in the log output. Edit config.json to include these, see Configuration.
Note that you cannot add these through the Homebridge Hue Settings in Homebridge Config UI X, but you can use the Homebridge Config Editor.

To update Homebridge Hue, simply issue another sudo npm -g i homebridge-hue@latest. Please check the release notes before updating Homebridge Hue. Note that a change to the minor version typically indicates that you need to review/redo your HomeKit configuration. Due to changes in the mapping how Hue bridge resources are exposed, HomeKit might treat them as new accessories, services, and/or characteristics, losing any assignment to HomeKit rooms, scenes, actions, and triggers. To revert to a previous version, specify the version when installing Homebridge Hue, as in: sudo npm -g i homebridge-hue@0.13.70.

$3

#### Run Homebridge Hue Solo
If you run into Homebridge startup issues, please run a separate instance of Homebridge with only Homebridge Hue (and Homebridge Config UI X) enabled in config.json.
This way, you can determine whether the issue is related to Homebridge Hue itself, or to the interaction of multiple Homebridge plugins in your setup.
You can start this separate instance of Homebridge on a different system, as a different user, or from a different user directory (specified by the -U flag).
Make sure to use a different Homebridge name, username, and (if running on the same system) port in the config.json for each instance.

#### Debug Log File
Homebridge Hue outputs an info message for each HomeKit characteristic value it sets and for each HomeKit characteristic value change notification it receives.
When Homebridge is started with -D, Homebridge Hue outputs a debug message for each request it makes to the bridge, for each state change it detects while polling the bridge, and for each push notification it receives from gen-2 Hue bridge event stream. Additionally, it issues a debug message for each bridge resource it detects.

To capture these messages into a log file do the following:
- If you're running Homebridge as a service, stop that service;
- Run Homebridge manually, capturing the output into a file, by issuing:
`
$ homebridge -CD 2>&1 | tee homebridge.log
`
- Interact with your devices, through their native app and or through HomeKit to trigger the issue;
- Hit interrupt (ctrl-C) to stop Homebridge;
- If you're running Homebridge as a service, restart the service;
- Compress the log file by issuing:
`
$ gzip homebridge.log
`

#### Debug Dump File
To aid troubleshooting, on startup, Homebridge Hue dumps its environment, including its config.json settings and the full state of all bridges into a compresed json file, homebridge-hue.json.gz.
IP addresses, and bridge API keys are masked.
This file is created in the Homebridge user directory, ~/.homebridge by default.
It can be downloaded through the Homebridge Config UI X user interface, from the Homebridge Hue _SETTINGS_ popup window, on the _Plugins_ tab.

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

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

$3

The HomeKit terminology needs some getting used to.
An _accessory_ more or less corresponds to a physical device, accessible from your iOS device over WiFi or Bluetooth.
A _bridge_ (like Homebridge) is an accessory that provides access to other, bridged, accessories.
An accessory might provide multiple _services_.
Each service corresponds to a virtual device (like a lightbulb, switch, motion sensor, ..., but also: a programmable switch button, accessory information, battery status).
Siri interacts with services, not with accessories.
A service contains one or more _characteristics_.
A characteristic is like a service attribute, which might be read or written by HomeKit apps.
You might want to checkout Apple's HomeKit Accessory Simulator, which is distributed as an additional tool for Xcode.

Internally, HomeKit identifies accessories by UUID. For Zigbee devices (lights, sensors, switches), Homebridge Hue bases this UUID on the Zigbee mac address. For non-Zigbee resources (groups, schedules, CLIP sensors), the UUID is based on the bridge ID and resource path (e.g. /sensors/1). By not using the resource name (e.g. Daylight`), Homebridge Hue can deal with duplicate names. In addition, HomeKit will still recognise the accessory after the resource name has changed on the bridge, remembering which HomeKit room, groups, scenes, actions, and triggers it belongs to. However, when a non-Zigbee bridge resource is deleted and then re-created, resulting in a different resource path, HomeKit will treat it as a new accessory, and you will need to re-configure HomeKit.