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.


Update April 2015: This information is now very out of date, please see the Official Documentation
Update March 2013: 6 months on and Philips have finally released the Official API documentation.

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.

Why did I do this?

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...

Talking with The Hue Hub

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)

Registering your Application

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

Interrogating the Hub

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

Querying a Lamp

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
    }
}

Controlling Lamps

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

The Colour Modes

There are three distinct colour modes;

hue
The parameters 'hue' and 'sat' are used to set the colour
The 'hue' parameter has the range 0-65535 so represents approximately 182*degrees (technically 182.04 but the difference is imperceptible) - Thanks Aaron!
xy
The colour is expressed as an array of co-ordinates in CIE 1931 space
(approximately, see note below)
ct
The colour temperature (white only) 154 is the coolest, 500 is the warmest
Thanks to Nathan for observing that this appears to be measured in Mireds, equivilent to 1000000/T (where T is the temperature in Kelvin) corresponding to around 6500K (154) to 2000K (500)

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.

Other functions

There are other functions available which I'm sure do a lot more than what I've found so far...

alert
'select' will flash the lamp once
'lselect' will flash the lamp repeatedly
effect
'colorloop' will cycle through all colours Hue can produce, 'none' is no effect.
transitiontime
If specified (in 1/10s), will cause the light to change over the time set
If set to '0' will result in a 'snap' and bypass the usual soft fade

Rate Limit

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;

QueriesTime
380.2s
621.02s
801.6s
922s

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.

Some Caveats or "Why can't it do.....?"

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..

It's not RGB
What's that I hear you say? Of course it's RGB... Well it is and it isn't.
The sources within a Hue are not primary Red, Green and Blue as are used in other LED lighting products; The Red is a touch more 'orange', the Green is closer to a 'lime-green' and the Blue is closer to Violet. They remind me of the intermediate colours in the ETC Selador x7 colour system.

Why did Philips do this? Simple - it enables the Hue to produce much nicer whites (at any colour temperature) than a normal RGB fixture and also much nicer pastel shades, which are likely to be the most common use of Hue.

The problem (from our point of view) is you can't easily map RGB colours to Hue, nor can you mix them with other LED fixtures and expect the same results. It's also why the CIE 1931 co-ordinates don't work exactly as you might expect.
 

everyhue.com

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.

About Me

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


LinkedIn Twitter

Get in touch