Hijack a Hue Remote to Control Anything with Home Assistant

Introduction

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 API

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". You can retrieve the user name using CURL (note you will have to press the button on the Hue hub first):

CURL -X POST -d '{"devicetype":"my_hue_app"}' http://192.168.1.64/api --header "Content-Type:application/json"

Here 192.168.1.64 is the IP address of my hub, so replace that with your own. The response will be like:

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

Now you have the user name 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/<your_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:

http://<bridge ip address>/api/<your_username>/sensors 

Which returns in my case quite a long file containing 13 sensors. The one I am interested in I identified from the 'name' field and the JSON code is:

 "2": { 
   "state": { 
     "buttonevent": 4002, 
     "lastupdated": "2017-04-26T21:12:11" 
   }, 
   "config": { 
     "on": true, 
     "battery": 100, 
     "reachable": true, 
     "pending": [ 
     ] 
   }, 
   "name": "Hue-dimmer-switch-1", 
   "type": "ZLLSwitch", 
   "modelid": "RWL021", 
   "manufacturername": "Philips", 
   "swversion": "5.45.1.16265", 
   "uniqueid": "YOURS" 
} 

We now have all the data we need to create a sensor in software to check for changes in state of the remote!

Home Assistant integration

UPDATE: the use of RESTful sensors is no longer necessary since I have published a custom component below. I leave the explanation of RESTful sensors as a guide for other applications.

Home Assistant provides a RESTful sensor for monitoring the state of the Hue remote, described at https://home-assistant.io/components/sensor.rest/ We actually require two RESTful sensors, one to monitor the "buttonevent" and one to monitor "lastupdated", since we want to detect every push of a button and "buttonevent" will not change if the same button is pressed twice in a row. The buttonevents have values of 1002, 2002, 3002, 4002, and a template sensor is used to parse the first character of 1,2,3,4. The code below must be placed in the configuration.yaml file of Home Assistant. Note that you will need to change '2' to whichever value represents your remote.

- platform: rest 
 resource: http://<bridge ip address>/api/<your_username>/sensors/2 
 name: 
 value_template: '{{ value_json.state.buttonevent }}' 
 scan_interval: 1 
#
- platform: rest 
 resource: http://<bridge ip address>/api/<your_username>/sensors/2 
 name: 
 value_template: '{{ value_json.state.lastupdated }}' 
 scan_interval: 1 
- platform: template 
 sensors:  
   living_room_remote_status: 
     friendly_name: 'Living room remote' 
     value_template: '{{states.sensor.dimmer1_state.state[0]}}'  

Now time to do something useful with the remote, trigger some Home-assistant services! Here I present two approaches; 1) pure automations 2) using a python script.

Pure automation

The following automation automation sends a message to my iPhone when a button is pressed with the text of the message determined using a template. The code should be placed in the configuration.yaml:

- alias: Hue dimmer 1 automations 
 trigger: 
   platform: state 
   entity_id: sensor.dimmer1_updated 
 action: 
   service: notify.ios_robins_iphone 
   data_template: 
     title: "Hue notification" 
     message: > 
       {% if states.sensor.living_room_remote_status.state == "1" %} 
       'Button 1 pressed' 
       {% elif states.sensor.living_room_remote_status.state == "2" %} 
       'Button 2 pressed' 
       {% elif states.sensor.living_room_remote_status.state == "3" %} 
       'Button 3 pressed' 
       {% elif states.sensor.living_room_remote_status.state == "4" %} 
       'Button 4 pressed' 
       {% else %} 
       none 
       {% endif %} 

Python script

An alternative approach is to use a python script to determine what action to take when the remote is used. Create a file called hue_remote.py with the following code:

button_obj = hass.states.get('sensor.living_room_remote_status') 
button = button_obj.state 
if button == '1': 
   hass.services.call('light', 'turn_on', { "entity_id" : 'light.lamp', 'color_name': 'green' }) 
elif button == '2': 
  hass.services.call('light', 'turn_on', { "entity_id" : 'light.lamp', 'color_name': 'red' }) 
elif button == '3': 
  hass.services.call('light', 'turn_on', { "entity_id" : 'light.lamp', 'color_name': 'purple' }) 
elif button == '4': 
  hass.services.call('light', 'turn_on', { "entity_id" : 'light.lamp', 'color_name': 'yellow' }) 

Place this file in the folder <config>/python_scripts and add to configuration.yaml python_script: Restart Home-assistant and you will have added a service called python_script.hue_remote . Replace the service calls with whatever service you want.

Now we create an automation to trigger this script, and I created this automation using the Automation editor. I have added two triggers, changes on both lastupdated and buttonevent. I used two triggers since this was a more reliable trigger than using just one or the other, where sometimes a button press was not registered (could be related to scan_interval). The automation code is:

- id: Hue_remote_automation 
 alias: Hue remote automation 
 trigger: 
 - entity_id: sensor.remote_living_room_updated 
   platform: state 
 - entity_id: sensor.remote_living_room_button 
   platform: state 
 action: 
 - service: python_script.hue_remote 

I personally prefer python scripts over pure automations for 2 reasons. 1) You are coding in python rather than producing yaml, and (2) no need to restart Home-assistant to see changes in effect of the python script.

Component

I have now created a component to replace the RESTful sensors. The code is on Github. Example usage below. Forum discussion here.