Control Philips Hue with Raspberry Pi

This tutorial will teach you how to control your Philips Hue appliances with a Raspberry Pi and Spring boot. This comes handy if you have more things you would like to control, not just Phillips Hue products. You can create your own software to control them all, however this tutorial will only teach you how to interact with Phillips Hue products.

Requirements

This tutorial requires you to have a Raspberry Pi setup with Raspbian as an operating system. If you have not done this yet please have a look at this tutorial. Prerequisites for this tutorial are also Java tutorial and Spring boot tutorial.

Tutorial

The Philips Hue bridge has an interface which you use when interacting with the bridge and you can find the documentation here. (You do need to register/login to access the API documentation)

The first thing that you need to do when interacting with the Philips Hue bridge is to find out on what ip address your Hue Bridge is located on. Philips has made this step simple for you by creating a website you can use, all you need to do is to visit this website while on your local wifi network.

[{"id":"001788fffea644ad","internalipaddress":"192.168.0.31"}]

In my case the ip address is “192.168.0.31”, but this will be different for everyone.

The interaction with the bridge is with REST and I will be using the command tool curl. You can find more information about Curl here. There are a lot of tools which you can use e.g. Postman or SoapUI.

When you now have the address to the bridge we can now continue with creating a user in the bridge by using the endpoint “/api/newdeveloper” in the Philips Hue Bridge.

# curl -X GET 192.168.0.31/api/newdeveloper

Oops the response you will get is something like this

[
    {
        "error": {
            "type": 1,
            "address": "/",
            "description": "unauthorized user"
        }
    }
]

This is the security provided by Philips to make sure only authorized users can access your Philips Hue and your smart products. What we need to do is to create a user using the “/api” endpoint by typing this command. But before we do this, you need to press the button on the bridge once, otherwise you will get an error response.

# curl -X POST 192.168.0.31/api -d '{"devicetype":"rpi_app#superman"}' -H 'Content-Type: application/json'

With the button pressed and chosen a good app name and a user name you will get a response like this. I chose “rpi_app” as an app name and “superman” as a user name.

[{"success":{"username":"AjfksdfEfDfsdvdFfdgRSGvsd"}}]

This username is important therefor do not loose it otherwise you will have to do this step again. It is used in all interactions with the Philips Hue Bridge.

Get information about all the lights.

To get information about all the lights on your Philips Hue network use the following command:

#  curl -X GET https://<bridge ip address>/api/<username>/lights
e.g. https://192.168.32.2/api/AjfksdfEfDfsdvdFfdgRSGvsd/lights

The response will look similar to this.

{
  "1": {
    "state": {
      "on": true,
      "bri": 254,
      "alert": "select",
      "mode": "homeautomation",
      "reachable": false
    },
    "swupdate": {
      "state": "noupdates",
      "lastinstall": "2019-09-27T12:20:51"
    },
    "type": "Dimmable light",
    "name": "Lamp",
    "modelid": "LWB010",
    "manufacturername": "Philips",
    "productname": "Hue white lamp",
    "capabilities": {
      "certified": true,
      "control": {
        "mindimlevel": 2000,
        "maxlumen": 806
      },
      "streaming": {
        "renderer": false,
        "proxy": false
      }
    },
    "config": {
      "archetype": "classicbulb",
      "function": "functional",
      "direction": "omnidirectional",
      "startup": {
        "mode": "safety",
        "configured": true
      }
    },
    "swversion": "1.46.13_r26312",
  }
}

Get information about a specific light

To get information about a specific light one use a similar endpoint, but with an id.

#  curl -X GET https://<ip address>/api/<username>/lights/<light-id>
(e.g. https://192.168.32.2/api/AjfksdfEfDfsdvdFfdgRSGvsd/lights/1)

The response will look similar to this.

{
  "state": {
    "on": true,
    "bri": 254,
    "alert": "select",
    "mode": "homeautomation",
    "reachable": false
  },
  "swupdate": {
    "state": "noupdates",
    "lastinstall": "2019-09-27T12:20:51"
  },
  "type": "Dimmable light",
  "name": "Lamp",
  "modelid": "LWB010",
  "manufacturername": "Philips",
  "productname": "Hue white lamp",
  "capabilities": {
    "certified": true,
    "control": {
      "mindimlevel": 2000,
      "maxlumen": 806
    },
    "streaming": {
      "renderer": false,
      "proxy": false
    }
  },
  "config": {
    "archetype": "classicbulb",
    "function": "functional",
    "direction": "omnidirectional",
    "startup": {
      "mode": "safety",
      "configured": true
    }
  }
}

The field that we are interested in is the “state” field, this field tells us if the light is on or not. To change this field we need to request a change to the Philips Hue bridge. We do this by send a PUT request with a body to the Philips Hue Bridge. The Body should be in a json format and it should define if the light should be on or not. (true or false)

# curl http://<bridge ip address>/api/<username>/lights/<light id>/state -X PUT --header "Content-Type: application/json" --data '{ "on": true }'

So far all the commands shown has been in a curl format. But this is just one way to control the Philips Hue bridge. One can also use Spring boot to do this and it could look like this.

These code blocks are from an example application I created to show you how to use Spring boot and React to control Philips Hue lights. You can find the source code for this application here.

Conclusion

This tutorial teaches you how to control Philips Hue lights with your Raspberry Pi. With this tool in your toolbox you can now build your own application and control the lights however you want. Maybe read more about the Phillips Hue API and include a motion sensor in your application?