A Day with Philips Hue

I got a Philips Hue on the first day it was available at the Apple Store and had f.lux running 3 hours later. Here are my notes.

Some notes about Hue in general:
  1. Color is great, whites look good
  2. Bulbs are efficient (8.5W)
  3. Brightness is good, useful as a regular bulb.
Negatives:
  1. The controller rate-limits updates from the software. So if you wire up a slider to send messages at 10fps, it won't work. You can send 2-3 messages per second, and then it does some interpolation on its own, which might not give the "look" you want.
  2. Powering down a bulb (like with a lightswitch) and restarting loses all the bulb's state! Depends on a client to restore it. The controller bridge really should do this automatically.
  3. Range isn't so great -- Zigbee loses to my DECT phones and baby monitor and wireless network. So you really need a "mesh" of nodes, not two bulbs 50 feet away.
  4. Minor: Bulbs have a front-facing distribution (put out less light to the side and back than the L-Prize bulb.)
Here are some notes about the interface to the Hue controller (I didn't look into the Zigbee side, just sniffed the iOS client.)

Discovery

Hue uses SSDP (like Roku and Sonos do). So, discovery is pretty standard. You can also walk your class-C network and look for a webserver responding to /description.xml, which is cheating (but it works.)

Authentication

Hue relies on client-generated secrets. Each client generates a secret (likely one of the device unique identifiers), and then uses that to talk to the hub.

So you'll see an http request like this:

GET /api/{secret}/lights HTTP/1.1

And the switch will respond "unauthorized user." The client will then start polling to make a user:

POST /api
{"username": "{secret}", "devicetype":"{name}"}

And Hue will respond (in JSON):
"link button not pressed"

Once the button is pressed:
"success"

Basic Controller

The current iOS client appears to poll /api/{secret} once per second, which gives the whole dump of settings. Most of these seem writable.

To change a light you do a PUT to /api/{secret}/lights/#/state (not POST).

(where # is a number you found from the main lights feed. On the default kit you'll have lights 1-3 available.)

Contents are JSON! For single brightness and color settings (not groups or scenes) you might see something like this:

{"bri": 128, "ct": 200, "on": true}

Brightness appears to go to 255, color temperature is 500 to 154 (which corresponds roughly to 2100K to 5800K, somewhat nonlinear.)

Or you can send xy coordinates to control the bulb in color (use your handy sRGB to XYZ matrix):

{"bri": 255, "xy":[0.4, 0.4], "on": true}

You must rate limit your client in the range of 2-3 updates per second, or the hub will send you a 503 and throw away your changes. It appears to be "worth it" to stay in this range, or the rate limits get a little more severe.

Advanced Controller [TBD]

The software has the ability to define groups and scenes. Have not investigated yet.


17 comments:

  1. What do you mean by f.lux?

    ReplyDelete
  2. thanks - updated to include a link. f.lux is our software to adjust color temperature of a display by time of day. turns out you can do the same with home lighting. :)

    ReplyDelete
  3. Enjoyed this post, Michael. I'm backing a similar project on KickStarter at the moment, but bought a Hue at an Apple Store on my way to the airport yesterday. In my rush, I realise I bought just a bulb and not the bridge/station!

    Do you think it's possible to hack the bulb to have it talk to my router without Philips' bridge?

    ReplyDelete
  4. WIll -- interesting idea. I suspect controlling the bulbs separately is possible, but you would need more hardware to talk on the Zigbee network (a Zigbee Light Link controller of some sort.)

    I was wondering if this would happen to people, since my local store is out of the kits too, and only has the bulbs.

    ReplyDelete
  5. This is really great. I picked up a set of these todays and am really impressed.

    I've been trying to get this working and am having problems creating the new user. When I attempt to POST the JSON to /api I get an error response (type: 2) saying that "body contains invalid json".

    Do you have any ideas why this might be? Is it possible the URL or params are incorrect here?

    (I realize you're not tech support for Hue, but I thought I'd at least ask since you know more than anyone else at this point ).

    ReplyDelete
  6. Never mind.

    My problem was submitting the data as form data instead of the request body. Once I solved that, I was able to be authorized.

    Thanks again.

    ReplyDelete
  7. Thank you for taking the time to figure out the protocol. I got my Hue this weekend, and found your page this afternoon. At home I was able to write a script in python to pulse the lights, the first step in some fun ambient notification and home automation ideas I have.

    https://gist.github.com/4022368

    ReplyDelete
  8. Hi. I’ve created a google group for discussions related to Hue hacking. My hope is that we’ll manage to gather all known information about the Hue in a known location, so information isn’t as scattered as it is now.

    Please check it out: https://groups.google.com/d/forum/hue-hackers

    ReplyDelete
  9. Anonymous7:09 AM

    Anyone know how to unpair these bulbs? I have some that are paired with bridge #1, but I'd like to pair them with bridge #2 but seems they are now undiscoverable.

    ReplyDelete
    Replies
    1. Help, need too

      Delete
    2. Anonymous6:42 AM

      Philips support told me that the single pack bulbs could be unpaired by pressing the factory reset button on the bridge but I haven't been able to get this to work.

      Delete
  10. You can pair bulbs from bridge #1 to bridge #2. It's tricky but it works.
    All you need is a philips living colors remote. With this you can reset the zigbee settings from the bridge. After that you learn the bulbs to the living color remote and then you copy the settings to the bridge.

    Philips give this steps::

    Reset the remote control to factory defaults: remove the back cover of the remote control and insert and hold a paperclip in the little reset hole inside the remote (remove back cover) until you hear a beep.
    Add each LivingColors lamp and hue lamp to the remote control: bring the remote close to the lamp, then press and hold the "I" button. The lamp will flash 3 times. Hold the "I" button until you hear a beep from the remote; the lamp will shortly flash in green. It is now connected to the remote Control and will turn to its last "on" setting. Check if all the lamps can be controlled using the remote control.
    Reset the hue bridge to factory defaults and clear the Zigbee network settings: press the link button on top the bridge and bring the remote close to the bridge, then press and hold the "I" and "Scene 1" (.) button on the remote control until LEDs on bridge start blinking and the middle LED turns off.
    Copy the Zigbee network settings to the bridge: bring the remote close to the bridge, then press and hold the "I" button. The LEDs on the bridge start blinking. Hold the "I" button until you hear a beep from the remote; The middle LED lights up on the bridge.
    Start the app and follow instructions.

    ReplyDelete
  11. Anonymous7:58 PM

    Yeah perfect, just seems little tough to find this remote...

    ReplyDelete
  12. http://www.HueDotNet.com

    Check this link out guys! :)

    ReplyDelete
  13. Hi, i bought the hue pack, but I am not being able to connect to the bridge nor the bulbs to the bridge. It seems like an Unauthorized access. Any ideas?

    ReplyDelete
  14. Hey all,
    I was trying to figure this out too, and saw this page first. I kept looking and found an easy solution to pair the lights from two bridges to a single bridge. It is the first post from here:

    http://www.everyhue.com/vanilla/discussion/comment/641#Comment_641

    I downloaded the simple software from this discussion and was able to successfully pair 4 bulbs from a second bridge onto the first bridge. Now all the lights are on a single bridge and I unplugged the second bridge.

    Good luck. :)

    -- Matthew

    ReplyDelete
  15. I guess a lot's happened since the original post, but for anyone like me who happens across it while Googling, the API is now documented at http://developers.meethue.com/ and there's a handy debug tool that lets you simply type your json.

    On the pairing issue, I was recently stuck after having to replace my bridge. The lamps were obviously paired with the old one. Lampstealer did the trick for me, but was a bit clunky (The app didn't find my bridge at first, I had to use the jar version). The 'Touchlink' command doesn't seem to be part of the API, but I did find this handy trick which you can work through the command line: http://nohats.ca/wordpress/blog/2013/05/26/philips-hue-alternative-for-lamp-stealer/ And for an easier ride for mac users, I've built the Touchlink command into the next version of my app Hue-topia (v1.6, out shortly)

    ReplyDelete