[RELEASE] Philips Hue Zigbee Driver (not using Hue Bridge)

Background

I am using Philips Hue White and Color Ambiance bulbs (the latest generation which have both Zigbee 3 and Bluetooth) directly attached to Hubitat (the Zigbee 3 version appears to be a decent enough router for a strong mesh). I am doing this so I can bind the new Inovelli Blue switches to the bulbs to allow for direct control. While the existing Hubitat Zigbee drivers are functional, they do not provide access to some of the bulb features (effects etc.) and I was less than successful at keeping the bulb in sync when using the direct binding from the switch. I decided to write my first Zigbee driver to address these shortcomings.

This driver is only for Hue bulbs (works best with generation 3 or newer that have the bluetooth capability) that have been directly paired to the hub using Zigbee (not when using the Hue hub).


This driver provides the following features:

  • Standard On/Off, Level, Color Temperature and Color control
  • Enhanced Hue color command (provides expanded 0 - 360 hue range)
  • Standard start and stop level change native commands
  • Native stepped level change and stepped hue change commands
  • Effects support for the built-in bulb effects (firmware version dependent)
  • Reporting (push) updates when bulb state is changed from outside Hubitat
  • Uses Hue private cluster decoding to reduce Zigbee traffic (similar to the bridge)
  • Power restore state setting (dependent on recent bulb firmware)
  • Independent configuration of default transition times for level and color changes (note that on and off transitions are hardcoded in the bulb and cannot be changed so the driver has an option to make ON and OFF use dim commands as a workaround if needed)
  • Support for level pre-staging using preset level command when bulb is off
  • Support for color/CT pre-staging using set hue and set saturation and set color temperature commands while the bulb is off (the set level and set color commands will turn on the bulb to be compatible with room lighting app which I use extensively)
  • Fallback polling mode to support earlier generation of Hue bulbs
  • Health Check attribute to detect device being offline (option to select check interval up to an hour) or after 10 seconds if a command gets no response

One behavior to be aware of. Because these bulbs push updates to the driver, when doing any transitions you will see the intermediate values populate until the transition is complete and the bulb sends the final value. For example, dimming from 10 to 100, you will see the level value changes to e.g. 47, then maybe a 86 before eventually showing 100. If you do not like this behaviour, simply turn off the reporting option and the driver will poll after a delay instead.

Installation

MAKE SURE YOU HAVE UPDATED YOUR BULB TO THE LATEST FIRMWARE (via the Hue app using Bluetooth if you do not have a Hue hub)

To use this driver with an existing Hue device you can change the existing Zigbee driver on the device to this one, set the preferences, and then click done (It will automatically run the configure and refresh commands when settings are updated)

The driver is available from the Hubitat Package Manager (HPM) or directly via Github at hubitat-public/PhilipsHue at main · bradsjm/hubitat-public · GitHub

11 Likes

Ooh, this is really awesome -- I will definitely play around with this soon (likely weekend). Thank you @jonathanb!!

I'm not sure how useful it will be but it might also be possible to support the older Generation 2 (ZLL/HA1.2) versions of the bulbs. They don't support the push notifications of Zigbee 3, but I could fall back to polling them instead. My assumption was that people with older generation bulbs would be using the Hue hub because of all the issues I've heard about.

Let me know if you are using those with Hubitat and would want this?

2 Likes

@jonathanb - would this driver work with plain White Ambiance (non-RGB) bulbs too?

I was planning to test this driver out tomorrow, but I just realized my couple of applicable bulbs aren't full color so I figured I'd ask before diving in...

Thanks!

1 Like

If they are generation 3 or newer then yes, there is no reason why it would not work too for all non-RGB functions (e.g. color temperature).

My plan was to take the driver and split out the non-RGB code to have a individual version for the white if it worked.

I'm also able to support the previous Hue generation by falling back to polling mode that @kkossev has been testing.

Lastly, I'm incorporating the healthCheck attribute that @kkossev has been putting into his Tuya zigbee drivers to indicate when the bulb is not responding.

2 Likes

Awesome -- I'm planning to play around with it over the weekend here, so I'll let you know how it goes. Thanks again!!

Thank you @jonathanb !
Your driver is working excellently with my $25 '“midnight/third shift” produced :slight_smile: Philips Hue Gen2 color bulb! (model: LCT007).

