homebridge-hue: Warning: breaking changes in homebridge-hue v0.8

homebridge-hue v0.8 will break your existing HomeKit setup: HomeKit will no longer recognise the accessories and services as the ones previously exposed by an older version of homebridge-hue. This will cause the accessories and services to be dropped from any HomeKit room, group, scene, and automation. Effectively, you’ll have to redo you HomeKit setup.

I don’t particularly enjoy this myself: it typically takes me half a day to redo my HomeKit setup. However, I’ve been putting off these changes for far too long, and I need these for further development of homebridge-hue. This has, in fact, been a major impediment for moving towards dynamic platform accessories (issue #4).

When I started homebridge-hue, several years ago, the world of Hue was simple. The Hue bridge exposed a ZigBee device as a single REST API resource, which homebridge-hue exposed as a single HomeKit HomeKit service, for which homebridge created the corresponding HomeKit accessory. With the introduction of the Hue motion sensor, but even earlier with e.g. the dresden elektronik wireless ballasts, this 1:1 relationship between device, resource, service, and accessory no longer holds. The Hue motion sensor is one device, exposed as three /sensors resources by the REST API (ZLLPresence, ZLLLightLevel, ZLLTemperature), which homebridge-hue actually exposes as five different HomeKit services (Motion Sensor, Ambient Light Level Sensor, Temperature Sensor, Battery and Accessory Information), combined in a single HomeKit accessory. For stateless switches the setup is even more complicated (with a HomeKit service per button). More recently, fakegato-history has added an additional service for the history in Eve.

Until now, I’ve been able to handle these changes with the original design of homebridge-hue: expose each resource as a separate HomeKit service, and afterwards glue them together into a single HomeKit accessory. However, the current pre-v0.8 design of homebridge-hue still doesn’t recognise or manage HomeKit accessories. Over time, the code to workaround this limitation has become almost too complex to maintain. Furthermore, the current design has serious limitations:

• Obviously, to support dynamic platform accessories (issue #4), I need to manage the accessories;
• For smart plugs, I need to combine multiple resources into one HomeKit service (one /lights resource to control the plug, and a ZHAConsumption and/or ZHAPower /sensors resource for metering). For that, I need to know the accessory upfront;
• For weather sensors, the order of the ZHATemperature, ZHAHumidity and ZHAPressure /sensors resources is relevant: the ZHAHumidity needs to be first or second or the history service won’t be created;
• I cannot expose history for a temperature sensor (without humidity), as this might interfere with the motion history of the Hue motion sensor, again depending on the order of the /sensors resources;
• For chandeliers/luminaries consisting of multiple lights, I want to combine multiple /lights resources into one HomeKit accessory (in my never ending and ultimately doomed quest to avoid the dreaded 99 accessory limit);
• I need to whitelist explicitly each light with multiple /lights resources (see #198).

Starting with v0.8, homebridge-hue will manage accessories explicitly. The discovery of bridge resources has been refactored, to collect resources into HomeKit accessories first, and second to expose the resources as HomeKit services in the right order and in context of the HomeKit accessory (rather than first exposing each resource as a HomeKit service, in the (random) order as provided by the REST API, and second glueing these services into a HomeKit accessories). However, as a consequence of this, the IDs (and derived UUIDs) of the HomeKit accessories and services change, causing HomeKit to see new accessories instead of existing ones.