Controlling the Hue smart lights

Philips Hue light bulbs set to different colors and low brightness
Philips Hue light bulbs set to different colors and low brightness

In 2012, Philips introduced a lighting system called Philips Hue. The system exists of a series of so-called smart LED light bulbs in different forms. What is special with these bulbs is that one controls them wirelessly, in terms of brightness, color temperature and color.

The bulbs create and extend their own (Zigbee) wireless network which is independent from any established WiFi networks. A bridge connects the wireless ‘bulb network’ with the regular WiFi network.

On the software side, Philips provides its own smart phone app for setting up and controlling the bulbs. At the same time Philips enables external developers for creating more advanced effects. For this Philips provides an Application Programming Interface (API) that is available for anyone to use.

This resulted in loads of apps for controlling the Hue lights on various platforms. Some are more fun-oriented, like synchronizing light effects with music. Others are more serious, like adjusting the lights dynamically according to sleep patterns during the late evening and early morning.

My question is then, how can we control the lights ourselves?

First, a shopping list: only one item is needed besides a computer (or tablet/smartphone) and that is a Philips Hue White And Color Ambiance Starter Kit. This is not quite the cheapest starter kit, but it is the variant that has the most possibilities, i.e. can adjust color. If you’re not interested in that, cheaper variants can be found.

The starter kit contains 3 color light bulbs and a bridge. The bridge has to be connected with a network cable (included) to the Wifi base station so it is accessible from your computer. A power supply for the bridge is also included, but obviously no lamps that can hold and power the E27 light bulbs. So if you don’t have those around, you’ll have to buy a three simple E27 sockets as well.

After installing the bridge and the light bulbs (make sure they are powered), the Hue app needs to be downloaded to be able to control the lights. (Don’t use a power switch, the lights shall always be powered.) The Hue app will find the bridge, let you configure rooms and assign light bulbs to the rooms and let you choose lighting effects for the rooms. As well as switching on and off, of course.

Feel free to download additional apps to explore various possibilities with your Hue setup. A recurring theme is that for each new app, you’ll have to press the big button on the bridge to pair the app with your bridge.

In the settings section of the app, you will find the IP address of the bridge in your network. You will need that for accessing the bridge from your computer.

IP address of the bridge in the Hue app
IP address of the bridge in the Hue app

Now that we have the IP address of the bridge, let’s see how we can communicate with it. This is surprisingly easy, since the Application Programming Interface (API) is implemented as a web service. This means that we can simply open a browser and enter its IP address in the address bar. You will be greeted with an introduction screen and a lot of license information.

If you enter the IP address followed by /debug/clip.html. (In my case:, the bridge will present an API Debug Tool that lets you enter REST commands to the bridge and it shows the response from the bridge. The body of the command messages and the responses are in the JSON format.

API Debug Tool
API Debug Tool

The first thing we’ll need to do is get access to the bridge, is get a key. First press the button on the bridge, after which we enter /api in the URL bar and {“devicetype”:”ABC”} in the message body and press POST. The response will include the magic word “success” and we can isolate the key. In the future, we can always use this key for further experiments. No need to repeat this step.

Now let’s query the lights that we have in the system. We do that by entering:

/api/(the key that we received)/lights

in the URL bar and pressing GET. We’ll get a detailed report of all three lights in the system, from color and brightness values to the software version.

Status of lights
Status of lights

Entering /api/(the key that we received)/lights/4 will give the status of only light number 4 only.

Last but not least, we want to change the state of a light. Enter:

/api/(the key that we received)/lights/4/state

in the URL and the parameters we wish to change with the new values in the body. For example:

{“on”:true, “sat”:255, “bri”:1,”hue”:50000}

In the response, we’ll get a success report for each update that was successful and an error for each update that was incorrect. Of course you will want to check the light that it adjusted in color and brightness.

Setting a light
Setting a light

Now we can use this tool to play with the different parameters and values we can set. Also, we can change the colors visually using the Hue app and simply query the current value of the lights. Then we including these GET and PUT commands into scripts to create more complex effects: automatically changing colors or blinking/pulsing, either continually or as a reaction on certain events.