How to connect backend service with philips hue bridge remotely?

vinnybad picture vinnybad · Nov 11, 2013 · Viewed 10.2k times · Source

I'm looking to write a philips hue service that needs to allow users to register their hue bridge with my service. This service would change the color of bulbs based on an event. I'm aware that I can use IFTTT but in this scenario, I'd like to not use IFTTT and I'd like to register my website with philips hue's apps.

Any idea how I can do this? Your help is very much appreciated. Thanks!

EDIT: Not sure why I was down voted but I definitely did do my research. I looked on philips hue's developer website and couldn't find anything that was explicit on their APIs. I also looked through the iOS SDK and didn't see any methods that would trigger the pairing routine for remote devices. So far, the only example I have of this working (outside of Philips' products is the IFTTT service, which allows for an entry to be added into the 'My Apps' section).

Answer

Paul Jianer Shi picture Paul Jianer Shi · Nov 27, 2013

TLDR: I wrote an API: https://github.com/jarvisinc/PhilipsHueRemoteAPI

I answered this question on my technical blog (http://blog.paulshi.me/technical/2013/11/27/Philips-Hue-Remote-API-Explained.html), which I will post here:

The question actually comes as two part:

  • Authentication
  • Remote Control

Authentication

I haven't figure out a reliable way to do authentication automatically. The following procedures needs to be automated: The idea is to fake as official iOS APP which has the ability to control remotely when enabled. We will need to get BRIDGEID and ACCESSTOKEN to pass the authentication step for remote control.

  1. Find your BRIDGEID from https://www.meethue.com/api/nupnp. (or in My bridge page on the meethue website and by clicking on "Show me more")

  2. Get ACCESSTOKEN

    www.meethue.com/en-US/api/gettoken?devicename=iPhone+5&appid=hueapp&deviceid=**BRIDGEID**
    
  3. Right click on "BACK TO THE APP" and write down ACCESSTOKEN inside the link it redirect to

    phhueapp://sdk/login/**ACCESSTOKEN**
    

Basically it is a hack to get your access token. You fake your app as the official iOS Hue App, and ask for access token that way. I am not sure there is an easier way out there, if you do know one, please do comment below.

You can potentially automate it by doing simulated log-in session and grab the the ACCESSTOKEN by scraping the page content. But I consider it highly unreliable because any change to the official page will likely break it.

I wrote this script that allows the automation of getting ACCESSTOKEN as of today, but I don't guarantee it will work tomorrow for the reason I explained above :P

Currently, this OAUTH process only works with official apps. There might be a slight chance that they will open it to other 3rd party apps.

Remote Control

Once authentication is done, this part can be done automatically. There are 2 known private endpoints for sending control command and getting all the status related to the hue bridge.

  • Sending Command Endpoint:

    POST https://www.meethue.com/api/sendmessage
    
  • Getting Status Endpoint:

    GET https://www.meethue.com/api/getbridge
    

Sending Command Endpoint

  • URL: https://www.meethue.com/api/sendmessage

  • Method: POST

  • URL Parameters:

    token=**ACCESSTOKEN** (which you obtained earlier)
    
  • Request header

    content-type=application/x-www-form-urlencoded
    
  • body

    clipmessage={ bridgeId: "**BRIDGEID**", clipCommand: { url: "/api/0/**APIENDPOINT**", method: "**METHOD**", body: **JSONCOMMAND** } }
    
    • BRIDGEID is the same one you obtained earlier
    • APIENDPOINT the same as official API /api/<username>/*** by removing /api/<usename>/ part
    • METHOD PUT/GET/POST/DELETE the same 4 method as official API. Despite GET really doesn't work since all response from the Sending Command Endpoint is 200 explained in the following part, while DELETE is not tested
    • JSONCOMMAND The actual command body for example {"on":true}

Getting Status Endpoint

  • URL: https://www.meethue.com/api/getbridge

  • Method: GET

  • URL Parameters:

    token=**ACCESSTOKEN**
    bridgeid=**BRIDGEID**
    
  • Request header

    content-type=application/x-www-form-urlencoded
    

Limitations

Current limitation is you cannot immediately know from the response whether your control command succeeded like the official API. All the response you get from calling the Sending Command Endpoint is pretty much always <200> if you are doing it correctly. But you can always pull all the status related to the Hue bridge from the Getting Status Endpoint.

Remote Control API

I wrote Philips HUE Remote API to specifically solve the remote control problem.

Enjoy :)

Paper

For full documentation please refer to this excellent paper:

Hacking Lightbulbs: Security Evaluation of the Philips Hue Personal Wireless Lighting System by Nitesh Dhanjani