Operating your Hue remotely using Hue Remote API – a working Proof of Concept

Introduction

To operate your Hue system on local network you can send REST based messages like described in the Philips hue API to your Hue bridge. However if you want to do this in your custom application over the internet you have a problem. No API, no official documentation about how to sent messages through the Hue Portal that forwards it to your Hue bridge.

This blog post will show how you can send messages to your Hue bridge over the internet (without using port forwards). In this proof of concept I reuse the access token of IFTTT. The code samples are in C#, however you could make the same REST calls using the language of your choice.

BTW: I assume you have an account on the Hue portal and that you registered your Hue bridge.

What others write about this topic

Just a few people have some information about this like:
http://blog.paulshi.me/technical/2013/11/27/Philips-Hue-Remote-API-Explained.html
Hacking Lightbulbs: Security Evaluation of the Philips Hue Personal Wireless Lighting System by Nitesh Dhanjani
http://stackoverflow.com/questions/19900657/how-to-connect-backend-service-with-philips-hue-bridge-remotely

I investigated some of the findings from above resources. The parts about the getting the access token is not working, it’s probably out of date because of changes to the Hue Portal. So if you don’t have an access token you cannot send commands to the Hue Portal.

Local REST Messages

Sending a REST based message to your local bridge is done by sending a http request in the following format.

URL	http://<your bridge ip>/api/<username>/<some resource>
Method	GET/PUT/POST/DELETE
Body	JSON formatted data

To turn on light 1 you will send a message like:

URL	/api/<username>/lights/1/state
Method	PUT
Body	{ “on”: true }

Remote REST Message

Now it gets interesting. Sending a message to your bridge through the Hue Portal is a bit different. You should always use POST and send the request to the Hue portal. It should also include a valid access token. The body contains a clipmessage which contains a clipCommand that encapsulates the JSON command you normally sent to your bridge (in local network mode).

The format is as follows:

URL	https://www.meethue.com/api/sendmessage?token=<AccessToken>
Method	always POST
Body	clipmessage=<JSON formatted clipCommand> clipCommand==> {    “clipCommand” :          {             “url”: “api/0/<some resource>”,             “method”: “GET/PUT/POST/DELETE”,             “body”: JSON formatted data          } }
Header	encoding: UFT-8 application/x-www-form-urlencoded

Note: the url in clipCommand uses ‘0’ what in a local scenario would be the username.

Below an example of a command that will turn on light 1.

URL	https://www.meethue.com/api/sendmessage?token=<AccessToken>
Method	POST
Body	clipmessage= {     “clipCommand” :          {             “url”: “/api/0/lights/1/state”,             “method”: “PUT”,             “body”:                { “on”: true }          } }

To retrieve the status of the Hue system you need to sent a message as follows:

URL	https://www.meethue.com/api/getbridge?token=<AccessToken>
Method	GET

The result will be a JSON string representing the current state of your Hue system.

AccessToken

The biggest challenge in all this is to obtain a valid access token. In the next step I’m going to get the access token that IFTTT is using. But you could also use the access token of the official Philips Hue app.

Steps:

1- Go to IFTTT

2- Search for Channel ‘Philips Hue’

3- Activate Channel, this will bring you to the Hue Portal and log you in, and ask you to trust IFTTT. Click ‘Yes’. The Hue Portal will generate an access token and IFTTT will use that access token to send command to your Hue bridge.

4- When channel is activated logon to Hue Portal

5- Go to ‘Settings’

6- Click on ‘My Apps’ and you will see a list of apps you trusted for accessing your Hue bridge.

7- Copy the link of the ‘(De-activate)’ link. It will contain the access token. Here’s an example of my token: https://www.meethue.com/en-us/user/preferencesappsrevoke?tokenId=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaTT0%3D
The access token you should send in the remote message should be: “aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaTT0=” (without the double quotes and make sure to URL encode the whole thing).

BTW: If you revoke the access token by clicking ‘De-activate’ the access token cannot be used anymore. You will get a JSON response containing the message “I don't know that token”.

Code samples

We now have the message structure and the access token. We can now put this together in a C# sample.

   1: dynamic command = new ExpandoObject();

   2: command.clipCommand = new

   3: {

   4:     //change state of light 1

   5:     url = "/api/0/lights/1/state",

   6:     method = "PUT",

   7:     body = new

   8:     {

   9:       //set the light state changes

  10:       on = true

  11:     }

  12: };

  13:  

  14: SendMessage(command).Wait();

Lines 1-12 builds the clipCommand.
Line 14: sends the command

   1: private static async Task SendMessage(dynamic command)

   2: {

   3:   string jsonMessage = JsonConvert.SerializeObject(command);

   4:  

   5:   HttpClient client = new HttpClient();      

   6:   HttpContent content = new StringContent("clipmessage=" + jsonMessage, Encoding.UTF8, "application/x-www-form-urlencoded");

   7:  

   8:   Uri remoteMessageUrl = new Uri("https://www.meethue.com/api/sendmessage?token=<YOUR ACCESS TOKEN>");

   9:   var result = await client.PostAsync(remoteMessageUrl, content).ConfigureAwait(false);

  10:   var jsonResult = await result.Content.ReadAsStringAsync().ConfigureAwait(false);  

  11: }

Line 3: creates JSON formatted string of the command.
line 6: creates the body of the message, including the encoding and mediatype
line 8: creates URI including the access token
Line 9: sends request to Hue Portal
line 10: will contain results of the request.
Possible results could be:
success: "{\"code\":200,\"message\":\"ok\",\"result\":\"ok\"}"
failure: "{\"code\":109,\"message\":\"I don\\u0027t know that token.\",\"result\":\"error\"}"
failure: "{\"code\":113,\"message\":\"Invalid JSON.\",\"result\":\"error\"}"

 

Show me the Code

Get the C# sample from https://github.com/koenvanderlinden/RemoteHueDemo that contains sample for sending a message to change lights and how to retrieve bridge status.
Let me know if you think this blog post helped you in building a Hue enable application ;-).

TODO: getting the access token is still done by hand and it reuses another popular Hue application. Next step will be how to make the Hue Portal trust your own third party Hue app so you can use your own access token.