What is Philips Hue

Philips Hue is smart lightning, allowing you to control the lights from either a smartphone via an app or via the additional accesoires like physical remotes or sensor detectors. The Hue system works via ZigBee protocol, a lightweight 2.4 GHZ frequency protocol. The system also integrates well with a Homie, according to the internet.

Using the Hue API

Getting the API key

Philips has not just created a nice smart lightning product, they also opened the API for developers. You can retrieve the API key from the central control unit, which runs a webserver. For a comprehensive guide, see the official documentation. The short version is:

Make a POST request with the required data with curl:

curl --insecure --data {"devicetype":"my_hue_app#mylaptop"} -X POST https://<hue bridge ip address>/api

You will be prompted to press the button on the Hue bridge, as proof that you have physical access to it (and therefore hopefully the (house)owner). Once you pressed it, perform the curl command again.

You should now receive a response stating “success” and a username. This username is the API key which you’ll need for the communication with your bridge and Hue devices.

Using the API key

The API uses a URL convention to reach specific levels of the available devices. For instance, if you want to get an overview of all the lights, you can execute the curl command below. The pipe to Python is optional, this will print the returned JSON “beautified”.
curl --insecure -X GET https://<bridge ip address>/api/<your retrieved api key>/lights | python -m 'json.tool'

If you want to get the details of a specific light, execute: curl --insecure -X GET https://<bridge ip address>/api/<your retrieved api key>/lights/<number of light> | python -m 'json.tool'

Use cases

So what fun and use can we find for this new obtained superpower? For starters, you can use the API URL in Apple Shortcuts to check out the brightness or temperature in other rooms and if that is above or below a certain level, take steps (automated or manually). Below an example where I check the brightness levels in a room and send them via iMessages to myself.

Another use case can be to monitor the temperature of your home every hour to monitor the time it takes for the heater to warm up your house and how temperature outside affects this. Running a script on a cron schedule makes this easy to do.

The last example is based on the time the sun goes down. You incrementally increase the light brightness and color to your liking and turn all the lights off when you are in bed and forgot to turn the lights off.

Some of this is also possible with integrations of Apple Homekit and within the Hue app itself of course. But it’s also fun to do something yourself every now and then ;)

Docker image

To make it easy to start, I’ve created a simple Go program that takes the IP address, API key and light or sensor to read out. The docker image can be pulled from Docker Hub:

docker pull statixs/hue-control:latest

Or clone the project from GitHub.

The program can do three tasks:

• Show light information (name, on/off and reachable yes/no)
• Show sensor information (name, temperature and brightness level)
• Show raw JSON response, for discovery of your devices and further developing

To run HueControl, start a container with the following parameters. In this case get the details on the lightbulb with ID 4

docker run --rm statixs/hue-control -ip <YOUR_HUE_IPADDR> -key <YOURAPIKEY> -lid 4

response:
Name: Example lamp of room example suite - On: false - Reachable: true

For sensor information, you can run this

docker run --rm statixs/hue-control -ip <YOUR_HUE_IPADDR> -key <YOURAPIKEY> -sid 5

Or get the raw JSON for debug and further development

docker run --rm statixs/hue-control -ip <YOUR_HUE_IPADDR> -key <YOURAPIKEY> -raw | python -m 'json.tool' # last part is to pretty print the JSON

Closing remarks

Talking to the Philips Hue device is easier than it seems and opens the door to many automations with possibilities for Apple Shortcuts and your own scripting skills. Enjoy the new superpower!