This is an old revision of the document!

---

Philips Hue Bridge Protocol

This implementation adds support for the Philips Hue protocol using the Philips Hue Bridge Rest API to control Philips Hue bulbs. The protocol polls the status from the Bridge every minute to update the device values in pilight.

Requirements

The Hue Bridge is connected to the same LAN as the machine running the pilight daemon.
Using the Hue Bridge allows smooth integration of pilight into the overall environment. The concept of the Hue Bridge is found here: http://www.developers.meethue.com/documentation/core-concepts. The bridge itself is using the zigbee protocol to communicate with the Hue bulbs. This interface is currently not supported.

To use all available settings for the bulbs you do need to use the CLI interface for the protocol philipshue and pilight-send or pilight-control.
The pilight WEBGUI, supports a subset of the capabilities of Hue bulbs.

Supported Brands

All Hue Bulbs connected to the Hue Bridge.

Sender Arguments

To create a new user on the Hue Bridge, proof of physical access to the Hue bridge is required.

Config

1. Create a user on the Hue Bridge:

First a username must be created and authorized on the bridge. To do so, you do need to press the button on the Hue Bridge AND execute the following pilight command at the same time:

$ pilight-send -p philipshue --bridgeip=192.168.0.252 --newuser

pilight will respond either with an error message:

pilight-send: NOTICE: Create and authorize new user for pilight on Hue Bridge ...
pilight-send: NOTICE: philipshue - post data = {"devicetype":"pilight"} to url http://192.168.0.252/api
pilight-send: NOTICE: response from hue bridge = [{"error":{"type":101,"address":"","description":"link button not pressed"}}]
pilight-send: NOTICE: description = link button not pressed
pilight-send: NOTICE: ----> Press Link button and run again pilight-send -p philipshue --ip=192.168.0.252 --newuser

or report the username generated:

$ pilight-send -p philipshue -i 192.168.1.252 --newuser
pilight-send: NOTICE: Create and authorize new user for pilight on Hue Bridge ...
pilight-send: NOTICE: philipshue - post data = {"devicetype":"pilight"} to url http://192.168.0.252/api
pilight-send: NOTICE: response from hue bridge = [{"success":{"username":"29b7e422ee6f973bc97b3e1f3269a3"}}]
pilight-send: NOTICE: ----> Successfully created and authorized username = 29b7e422ee6f973bc97b3e1f3269a3 <--- Use this username

You do need to copy the username to your config.json file. “devices”: {

  "Hue1": {
      "protocol": [ "philipshue" ],
      "id": [{
          "bridgeip": "192.168.0.252",
          "username": "29b7e422ee6f973bc97b3e1f3269a3",
          "lightid": 1
      }],
      "on": "false",
      "bri": 254,
      "hue": 8625,
      "sat": 252,
      "effect": "none",
      "x": 0.5837,
      "y": 0.3879,
      "ct": 500,
      "alert": "select",
      "dimlevel": 15,
      "group": 0,
      "scene": "0",
      "state": "off"
      }
  }
  "rules": {},
  "gui": {
      "Hue1": {
          "name": "Study",
          "group": [ "Lights" ],
          "media": [ "all" ]
      }
  },
  "settings": { .... },
  "hardware": { .... },
  "registry": { .... }

} </code>

The pilight GUI interface supports turning lights ON/OFF and dimming of the device in 15 steps. For all other command sequences, currently the CLI interface (pilight-send, pilight-control) has to be used.

Configuration Steps

Each Hue Bridge has its own username. For each lampid, you do need to configure a device and assign it to a group. Configure in the GUI section Dimmer devices if GUI support is required.

Examples

List all bulbs on the bridge: $ pilight-send -p philipshue –bridgeip=192.168.0.252 –username=29b7e422ee6f973bc97b3e1f3269a3 –resource=lights

List all scenes on the bridge: $ pilight-send -p philipshue –bridgeip=192.168.0.252 –username=29b7e422ee6f973bc97b3e1f3269a3 –resource=scenes pilight-send: NOTICE: philipshue - get data http://192.168.0.252/api/29b7e422ee6f973bc97b3e1f3269a3/scenes pilight-send: NOTICE: 497b50d84-on-0 = {“name”:“Sunset on 0”,“lights”:[“1”,“2”,“3”],“active”:true} pilight-send: NOTICE: ac637e2f0-on-0 = {“name”:“Relax on 0”,“lights”:[“1”,“2”,“3”],“active”:true} …

Apply a scene: $ pilight-send -p philipshue –bridgeip=192.168.0.252 –username=29b7e422ee6f973bc97b3e1f3269a3 –scene=497b50d84-on-0

Turn all lights on: $ pilight-send -p philipshue –bridgeip=192.168.0.252 –username=29b7e422ee6f973bc97b3e1f3269a3 –group=0 -t

Turn all lights off: $ pilight-send -p philipshue –bridgeip=192.168.0.252 –username=29b7e422ee6f973bc97b3e1f3269a3 –group=0 -f

Set full brightness red on light 2: $ pilight-send -p philipshue –bridgeip=192.168.0.252 –username=29b7e422ee6f973bc97b3e1f3269a3 –lightid=2 –bri=255 –sat=255 –hue=0

Turn light 1 to red. $ pilight-control -d Hue1 -s on -v hue=65280

Turn all lights on $ pilight-control -d Hue1 -s on -v group=0

Turn all lights off $ pilight-control -d Hue1 -s off -v group=0

Apply scene $ pilight-control -d Hue1 -s off -v scene=497b50d84-on-0

Hints

When you configure rules, you should limit the number of requests to be below 10 requests per second for an individual device and below 1 per second for a group.

When you configure conflicting parameters, only one parameter is accepted, the priority is: - xy beats ct beats hue beats sat.

All lights act as a single repeater, if you need to extend your physical range, put a lamp inbetween.

Once a light is ON, it stays on, do not sent ON commands repetively, as it slows down the bridge.

Known Limitations

The WEBGUI currently supports: ON, OFF, DIM UP/DOWN in 15 steps. Color, Scenes etc. do need to be controlled via the CLI interface.

Literature More information about the Hue system can be found here:

http://www.developers.meethue.com/documentation/getting-started http://www.developers.meethue.com/documentation/core-concepts