The Philips Hue is a revolutionary LED lamp which is controlled, currently, by an iOS app. Philips committed to 'open sourcing the software behind hue'... some of us didn't want to wait.
The only thing we didn't know already is that the Hue has a handy built-in debugger, the official documentation also contains some handy references for colours in the CIE colour space. There's also some information here not in the official docs.
The following is what I've discovered of the Hue hub protocol, and how it communicates with the apps. It is released for educational use only on the basis that the software is 'open source'. I do not accept any responsibility for damage to your Philips Hue products or any changes that Philips introduce. In summary, do not built a commercial product around this yet, or rely on it to control your lighting. See also my important caveats below.
If you use this information I would appreciate if you would please credit me with a link to this page (http://rsmck.co.uk/hue) in anything you produce.
My aim was to make Hue controllable by DMX - the end result can be seen in a brief video here; http://vimeo.com/52504066 - as my lighting at home is entirely controlled by a DMX system and most existing lamps are on DMX dimmers. I wanted to interface Hue with my existing system so I could use wall switches and my existing app and scheduling to control them. I also might find a use for Hue on stage in practicals...
The Hue hub communicates with your lamps using the ZigBee protocol, and with the apps (and the Hue web service) using HTTP. It appears to be a simple embedded HTTP server and as far as I can tell this is the only way of communicating with the hub.
This guide is written for people who have some experience of JSON HTTP APIs so before we begin you will need to know the IP Address of your Hub (YourHueHub below) on your internal network (you can get this from the meethue.com portal or look at arp) and how to make HTTP requests (using cURL or your favourite scripting language)
This needs to be done once, it seems older versions of the Hue bridge used an md5 hash as a 'username' but now you can use anything. Personally I'd still recommend you use a hash for some additional security.
Make an HTTP POST request of the following to http://YourHueHub/api
{"username": "YourHash", "devicetype": "YourAppName"}
If you have not pressed the button on the Hue Hub you will receive an error like this;
{"error":{"type":101,"address":"/","description":"link button not pressed"}}
Press the link button on the hub and try again and you should receive;
{"success":{"username":"YourHash"}}
The key above will be the username you sent, remember this, you'll need it in all future requests
Now that you have a username key you can get lots of useful information about the hub simply with an HTTP GET request to http://YourHueHub/api/key (where key is the username or md5 hash you set earlier)
The JSON object returned is self-explanitory so not discussed here, but it includes what all your lights are doing, the status of the hub and a few other things I've not worked out yet
You can also get the status of an individual lamp by making an HTTP GET request to http://YourHueHub/api/key/lights/1 (replace key as above, and change 1 for the lamp you want to interrogate (they start at 1)
The returned JSON object looks something like this
{
"state": {
"on": false, // true if the light is on, false if off
"bri": 240, // brightness between 0-254 (NB 0 is not off!)
"hue": 15331, // hs mode: the hue (expressed in ~deg*182) - see note below
"sat": 121, // hs mode: saturation between 0-254
"xy": [0.4448, 0.4066], // xy mode: CIE 1931 colour co-ordinates
"ct": 343, // ct mode: colour temp (expressed in mireds range 154-500)
"alert": "none", // 'select' flash the lamp once, 'lselect' repeat flash for 30s
"effect": "none", // 'colorloop' makes Hue cycle through colours
"colormode": "ct", // the current colour mode (see above)
"reachable": true // whether or not the lamp can be seen by the hub
},
"type": "Extended color light", // type of lamp (all "Extended colour light" for now)
"name": "Hue Lamp 1", // the name as set through the web UI or app
"modelid": "LCT001", // the model number of the lamp (all are LCT001)
"swversion": "65003148", // the software version of the lamp
"pointsymbol": { } // not sure what this does yet
}
}
Almost certainly this is why you're here - you want to be able to control your lamps from a script, your home automation system, or something obscure like siri or even DMX just because you can)
You can command a lamp with an HTTP PUT request to http://YourHueHub/api/key/lights/1/state (replace the lamp number and key as before)
The command should be a JSON object with only the attributes you want to change e.g.
{"bri": 254, "on": true} // turn lamp on at full brightness
{"hue": 25000, "sat": 254} // hue 125°, saturation 100%
{"ct": 500, "bri": 254} // warm white, full brightness
The hub will return a JSON object which confirms whether your change was successful
There are three distinct colour modes;
The current colourmode is returned when you query the lamp, it changes automatically when you send the parameters corresponding to the mode you wish to use. e.g. if you send a 'ct' value the colormode will change to 'ct' although the hue,sat and xy parameters will NOT change to reflect this.
There are other functions available which I'm sure do a lot more than what I've found so far...
Thanks to Michael Herf @herf for making me aware of the rate limiting that appears to be enforced by the hub. From some (fairly limited) initial testing rate limiting seems to take effect as follows;
| Queries | Time |
|---|---|
| 38 | 0.2s |
| 62 | 1.02s |
| 80 | 1.6s |
| 92 | 2s |
There is no rate limiting at around 30 updates per second
Annoyingly these limits are per query not per query per lamp and as it is only possible to change one lamp at a time it greatly limts the ability to make groups of lights change at the same time.
To put it in perspective DMX (a common architectual and enterainment lighting protocol) is 44 frames per second, and that's for 512 channels of control (or 170 RGB lamps) - this is necessary for smooth dimming
At 30 updates per second it's perfectly possible to smoothly control ONE hue lamp, but not entire groups of them.
The Philips Hue is a unique product and behaves quite differently from other LED lights you may have used. It's important to remember these few caveats and also that these compromises were made to provide a product thats ideally suited to the market that it's aimed at, not us who're trying to use it in more unusual ways;
Most of the original caveats here have been worked around, described above so I leave you with..
There is an unofficial user-to-user support forum for Hue users and developers at everyhue.com created by one of the Hue designers where you can share your own discoveries and Hue projects.
I'm a developer who has a background in lighting design and entertainment lighting. Or a lighting designer and technician who has a background in software development, either way I play with code and paint stages and buildings with light.
I've been involved in some other unusual architectual projects like SMS text-message controlled lighting for a business telecoms and messaging provider and developed my own DMX-based architectual lighting control system to provide the flexibility of a full lighting controller, initially at home, without the expense associated with professional systems.
The Philips Hue brings that sort of technology to everyone - and anything that gives people better light and more opportunities to be creative with light is a good thing
If you have any questions or are planning a project with Hue eMail me at ross@rmlx.co.uk
