Joris Kluivers

I like to build software.

Philips Hue

As of October 30th the Apple store here in Amsterdam started selling Philips Hue lights. It’s possible to dim and change the color of these LED lights using an iPhone app. I picked up a starter set (1 base station + three lights) immediately.

First thing any developer want to know of course is how to communicate with the system using your own software. I’ll document what I’ve found here.

Other resources with info on Hue:

Discovery

The Hue base station advertises itself using SSDP. This is basically a HTTP over UDP protocol. Sending a discover packet will result in an answer packet from the base station. The SSDP packets received don’t seem to uniquely identify a device as being a Hue. So for now it’s still required to make a http request for each discovered device it’s /description.xml (example) file, just in case there are more devices advertising using SSDP.

To discover devices on the network I wrote SSDPBrowser: a simple browser class in Objective-C that works on iOS and OS X.

https://bitbucket.org/kluivers/ssdp-objc

Registration

Before being able to use any of the API’s you’ll need to link your software to the base station by registering a username & device type combination.

Request

1
2
3
4
5
6

POST /api

{
  "username": "value",
  "devicetype": "Joris' iPhone 5"
}
  • username: can be any value. The official Hue application uses a (random?) md5 string here, so might be useful to do the same.
  • devicetype: Name of the client app/device

Response

1
2
3
4
5

[{
  "success": {
      "username": "value"
  }
}]

A success will echo back the username value you provided in the registration call. Use this value as the username in each API call.

For a registration to succeed you will have to press the big round button on the Hue base station. Until that time a registration call will return the following error:

1
2
3
4
5
6
7

[{
    "error": {
      "type": 101,
      "address": "",
      "description": "link button not pressed"
    }
}]

Lights

1

GET /api/[username]/lights

Response

1
2
3
4
5
6
7
8
9
10
11

{
  "1": {
      "name": "Living room"
  },
  "2": {
      "name": "Dining table",
  }
  "3": {
      "name": "Kitchen"
  }
}