Controlling your Hue Lights via API

If you follow my blog, you know that a lot of my projects involve changing the color of Hue lights in response to…ahem…”events”. For example my Sidereal Pipe Light that changes color when your psychic ability is the most powerful! I use the Philips lights API for this and I prefer programming in Python.

In this post, I’m going to step through a quick primer of how you can use Python with your projects to change the color of your lights.

The first step is to get familiar with the API and how it works. Philips has some great documentation here. We’ll be using the Lights API, and for the most part this post will be following this tutorial.

Next step is that you need to know the IP address of your bridge – that’s the device that the lights communicate with and the destination that you will be sending commands.

The bridge is the square device with the blue ring to the right. As of this writing there are two versions of the bridge. My setup is the older version which is round instead of square.

Philips Hue Bulbs and Bridge

The easiest way to find the IP is to lookup the address using your wifi router. The tutorial provides a good writeup on how this is done.

Once you have the bridge IP you can interact with it directly by pointing your browser to the built in API debugger url: https://<IP address>://debug/clip.html

The debugger should look like the below.

Once you can access the debugger you will need to create a username to send commands to the bridge. The username is more akin to a password – you use if for authentication whenever you need to send an API command.

Here’s what to specify when using the debugger to create a username:

URL: /api
BODY: {"devicetype":"<application_name>#<devicename>"}
METHOD: POST

Creating a username is detailed in the Configuration API documentation. What to use for the “application_name” and the “devicename” is a bit mysterious and not entirely explained. There’s a note in the docs saying that Philips would prefer that “published apps use the name of their app as the devicetype”, but there’s no mention of what the application_name should be.

The doc example uses {“devicetype”:”my_hue_app#iphone peter”}, so use that as a guide.

Update the URL and Body in the clip debugger and then select “Post”. If you’ve done everything right, you should get an output in the command response that tells you to press on the link button on the bridge. When you press the button again and you should see output that looks like the below.

The string with the numbers and letters is your username and you’ll use this going forward for authentication whenever you send API commands.

The Lights API details the all different commands you can send to control your Hue bulb, for the remainder of this post, I’ll describe how to change the color using Python.

One of the first things I discovered when working with the API is that assigning specific colors to the lights is more complicated than it might seem.

There are many ways to represent a color space and quantify a color point of light. Philips uses the CIE color space to represent the available colors of hub bulbs. See my post on how to select a color and what parameters to use when changing the color values.

Now that you know how to send commands to the bridge, have a valid username for authentication, and know the color parameters that you would like to use, the next step is to wrap it all up in a super easy python script that you can run from anywhere (perhaps a raspberry pi) to change the color of your lights.

CIE Color Space

My python script is literally an eight line hack. I’m using Python 2.7 with the urllib2 library. Note: If you’re using Python3 you might need to adapt the import. Here’s my code:

#!/usr/bin/python

import urllib2

url = 'http://192.168.1.33/api/T7TxxqrFVO8jv-gkwKmyQhtcVNGSTjGkJ0XENWg-/lights/12/state'

payload = '{"xy":[0.5015,0.3530]}'

opener = urllib2.build_opener(urllib2.HTTPHandler)
request = urllib2.Request(url, data=payload)
request.get_method = lambda: 'PUT'
url = opener.open(request)

The url variable is the IP address of my bridge along with the “username” that I use for authentication. I’m specifying that I would like to change the state of light #12.

If you have multiple Hue lights, you can determine the # of the light that you would like to update by specifying /api/<username>/lights in the clip debugger URL and clicking on “GET”. This will return info about every light connected to the bridge.

In the “payload” I’m specifying an “xy” value for the color I would like. In this case, “lightsalmon”. Again, see my post on selecting color values if this doesn’t make a lot of sense.

The rest of the script constructs the url and then submits it using the “PUT” method.

And that’s it! If you run this from the command line you should see your light change color. I wrote this for linux, but should work in Windows as well if you replace the path to Python on the first line.

Hopefully you found this post useful. I’d be very grateful if you’d help it spread the word by emailing it to a friend, or sharing on Twitter or Facebook. Thank you!

Which Pi am I?

Typically all of my projects are built with single board computers.

I typically use Arduinos, BeagleBones or Raspberry Pis depending on the specific use case.

If you’re like me and have been doing this for a while, you probably have several versions of the pi laying around, and it’s not always immediately obvious which version you’re holding.

This is important for things like understanding CPU and memory specs, pinouts and available peripheral ports.

Here’s a great site that has a table of all available models and makes it really easy to identify a board.

Because sharing is caring.

If you have access to a shell you can also find your Pi version by issuing a cat to /proc/cpuinfo:

Find the Revision number (second field from the bottom) and then compare to the table below.

Can’t find your Pi? Check here for the most up-to-date listing.

Engineering Notes

When I build things I like to document the engineering end. These are tips and tricks or links to hardware or coding documentation somewhere. These posts are not presented in any particular order, I’ll probably use as a reference to save time in the future. I hope you find them useful.