Controlling a Philips Hue

First off, the Philips Hue bridge exposes a web server, so take a look at the wireless connections on your network (see also How to develop for Hue) for other methods of locating your Hue bridge on the network.

Much of the information in this post is taken from How to develop for Hue?. More information is available if you register as a Philips Hue developer.

Once you’ve located your bridge IP address you can use a web browser to connect the CLIP API Debugger, i.e.

https://<bridge ip address>/debug/clip.html

The Hue bridge API

The first thing we need to do is a key for interacting with the device. The Hue actually calls this your username and it’s a randomly generated string, once we have this we have an authorise user.

So for example if you try to use any command without a key you’ll get a response along the following lines

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

Creating our user

To get our username and thus create an authorized user, we use the following API

  • Method: POST
  • Url: /api
  • Body: {“devicetype”:”my_hue_app#my_name”}

The “my_hue_app#my_name” appears to simply be a unique resource name. Before you run this command you should press the link button on the Hue bridge then execute this HTTP request.

If all works correctly you should get a response like this

[
  {
    "success": {
      "username": "sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12"
    }
  }
]

Now we use the username value (i.e. sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12) in our method calls going forward.

Getting more information

  • Method: GET
  • Url: /api/sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12

This will return a JSON response (which it too large to include here) including information on the available lights, their state, brightness, hue etc. along with stored scenes.

Getting light information

  • Method: GET
  • Url: https:///api/sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12/lights

If successful, this will return light specific information, such as state, name, brightness etc.

Getting light information for a specific light

If we want to just get information for a specific light, we use it’s ID, by simply appending it the the previous URL, for example we’ll get information for light 1

  • Method: GET
  • Url: https:///api/sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12/lights/1

Turning a light on and off

To change the state of a light we append state to the previous URL, for example

  • Method: PUT
  • Url: https:///api/sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12/lights/1/state
  • Body: {“on”:false}

We should get a response similar to the one below

[
  {
    "success": {
      "/lights/1/state/on": false
    }
  }
]

More than just on and off

  • Method: PUT
  • Url: https:///api/sYA1egf8VZteeIWnXmlIdrxFE3uHgUr-jk2Vrt12/lights/1/state
  • Body: {“on”:true, “sat”:254, “bri”:254,”hue”:10000}

After executing this, you’ll get a response similar to the following

[
  {
    "success": {
      "/lights/2/state/on": true
    }
  },
  {
    "success": {
      "/lights/2/state/hue": 10000
    }
  },
  {
    "success": {
      "/lights/2/state/sat": 254
    }
  },
  {
    "success": {
      "/lights/2/state/bri": 254
    }
  }
]

C#/.NET Libraries

There are also several .NET libraries for interacting with the Hue, that allows us a better API experience, such as

  • https://github.com/Q42/Q42.HueApi
  • https://github.com/cDima/Hue
  • https://github.com/qJake/SharpHue

References

Become a Philips Hue Developer to light up your ideas