I’m writing this because there are several scattered posts on how to control your Phillips Hue with your ISY. But they all use terms and make assumptions-of-understanding that the laymen (like me) just don’t have. So I wanted to leave behind a roadmap that anyone, with any level of understanding, can follow. I will update this post as needed if anyone is confused by anything. Please tell me if that’s the case. Also, please note, there are other methods to control the Hue. This method uses what is called a Network Module. It is an additional piece of software that you need to purchase for the ISY. To do so, open your ISY control panel and go to the Help menu and select Purchase Modules. Follow the instructions to purchase the Network Module.
BEFORE YOU BEGIN…there are a few bits of information you need to get first before you start tinkering with your ISY. This is the “hard” part, with lots of steps — but is something you only do once.
To get started, you need this info:
1) The IP Address of your Hue
2) Your Hue Bridge user name/ID
3) The name/ID of the lights, groups, or scenes in the Hue that you want to control (more on this later)
TASK 1 - Get the IP Address of your Hue
There are several methods to do this but I chose the one that uses the Hue app. Specifically the iOS Hue app. I imagine the Android app functions similarly (and could someone please confirm in the comments if that is the case?). To get the IP address of your Hue Bridge:
a) Open the Hue app (and verify you can control your lights so you know you are connected)
b ) Go to settings (gear icon in the upper right hand corner)
c) Select “Hue bridges”
d) Select your Hue bridge (probably by tapping the little “i” for information)
e) Select Network Settings
f) Toggle the DHCP button to “off” — at which point you will see the IP address of your Hue - write it down and save it
g) Toggle the DHCP back to “on” — to put things back how they were
I will later call the IP address you wrote down MY-HUE-IP-ADDRESS. If you see that anywhere, just use the IP address you wrote down.
TASK 2 - Get your Hue Bridge user name/ID
This requires using what everyone calls the “built-in Debug tool” which meant nothing to me. What exactly is that? Basically, you go to your web-browser and type in a specific URL (aka “web-page”) which then allows you to access your Hue bridge via your web-browser. This “Debug tool” allows you to send commands directly to the Hue — but also will allow you to get information from it. In this case, we are going to use the Debug tool to get the Hue Bridge user name/ID. To do that:
a) Open your web-browser
b ) Enter this URL into your web-browser...
http://MY-HUE-IP-ADDRESS/debug/clip.html
(swap out MY-HUE-IP-ADDRESS for the IP address you got in Task 1)
c) In the "URL" section of the debugger (NOT the browser), make sure it says /api -- the default will be /api/1234 - and you don't need the /1234
d) In the “Message Body” section, enter this entire statement: {"devicetype":"my_hue_app#iphone peter"} -- brackets and all (and, yes, peter)
e) Press the physical button on top of your Hue Bridge (requiring physical interaction is a security feature)
f) Press the “post” button on the debugger in your browser
g) Copy down the username that appears - save it someplace
That is your Hue User name. It is generated randomly by the Hue. I believe you used to be able to create your own name. Those days are over. If you see MY-HUE-USER-NAME anywhere, just replace it with the username you wrote down.
TASK 3 - Get the names of your Hue lights, groups, or scenes that you wish to control in the ISY
Some background info is helpful here. The Hue app breaks their system into lights, groups, and scenes. “Lights” are the individual lights themselves. “Groups” really should be called “rooms” IMHO — they are a collection of lights in one room. And finally “scenes” which are the various settings for a group lights — i.e rainbow colors, all red, all blue, etc.
To get info about your lights, groups, or scenes, you use the Hue “built-in Debug tool” again. You should already have it open from the prior task. I will show you an example on how to get individual light info:
a) In the URL field, enter: /api/MY-HUE-USER-NAME/lights
b ) Push the GET button
c) The Command Response field will populate with a bunch of stuff that looks like this:
"1": {
"state": {
"on": false,
"bri": 252,
"hue": 47116,
"sat": 252,
"effect": "none",
"xy": [
0.169,
0.0428
],
"ct": 153,
"alert": "select",
"colormode": "xy",
"reachable": true
},
"type": "Extended color light",
"name": "Hue plant",
"modelid": "LCT007",
"manufacturername": "Philips",
"uniqueid": "00:17:88:01:10:4a:67:b8-0b",
"swversion": "5.38.1.14919"
},
"2": {
"state": {
"on": false,
"bri": 252,
"hue": 47116,
"sat": 252,
"effect": "none",
"xy": [
0.169,
0.0428
],
"ct": 153,
"alert": "select",
"colormode": "xy",
"reachable": true
},
"type": "Extended color light",
"name": "Hue corner",
"modelid": "LCT007",
"manufacturername": "Philips",
"uniqueid": "00:17:88:01:10:26:23:6f-0b",
"swversion": "5.38.1.14919"
},
d) The actually names of the lights are literally the 1, 2, 3, etc at the top of each section. It’s as simple as that. I believe they are ordered in the order you added the lights. Hopefully you can pick out which light is which here by the "type" of light. But it doesn’t matter. You can trial and error the process in the ISY. You really don't even need to do this process to get the light IDs...you can just trial and error it...but you DO need to do this to get the group and scene ID names, if that something you later try to do.
TASK 4 - Getting your ISY to talk to your Hue lights
This involves something called a Network Resource — which was gibberish to me at first. As far as I can tell, it’s basically some data you enter in the ISY that helps you communicate with a third party device over the “network”. Hence... it's called a Network Resource. You have to create an individual Network Resource for every command you want to send. To turn a group on, you need a Network Resource for that. To turn a group off, you need a separate Network Resource to do that. Yes, it's annoying. To create your first Network Resource:
a) Open your ISY
b ) Next to “Main” and “Programs” is a tab called “Configuration” — select that.
c) Click on the “Network” sub-tab. Then click on the “Network Resources” sub-tab under that.
d) Click on “Add” at the bottom of the screen - where you can instantly name your Network Resource. Let’s call it Light 1 ON
e) Under the URL column, you might notice it says “select to edit content” — click on that field and a new data box appears
f) Enter or change this data…
—Change the “GET” box to “PUT”
—Put MY-HUE-IP-ADDRESS in the Host box. No http. No //. Just 10.x.x.x (or whatever your Hue's IP address is)
—Change Mode to “Raw Text”
—In the Path field, put...
/api/MY-HUE-USER-NAME/lights/9/state
NOTE: in this case, the “9” is my 9th light — change that parameter to the light number you want
—In the Body section, put...
{"on":true, "bri":255, "sat":255, "hue":255, "transitiontime":5}
NOTE: the “bri”(ghtness) and “sat”(uration) numbers of 255 are all adjustable parameters . Between 0 to 255. The “hue” range is 0-65535. That is the specific color of the light. Transition time is how long it takes the light to turn on. You do NOT need to specify all these parameters, just the ones you want. I believe that the parameters you don’t specify will stay whatever they were at before the last time they were set. So if you only specify, say, a brightness change, the color will be the same as it was before.
IMPORTANT NOTE: If you look back up to Task 3C, you can actually see these parameters reflected in the debugger window when you asked the Hue Bridge for info. So if you are trying to figure out what numbers to put in for an individual light (color, brightness, etc) to get a desired result, try this: use your iOS Hue app to set your Hue light how you like it, then do Task 3C again to get info from the Hue Bridge. The debugger window will fill up with the numbers you need to recreate a particular light/color combo.
g) Press Update — which will copy the data into the “actual” box so you can see it again
h) Press Save — which will close the box BUT!!!! You need to press the SECOND SAVE BOX on the next screen
i) Press the “Test” button — at which point your Hue light should go to the setting you entered
NOTE: I have had the "Test" button NOT turn my Hue light on...but going on to Task 5 still works. If you encounter this, try restarting your computer and trying again. You can also just go on to Task 5 and see what happens. Also, make sure you hit both SAVE buttons. See 4h above.
TASK 5 - Invoking this “Network Resource”
The final task is how to activate this functionality you created. The way you do that is via an ISY program. I’m not going to go into too much detail about that…unless someone requests it. The short answer is, there is a programmatic “action” called “Networking”. You can then either select “Wake on LAN” or “Resource”. If you select “Resource” a pop-up menu appears of all the Network Resources you created.
For example, I have a program running in the background that monitors whether I have turned a particular Insteon-device scene on. If the scene turns on, the ISY will trigger the Network Resource “LIGHT 1 ON”. When the scene turns off, another program triggers a second Network Resource to turn the light off. Yes, you need to create an entirely new resource to turn a light off. So to turn my light on, I have something like this in the Body field:
{"on":true, "bri":255, "sat":255, "hue":255, "transitiontime":5}
To create a second Network Resource to turn the light off, everything is the same expect I have JUST this in the Body field...
{"on”:false}
You don’t need all those other parameters if you are just turning a light off.
ADDENDUM - Controlling Scenes and Groups (not just lights)
Groups
In addition to individual lights, you can turn whole rooms on all at once (aka groups). If you use this method to control the Hue lights, when you turn the group on, whatever settings it was set to before are what you will get (i.e. colors, saturation, etc). This is how my Echo integration works. I tell Alexa to turn the room on…and it just turns the Hue lights on to whatever they were set at before. It has its uses.
Scenes
You can also turn Hue scenes on. That will cause the Hue lights in your group/room to go to a preprogrammed level. So you would create an Network Resource for each scene you want to invoke. Unfortunately, you cannot turn scenes OFF via a network resource (at least, I don’t know how how). But there is a simple workaround. You CAN turn whole rooms or individual lights off. In my case, I just create a Network Resource to turn the entire group/room off.
How To Do It
Go back to 3a above, where you asked the built-in Debug tool to give you info on the individual Hue lights. Except instead of putting this in the URL field…
/api/MY-HUE-USER-NAME/lights
You swap out “lights” for either “groups” or “scenes” like so (pick one)…
/api/MY-HUE-USER-NAME/groups
/api/MY-HUE-USER-NAME/scenes
Then press GET. As an example, let’s start with groups. That will give you something like this in the debugger’s Message Body:
{
"1": {
"name": "Living room",
"lights": [
"2",
"4",
"3",
"6",
"1"
You don’t record the name Living Room. All the ISY needs is the 1. That is the name of my living room "group". Then go up to Task 4F above to create a Network Resource in the ISY. Everything is the same except the Path and the Body.
In the path field, enter:
/api/YOUR-HUE-USER-NAME/groups/###/action
Swap out your own user name in there. And also, the ### is the number of the group you want to control. Then, in the body, put:
{"on": true}
That turns the group on. To turn it off, you have to create a totally separate Network Resource but put THIS in the body:
{"on": false}
Whatever you do, don’t forget to press save! Twice!!!!
NOTE: If you use a group number of zero, then ALL the lights will be turned either on or off.
Back to Scenes...
So you want to turn whole scenes on. You go into the debugger and enter this in the URL box, to get all the scene name to appear:
/api/MY-HUE-USER-NAME/scenes
Something like this comes up in the Command Response window:
{
"7fwrKuV56D9cvyA": {
"name": "Relax",
"lights": [
"1",
"2",
"3",
"4",
"6"
],
"owner": "70ed172f673e511b294419971348d598",
"recycle": false,
"locked": false,
"appdata": {
"version": 1,
"data": "NoG1L_r01_d01"
},
"picture": "",
"lastupdated": "2016-07-31T03:28:36",
"version": 2
},
NOTE: the scene name here is NOT Relax. It’s actually 7fwrKuV56D9cvyA. I will call that YOUR-SCENE-NAME in a moment.
To control the scene, go up to 4F above to create a Network Resource in the ISY. As before, everything is the same except the Path and the Body.
In the path field, enter:
/api/YOUR-HUE-USER-NAME/groups/###/action
NOTE: This is the same data as if you are controlling a group — which makes sense, because a scene is something WITHIN a group (so you need to tell the Hue which group you are addressing). It is only in the Body section that you specify the scene by typing this:
{"on": true, "scene": “YOUR-SCENE-NAME”}
IMPORTANT NOTE: Make sure you have the correct scene name corresponding to the correct group. What I mean by that is, every single group has a default scene called Relax. In my case, I have a Relax scene that controls Lights 1 through 6…
"7fwrKuV56D9cvyA": {
"name": "Relax",
"lights": [
"1",
"2",
"3",
"4",
"6"
…but also a Relax scene using Lights 8-9…
"rvqsYVVePr72KXh": {
"name": "Relax",
"lights": [
"8",
"9"
The first Relax scene is in Group 1. The second Relax scene is in Group 2. So you have to make sure you have the correct scene in the correct group.
That’s basically it. I have done all of this, but I haven’t necessarily gone through my own instruction set and vetted it. If ANYTHING isn’t clear, please post in the comments below and I will update the doc.
Thanks,
Steve
Oh, P.S. Special thanks to larryllix, troychasey, mwester, nridge, jkmonroe, Scottmichaelj, kohai, Brian H and I hope I didn’t leave anyone out!