2 Likes

Updated version (0.2)

  • Fallback polling mode to support earlier generation of Hue bulbs
  • Health Check attribute added to detect offline (option to select check interval)
  • Some bug fixes
3 Likes

Thank you for adding the healthCheck attribute, Jonathan!

I have configured the healthCheck interval to 1 hour :
image

Works as expected - if the bulb is powered off from the mains switch, it changes its status to offline after one hour if there were no any commands sent in this period, or 10 seconds after sending a command to the bulb without a confirmation!

3 Likes

Overall, the driver works well, but the odd thing I ran into was that Color Temperature is only coming across as 2 digits... Is that expected behavior?

I have an odd-ball setup that depends on my white-ambiance bulbs always getting reset to certain default CT value, so s 2-digit value was throwing that logic off.

But I really dig the potential here -- thanks again!

Nope, must be something to do with the parsing of the private data that is different. I'm researching it :slight_smile:

1 Like

Uploaded version 0.3 with the following changes:

  • Added support for 'set Enhanced Hue' command which takes an enhanced range hue value from 0 - 360 for when you want more accurate colors than the default 0-100 hue (the hue attribute in the driver will still show 0-100 range but the bulb will get the more accurate level sent to it)
  • Added step hue change (like stepped level change but for hue) and for color temperature
  • Available effects are now set dynamically by querying the bulb for which ones are supported
  • Added mode parsing for the 'Philips Hue White' bulb (on/off and level)
  • Various code cleanups

Known issues:

  • Color Temperature for Hue White Ambience bulbs not showing correctly
3 Likes

I'm really enjoying the added native stepped hue change (up/down with step size) commands so I can use the Hubitat button controller to make it easy for people to control the color from my Inovelli Switches. I have it so 3 taps on the up or down button on the switch will step through the available colors :smiley:

2 Likes

I've pushed a few more updates with fixes for some obscure bugs that needed squashing related to transition times.

Speaking of transition times, this version now lets you set specific times for color changes (vs. level changes) and for level changes you can set the time for dimming up vs. dimming down.

1 Like

Release 1.0 pushed to the repository and should also be available from HPM soon.

Note that the driver URL has changed (new URL in the first post) for manual installation. There are versions of the driver for Philips White and Color Ambiance, White Ambiance (Color Temperature) and White (Dimmable) bulbs.

When updating the driver please run the "Configure" command or simply update the preferences and save as that will also configure the bulb.

4 Likes

White Ambiance driver is working great! I finally got the kinks worked out of my crazy bathroom lighting setup... It's now grown to involve a G&S Group (to get reliable ZGM for the 2 bulbs) that's leveraged by a motion-based RL setup, and then a RM rule ensures the CT always gets properly reset in any "off" scenario.

Messier than I hoped, but hey, it works! And your driver definitely helps a lot - thank you!

1 Like

Hey @jonathanb, came down stairs to let the dogs out late last night, saw your post on my request for help, installed your driver, and went back to bed. Woke up this morning and my bulbs were off... victory!

Well, almost. While these appear to be working as advertised (CCT White 1600lm Hue with BT) the Current States field on the device page does not update to reflect commands that have been sent to the bulb. The bulb is getting them, but changes don't show. I've tried it with, and without the "Enable State Reporting" toggle on and off, but no joy.

@jonathanb Nice driver! I too am waiting on a bunch of Inovelli Blue 2 in 1's. I have about 22 recessed downlights that I'm going to retrofit with Hue downlights. Most will be white ambiance but a few will be color.

New to the Hue ecosystem, so maybe this is just how things work but if I set the color temp through your driver and then cycle the power off and on (which I will have to do until the Inovelli Blue's come someday), the bulbs revert to what I assume is the factory default setting. Is this just how they work when cycling power? I have power restore mode set to "last state".

The power restore last state is just on/off state so it is doing as expected. However, they may support the "power on color temperature" setting which allows setting a fixed color temperature to power on with, I'd have to try it out to see.

I will give Hue credit for their bulbs really adhering to the Zigbee 3 specifications even the more obscure ones like remembering the color temperature option.

Just released a minor 1.02 update for the CT and RGB bulbs that configure the bulb to remember the last color temperature and revert to it upon power cycle.

Note: After upgrading the driver you will need to select "Configure" on each device to push the updated settings to the bulb.