Phillips’ smart light system Hue has for long been synonymous with smart IoT light bulbs, and although they recently have received competition from IKEA Trådfri and Osram Lightify (and many more), it’s still the dominant platform for smart lighting.

Basically Phillips Hue consists of the light bulbs, lamps or light strips which can be either white, white ambience or full colour, as well as the Hue Hub. In addition Phillips also sells buttons and sensors that can be used with the Hue lamps.

As the bulbs are communicating through the Zigbee protocol the Hub acts as a gateway where you, or your apps, or even smarts hubs can connect and speak with the bulbs. This is done through an API endpoint exposed by the hub.

Find the Hub and the API-endpoint

Once you get your Hue system up and running, your Hue Hub is connected to your home router over Ethernet. There are several ways of finding the hub. Given that you have access to the web interface of your router (usually found at the address 192.168.1.1 or similar), the easiest way is to find it under connected devices. Do you see a host named “Philips-hue” there? Bingo! If you don’t have access to the router, you could use nmap, arp or other funky tool to find the hub on your local network. Once you find the right IP-address you will be greeted by a page listing license information among other things .

Once you have the IP-address to the Hue Hub on your local network, let’s find the API-endpoint at http://the-ip-address/api.

For easier access to the API, you can also use the supplied debug client. It can be found at http://the-ip-address/debug/clip.html

Obtain a key

If you start running commands against the API-endpoint you will soon discover that you need to be authorized before you can do anything. To obtain such a key. Do a POST-request to /api with the following JSON-body. You will also have to click the physical button on the Hue Hub to be granted a token.

{“devicetype”:”the_hue_app#test”}

Software libraries

The API for the Philips Hue is not enormous, but using an already existing library with the API implementation in your programming language of choice saves you the hassle of creating the data-objects. Q42 has compiled a pretty good list over the available Hue libraries available. You can find the documentation of the API on Hues developer pages, but for the official documentation you will need to create a free account.

Control the lights

Depending on the library you chose (or if you have to create HTTP-clients on top of the model) you are now ready to create an application that can talk with your Philips Hue lights.