Control Philips Hue Lights

Controlling Philips HUE Lights with Raspberry PI


Philips HUE is a domestic line of Wi-Fi-enabled color changing LED lamps. It was first introduced in October 2012 and has been updated both in 2015 and 2016, so one can say that it is a mature product. Of all the alternatives, and despite its price (15/20 € pro bulb), I think that HUE is the best smart lightning system. In this tutorial I will explain how to integrate HUE lights in your own domotic system/web server using acceding Philip’s API through cURL.

How HUE Works?

The Hue lighting system is based on a central node, the Hue Bridge, which is connected to the router through a LAN cable. The Bridge communicates with the bulbs using Zigbee Light Link standard (and Zigbee 3.0, a recent update released in 2018). The Bridge implements a very good documented REST API (access requires login) though port 80. The HUE can be configured to be accessible from outside the local LAN, however due to previous security issues with HUE products, I decided to disable this functionality. By this way, only devices inside the local network will be able to control my home lights.

Philips HUE Bridge

To tell the true, in order to control your HUE lights, the Bridge is not 100% needed. You can access directly the bulbs sending RF Zigbee signals from a Raspberry Pi compatible module. However I think that the (approximately) 50 € that the Bridge costs is a reasonable price that will avoid headaches trying to hack the only partially documented protocol used internally by the Bridge.

Find HUE Bridge IP

In order to be able to talk with the Bridge, you will first have to find which IP the router has assigned to it. There are a number of ways of doing this as described in this link. The easiest way is, from my point of view, to use the Bridge’s mDNS capabilities. First of all, you will need to install a service discover client. I have used avahi package. Once installed, use it to find the IP announced by the Bridge’ service:

Note: This should work if your Bridge version is 2.0 (the square one).

As you can see, the Bridge announces its services twice, using IPv4 and IPv6. Write down the IP. I would recommend you assigning a static IP to the Bridge. In this post I explained how to do that in an EasyBox 904 xDSL router. Other devices will probably need different (although similar) steps. In all cases you will probably need your Bridge’s MAC. To figure it out just type:

Get a valid user

REST APIs are stateless. It means that the response from the server is independent of any sort of state (and of any previous request). However, to start talking with the HUE you will first need a valid user that authorizes the use of the API. This valid user is generated by pressing the Bridge’s physical button and then posting a request with the following content (replace YOUR_USER_ID by any identifier that you want, it will not be used anymore):

Write down the username generated by your Bridge, you will have to authenticate each request with it. Let’s do a short trial. Send the following command to obtain the list of available bulbs, as well as their current status:

Copy and paste the response received in a JSON Parser to read it in a more comfortable way. You should obtain a numbered list of lights. If you have previously named your bulbs (using Android or iPhone HUE App), you will find this information in the list of attributes returned. Identify now each light with the number assigned by the Bridge. You will have to use this number as the bulb’s identifier.

Controlling lights

Once you know your light’s ID, let’s see how to manipulate them. The simplest scenario is to turn on a light. To do so, just send the following web request. If everything works fine you should receive a response containing a confirmation of the arguments passed in and, of course, the light will turn on.

Depending on the type of bulb, you can also control other parameters. You can find which are configurable by looking at the state attribute of the light. For instance, you can control only bright and color temperature in A19 White bulbs, while you can also define the saturation and the exact color of the light in the color ambience models.

Defining the color of a light bulb is a little bit more complicated than just turning it on. The color point of a light has lots of ways of being quantified. HUE accepts a couple of them, being the most complete the use of x/y coordinates of the color in the CIE color space. The following image shows the chromaticity diagram of CIE color space. The three triangles (gamut A, B and C) outline the colours which hue can address depending on the bulb used. Have a look at this link to find out your light’s gamut.

CIE 1931 Color Space

If you locate the coordinates [0.7, 0.3] you will see red color. To change the color of a light to this tone of red, send the following request:

Beside individual lights, groups of bulbs can also be controlled. First of all, the elements that belong to the group should be defined. It can be done sending requests (have a look at the API documentation) or, much easier, using HUE’s App. To turn on a group of lights with blue color, send the following request:

A Web interface to control you lights

Control Philips Hue Lights

I have integrated in my domotic web page a simple form that allows me control the HUE lights remotely. The form integrates the 433 MHz remote switches explained in this post too. I have followed Bootstrap framework (HTML5 and Javascript with AJAX requests) and PHP in the server side. By doing so, the Raspberry Pi receives commands and serves them using PHP and the libcurl library. I have used Bootstrap Swtich and Boostrap Color Picker libraries to create nice buttons.

This is a simple example to manage a light group with both color and bright controls. The HTML code is as follows:

The following javascript will send an AJAX request to a PHP Wrapper named HUEWrapper.php . The method sendToHue() creates an XMLHttpRequest object to interact with the server. The request’s URL query string will contain three parameters: the operation to be performed, the light status desired, the light bright and the light color. Similarly, the method getFromHue() will get the current status of the light.

Finally, the server will contain a PHP file that, using HUE’s API, modifies the bulb status. A couple of functions that will convert the color from hexadecimal format to x/y coordinates in the CIE colour space can be found in the code.


Leave a Comment