I hope this will be a useful guide if you are starting out with the Hue API and Home Assistant, as the project touches on several core concepts such as JSON, RESTful APIs, sensors, triggers and automations.
I have a Hue dimmer remote (http://www2.meethue.com/en-us/productdetail/philips-hue-dimmer-switch) which was originally purchased to switch a light which had its switch inconveniently placed behind a door. It works great and saved the hassle of having an electrician come over to install a traditional switch where I wanted it. The remote has four buttons, but I only ever use two, to toggle the light on and off. I could do this with a hacked Amazon Dash button, therefore this remote is free for more interesting things that make use of all four buttons. A connected remote that could be used to trigger four different automations in my home would be far more useful for example, and luckily this is possible with the Hue developer API and Home Assistant!
Hue smart devices (lights, remotes, etc) are all controlled via a hub (Philips call it a ‘bridge‘ http://www2.meethue.com/en-us/productdetail/philips-hue-bridge) which sits on your network and communicates with the devices via Zigbee. Whilst it is not possible to directly control the devices from your computer, you can control them via the hub using the Hue RESTful API. This arrangement is shown in Figure 1.
In order to use RESTful commands with the Hue hub you will first need to generate an “Authorized Username”. I found this process is a bit confusing at first, so I’ll summarise it as:
- Identify the IP of the Hue hub <bridge ip address> (recommend the Hue app or Fing unless you are happy with your routers interface)
- Using a web interface to make a POST command requesting a new username (in the example it is <username> = 1028d66426293e821ecfd9ef1a0731df)
The full steps are detailed at https://developers.meethue.com/documentation/getting-started. Now you have the username I recommend viewing the state of you hub in a web browser. I found a useful Chrome plugin which nicely formats the JSON called the JSON Viewer.
In the browser paste the URL:
http://<bridge ip address>/api/<username>
to view the entire state of the Hue hub. In the browser, I can flatten the displayed JSON to view the primary keys: lights, groups, config, schedules, scenes, rules, sensors, resource links. Now the Hue remote falls under ‘sensors’ so enter the URL:
For more detail: Hijack a Hue Remote to Control Anything with Home Assistant