Hue Binding for API v2 [;


This is an extension of the official openHAB Hue binding with added support for API v2 (CLIP v2).

There is also a Hue for API v2 for openHAB v3.4.x in the Marketplace.

Pre-requisite: this binding requires the UPnP transport feature which is sometimes not automatically installed. So before installing please enter the following command at the console command prompt…

feature:install openhab-transport-upnp


Philips / Signify introduced a new Application Programming Interface (API) for their Hue system, known as API v2 (or CLIP v2). Over time, the old API will become obsolete, and be replaced by the new one. The binding contains all the API v1 functionality, and adds support for API v2 things as well. Some benefits of the API v2 version are…

  • Supports current and future Hue devices and features
  • Replaces the 15 different Thing types in v1 with a single Device Thing type
  • Things have dynamic channels created according to their actual features
  • Implements SSE (server sent events) to provide real time status updates
  • Uses HTTPS over HTTP2 for improved speed and security



This version of the binding includes all the code for API v1, so any things created in a v1 system will continue to function as before. However it also includes support for API v2 things. These v2 things are not the same as the v1 things, so this is a breaking change from existing things. However if existing things are present in the system when the new things are created, then the new things will take over as much of the existing thing settings as possible.

Release notes

  • 2023-05-12 first stable release on the Marketplace.

Hi Andrew
I have not updated for a while so i thought i would try the version from here.
Copied .kar into addons and my openHAB immediately errored and restarted.
Did not have much timevto look further so just put old .jar back.
Is the latest .kar the same as the PR linked .jar?

Is it prefered to use the procedure here to update? Including the bundle install etc?

I did see that i woukd need to recreate my room things as well it seems?

BTW. I am on 4.0.0.M2

The Jars are the same. So you can either drop the jar from the PR or the jar from here. The feature:install is needed to ensure that OH has UPnp loaded because that is sometimes needed for discovery.

Hi Andrew

I tried the JAR from the PR, but the changes have confused me a bit as some CHANNELS seem to have disappeared at some stage - just not sure how or why, so I have gone back to my working JAR, as follows:

272 │ Active │  80 │     │ openHAB Add-ons :: Bundles :: hue Binding

In this build I see the following Channels on my Rooms:

So it appears that the SWITCH channels is “missing”, but it still seems to exist and in fact works. I can find it if I look at the ITEMS:

I caused myself a problem too by reverting the JAR version after recreating one of the rooms, so I ended up with a broken link between the ITEM and CHANNEL, so no longer have a SWITCH for the room in question - and this is one function we use a lot.

I also seems to be getting the following WARN when rescanning for THINGS (though I am able to add the THING and it comes ONLINE:

12:56:53.733 [WARN ] [ommon.WrappedScheduledExecutorService] - Scheduled runnable ended with an exception:
java.lang.NullPointerException: null
        at java.util.Objects.requireNonNull( ~[?:?]
        at org.openhab.binding.hue.internal.discovery.HueBridgeNupnpDiscovery.getBridgeList( ~[?:?]
        at org.openhab.binding.hue.internal.discovery.HueBridgeNupnpDiscovery.discoverHueBridges( ~[?:?]
        at java.util.concurrent.Executors$ ~[?:?]
        at ~[?:?]
        at java.util.concurrent.ScheduledThreadPoolExecutor$ ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor.runWorker( ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor$ ~[?:?]
        at ~[?:?]

Oh, and that is WEIRD, just deleted and readded the ROOMS and the SWITCH Channel is back?

Will have another go with he latest JAR and maybe recreant ethe THINGS more than once to see what happens?

Will report back - but if you can look at the discovery WARN?


Just a follow up after re-installing the latest JAR again.

It took a long time to get ll the lamps etc online they remained “NOT YET READY” for a good few minutes, then got the expected warnings about missing CHANNELS:

13:12:05.548 [WARN ] [ue.internal.handler.Clip2ThingHandler] - 18d47ab1-36fd-4c0f-8206-a95969f6b8b9 -> updateChannelList() required channel 'dynamics' missing => please recreate thing!

After Deleting and Scanning to add back the THING for a Room, the Switch CHANNEL is again missing:

But linked and working:

Removed THING and re-added, but switch is still missing.

Confirmed same for all 4 Rooms.

Will remove and re-add all THINGS and Test further.

Hi Mark,

Many thanks for giving me such useful feedback. A couple of comments…

  1. Yes, the Zigbee channel was indeed removed; if there is a Zigbee error, the thing is marked as offline, so the Zigbee channel was not necessary
  2. Under some circumstances the Switch and Dimmer channels appear in ‘Advanced’; they are still present but less obvious to see in the UI. Reason is that one of the OH maintainers insists that if a thing has a Color (HSB) channel then it should be switched or dimmed via the B part rather than using a switch channel. (And ditto if it has a Dimmer channel). Personally I totally disagree with that. But the compromise is to move such ‘unwanted’ channels to ‘Advanced’ so he can’t see them.
  3. The NUpnP discovery issue is because of another PR was made to ‘fix’ that, and it actually ‘broke’ my code. So I need to ‘fix’ the ‘fix’ in a next build…



Thanks for the quick response Andrew

I am a bit unclear on this resonse - I didnt mention anything about a Zigbee channel? :slight_smile:

I thought I have looked for Advanced - but didn’t see it - but it is there, so no issue there.

Cool - will wait for that.

All seems to be back working as before, so happy!

I now just need to look at the Dynamics and Alert Channels - will look for your docs on them.

@Mark_VG apropos the NUpnp discovery issue, can you please open the following url in your browser and let me know the result? It should return a JSON payload, but in your case I am guessing that it does not. ??

Hi Andrew.

If i run from my phone on my local lan I get

Is that whst you needed?

Yep. Perfect. I reported it here

1 Like

Fix created:

That’s a somewhat unfair and inaccurate description. It’s not only one maintainer, but multiple, and the reason for the insistence is that all current bindings dealing with lights (including Hue V1) work the requested way (only a single color or brightness channel, no dedicated switch).
@Mark_VG probably was just confused because the initial Hue V2 binding behaved differently, but I’d be surprised if the switch was actually needed in his case.

Hi There
I was not confused at all.

I have used the SWITCH option in a widget that I modified from other versions and examples found in the forums.
I cleaned up my system after installing the Marketplace version of the binding yesterday, so no longer have any of my V1 THING and ITEMS to show this, but can restore a 3.4.2 backup to show this if you like?

HUE allows one to switch off the lights and turn them back on in the same state as they were when turned off - which we use a lot. In my case I hardly ever use the DIMMER, other than to temporarily adjust lights to suite a short term mood.

I am however OK with the SWITCH hidden in advanced - at least it is still available, so thanks for that.

I am not qualified to comment on how it worked in the background, or what the SWITCH was linked to.


PS: These are some examples showing that the SWITCH was available (and used) in the V1 Binding:

You can just create a switch item and link it to the brightness channel if you want to have a switch. If you also want the dimmer control you can use a dimmer item as well in parallel.

Exactly that also works with dimmer channels. You can send ON and OFF commands to it, which does precisely what you want.

Thank you. I did not know that. This will make it less of an issue for me for the reasons explained above.

I have however restored a backup from my 4.0.0-SNAPSHOT - Build #3359 system prior to using the V2 API Binding, so running the stock V1 binding that ships with openHAB:

244 │ Active │  80 │     │ openHAB Add-ons :: Bundles :: hue Binding

This version did offer the SWITCH channel (and not under Advanced):

So thank you all for the comments and advise and keep up the good work.

And thanks Andrew for the hard work in getting this all updated. The V2 API binding is most certainly a lot more responsive and as I mentioned on the other thread I have been able to achieve some things that just di dnto work before.

@AndrewFG On a lightly different note - Rooms with Color Temperature and Color Channels

This is something I brought up in your original Topic if you recall?

I was actually incorrect. It appears that the color and color temperature can actually be set on all lamps in a room - though the process if far from intuitive:

I got this procedure from the Facebook Hue Support group:

1. Tap on a Room
2. Tap on a Scene that sets all lights to the same colour (such as the Bright Scene).
3. Tap on any light
4. Tap on a blank area around the colour wheel to unselect the light you just selected.
5. Tap on the dot on the colour wheel
6. Drag the numbered icon (that represents all lights in the Room) around the colour wheel.


I am not sure how this works in the background - though it would be really nice to have the Color and Color Temperature CHANNELS back on the V2 binding. Creating a scene to change all the lights in a room is just such an overkill for what can at times be a once off change?

What do you think?

Please correct me if I am wrong, but step 2 is probably unnecessary, or? (In other words, the described procedure is not being applied to a scene, but rather to the grouped lights within the respective room or zone). Can you confirm that?

Me neither. In order to find out, I would need to see the encrypted HTTPS traffic between the Hue App, and the Hue bridge. And to do that I would need to set up an SSL Proxy server on my LAN, so that I could sniff the actual traffic. Depending on the Hue certificate authentication mechanics this may or may not even be possible. But in any case, it might take me a day or two to figure that out.

To add further to the fun, the documentation for the Hue API grouped_light GET command shows that it is not possible to read a color XY state or a color temperature state from such a resource; whereas by contrast the documentation for the grouped_light PUT command says that it would indeed be possible to write a color temperature or color xy command to such a resource. So in other words it might indeed be possible to introduce a ‘half channel’ for rooms and zones, whereby you could write a new value to them, but not read their actual state. Reason being that a) the GET would not return those data, and b) I have never observed an SSE state update for color xy or color temperature from a grouped_light resource. In yet other words the state would have to be shown permanently as as UNDEF. And there is a further difficulty in that there is no way to actually determine if any, or all, resources in a room or zone would actually support color xy commands or color temperature commands. Nor what would happen if you tried to send such commands to such a room or zone where one, more, or all, lights there-in do not support such features.

{BTW simply writing the above paragraph yet further strengthens my belief that the four Color XY, Dimming, Color Temperature, and On/Off state elements of a light or grouped_light resource need to be (also) accessible via individual channels and not (only) accessible (partly) via an HSB …}


Yes. Just checked and step 2 is notc equired.

I will have to digest the rest of your redpknse to understand. :grinning: But thought i woukd respond where i could.

EDIT: I did not consider the possible case of room with lights that do not support color? But as you know this was supported in the V1 API.

It would however be nice to have that functionality back if possible.

Actually if the lights are already both the same color (including color temperature) the step is not needed; whereas if they are not already the same, then an intermediate step 2 is needed to make them so before you can proceed with step 3.

1 Like