# homebridge-hue: putting a Signify Hue bridge behind Apple's HomeKit > homebridge-hue is a Homebridge plugin that exposes Hue compatible lights, plugs, sensors and switches to HomeKit, with automatic discovery of multiple bridges and a command line utility for talking to the Hue API. It is more than a wrapper around the bridge's own HomeKit support, and the wiki keeps a feature by feature comparison. **ebaauw/homebridge-hue** — Homebridge plugin for Philips Hue - Repository: https://github.com/ebaauw/homebridge-hue - Stars: 924 · Forks: 94 - Language: JavaScript - License: Apache-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/ebaauw-homebridge-hue ## A plugin that surfaces Hue resources HomeKit does not otherwise see homebridge-hue is a Homebridge plugin that exposes Hue compatible devices, described as lights, plugs, sensors and switches, connected to a Hue bridge by Signify, to Apple's HomeKit. It is authored and maintained by Erik Baauw, with the copyright line running from 2016 to 2026. The plugin does one thing, and it does it in depth. Homebridge itself is a bridge server that lets accessories that have no HomeKit support appear in the Home app, and this plugin is a platform inside that server. Where a generic Homebridge setup requires you to declare each accessory by hand, homebridge-hue discovers the Hue bridge, connects to it, and reads the resources it publishes. Several practical behaviours are called out in the documentation. Discovery of Hue bridges is automatic. One installation can support multiple bridges. Both the v2 square bridge and the v1 round bridge are supported, and the plugin works alongside the native HomeKit functionality of the v2 bridge rather than replacing it. That last point is the one most people get wrong. The v2 Hue bridge already speaks HomeKit on its own, so installing homebridge-hue on top of it can mean duplicate accessories in the Home app if you are not careful about what you expose. The wiki carries a feature by feature comparison across four configurations: the native HomeKit function of the gen-2 bridge, the native Matter function of the gen-2 bridge connected to HomeKit, Homebridge Hue with a Hue bridge, and Homebridge deCONZ with a deCONZ gateway. That comparison is the first document to read, not the installation guide. Hue was originally developed by Philips before its lighting division was split off into Signify, and Signify continues to use the Philips Hue brand name. ## The ph command line utility talks to the Hue API directly The package ships a command line utility called ph, declared in the package manifest as the bin entry cli/ph.js. It exists to interact with the Hue API from a command line, and the wiki carries a ph tutorial for an introduction. Running ph -h or ph --help gives a brief overview of the functionality and the command line arguments. This is more than a convenience wrapper. When a HomeKit integration misbehaves, the useful question is whether the bridge is at fault or the HomeKit mapping is at fault, and a direct API client lets you separate those two. Querying the bridge directly tells you what the bridge believes the state of a light or a sensor to be. If the API agrees with what HomeKit shows, the fault is in the mapping or in the network path between Homebridge and the bridge. The repository layout supports this being a first class feature rather than an afterthought. There is a cli/ directory alongside lib/, and the plugin's own package ships a config.schema.json, which is the schema Homebridge Config UI X uses to render the plugin's configuration form. The dependencies tell you what the plugin is actually made of. The dependencies are hb-hue-tools at about 1.3.3, homebridge-lib at about 8.1.5, and fakegato-history at about 0.6.7. ## Installing the plugin and pairing with the bridge The installation sequence is documented in three steps, and the first one is not this plugin at all. You follow the Homebridge wiki instructions to install Node.js and Homebridge, then install the plugin either through Homebridge Config UI X or manually. The manual install is a global npm install: ```bash $ sudo npm -g i homebridge-hue ``` Then you add the Hue platform to Homebridge's config.json, and run Homebridge Hue for the first time. On that first run you press the link button on each bridge, and the plugin writes the bridge ID and API key pair for each one to the log output. You then edit config.json to include those values. There is a wrinkle here that catches people out. The project notes that the bridge ID and API key cannot be added through the Homebridge Hue settings in Homebridge Config UI X, so you need the Homebridge Config Editor for that step. The plugin is installable through the UI, but the credentials are not settable there. Updates follow the same pattern, and the documentation asks you to read the release notes before updating: ```bash sudo npm -g i homebridge-hue@latest ``` Rolling back is a matter of pinning the version in the same command: ```bash sudo npm -g i homebridge-hue@0.13.70 ``` The reason to keep that command around is the warning about minor version changes. The documentation notes that a change to the minor version typically indicates that you need to review or redo your HomeKit configuration, because changes in the way Hue bridge resources are exposed can make HomeKit treat them as new accessories, services or characteristics. When that happens you lose the assignment of those accessories to rooms, scenes, actions and triggers. ## The network requirements are stricter than the install steps suggest The prerequisites section is where the real constraints are, and they are not software constraints. You need a Philips Hue bridge to connect the plugin to your Hue compatible lights, switches and sensors, and the recommendation is the latest bridge firmware with API v1.61.0 for a v2 bridge or v1.16.0 for a v1 bridge or higher. You need a server running Homebridge, and it can be anything running Node.js: a Raspberry Pi, a NAS system, or an always-on PC on Linux, macOS or Windows. The recommendation is wired Ethernet between the Homebridge server, the Hue bridge and the Apple TV acting as home hub. Two network conditions are non-negotiable. HomeKit uses multicast DNS, also known as Bonjour, to discover Homebridge, so the Homebridge server must be on the same subnet as the iDevices running HomeKit. And for remote access and for HomeKit automations, including support for wireless switches, you need an Apple TV of the 4th generation or later or a HomePod as the home hub. That second point catches people. Without a home hub, the automation support and the wireless switch support simply are not there, and no amount of configuration on the Homebridge side changes that. On the HomeKit app side, the documentation recommends the latest released versions of iOS, watchOS and tvOS, and warns that Siri and even Apple's own Home app still provide only limited HomeKit support. It suggests looking at third party apps such as the free Eve app or Matthias Hochgatterer's paid Home+ for the full feature set. ## Version constraints encoded in the package manifest The package manifest pins the environment tightly, which is unusual and worth reading before you upgrade anything else in your Homebridge setup. The engines field requires a Node version of 24.20.0, or ^24, or ^22, and Homebridge at ^2.4.0. It also lists three numbered bridge identifiers, BSB001 at 1.16.0, BSB002 at 1.78.0 and BSB003 at 1.78.0, which line up with the bridge API versions the plugin is built against. The troubleshooting section makes the matching requirement explicit. Homebridge Hue 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, and the author is direct about the reason: there is simply not the bandwidth to test them. That is a real operational constraint for anyone running Homebridge on a pinned or older Node. If your Node version falls outside the declared engines range, you are outside the tested configuration, and you will be one of the people doing the testing. The package also declares its own tooling. The scripts run standard for linting and jsdoc for documentation generation as a prepare step, using a jsdoc.json in the repository root, and the test script is a placeholder that prints Error: no test specified and exits with status 1. In other words, there is no automated test suite in this repository. The style guide badge points at standardjs, and the repository is written to the standard style. Also worth noting: the module is declared as an ES module with type set to module, and the entry point is index.js. ## Licence, maintenance state and what the wiki carries The licence field on the repository says Apache-2.0, a permissive choice with an explicit patent grant. This is not legal advice, but for a plugin distributed through npm that you install on your own hardware, the terms are conventional and unobtrusive. The release history shows active work without any sign of abandonment. Version 0.15.10 was released on 2026-08-29, with 0.15.9 on 2026-07-12 and 0.15.7 on 2026-06-08. The last push was on 2026-08-29, the same day as the newest tag, so the published version and the working tree are in step. The number is still in the 0.x range, which in npm terms means the interface is not guaranteed stable. The minor version warning in the documentation is the practical expression of that: minor bumps can change how resources are mapped to HomeKit accessories. Most of the reference documentation lives outside the repository, on the wiki. The wiki holds the features and supported devices list, the configuration reference for the config.json settings with examples, the resource links page explaining how to create links on the bridge for finer grained control over what is exposed and how, the ph tutorial, and a FAQ for troubleshooting. The repository itself carries the README, a config.schema.json, the cli and lib source, the JavaScript sources in index.js, an ISSUE_TEMPLATE.md and a LICENSE file. That split is the main thing to know before you start. The code is one part of the project and the wiki is where the operational knowledge is. ## Conclusion homebridge-hue suits a Homebridge user with Hue lights who wants more of the Hue resource set surfaced to HomeKit than the bridge's own HomeKit function gives, and who runs Homebridge on a machine with a stable wired network connection to the bridge. It does not suit someone who has no Homebridge server at all, since the plugin is a platform inside Homebridge rather than a standalone bridge, and it is not the right choice for a Hue setup where the native HomeKit function of the gen-2 bridge already covers the features you need. Before installing, read the feature comparison on the wiki against the native HomeKit and native Matter support of your bridge, and confirm your Hue bridge firmware is at API v1.61.0 for a v2 bridge or v1.16.0 for a v1 bridge or newer. ## FAQ ### What does homebridge-hue do? It is a Homebridge plugin that exposes Hue compatible lights, plugs, sensors and switches connected to a Signify Hue bridge to Apple's HomeKit. It discovers bridges automatically and supports multiple bridges from a single installation, on both the v2 square and v1 round bridge. ### How do I install homebridge-hue? Install Node.js and Homebridge following the Homebridge wiki, then install the plugin through Homebridge Config UI X or manually with sudo npm -g i homebridge-hue. Add the Hue platform to config.json, then run it once and press the link button on each bridge to capture the bridge ID and API key from the log output. ### Why did my HomeKit rooms and scenes get lost after a homebridge-hue update? The project warns that a change to the minor version usually means you need to review or redo your HomeKit configuration, because changes in how Hue bridge resources are exposed can make HomeKit treat them as new accessories, services and characteristics. You can roll back by pinning a version, for example sudo npm -g i homebridge-hue@0.13.70. ### What does the ph command do in homebridge-hue? ph is a command line utility bundled with the plugin for interacting with the Hue API directly, declared as the bin entry cli/ph.js. Running ph -h or ph --help prints a brief overview of its functionality and command line arguments. ### Which Node.js version does homebridge-hue support? The package manifest requires Node 24.20.0, or ^24, or ^22, and Homebridge ^2.4.0. The notes state the plugin was developed and tested with the latest LTS of Node.js and the latest Homebridge, and that other versions may or may not work. ## Sources - [ebaauw/homebridge-hue on GitHub](https://github.com/ebaauw/homebridge-hue) - [Issues](https://github.com/ebaauw/homebridge-hue/issues) - [License: Apache-2.0](https://github.com/ebaauw/homebridge-hue/blob/main/LICENSE) - [README](https://github.com/ebaauw/homebridge-hue/blob/main/README.md) - [Releases](https://github.com/ebaauw/homebridge-hue/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ebaauw-homebridge-hue