Hued documentation

A daemon for controlling Philips (friends of) hue lights by applying rules based on conditions. Rules can in turn trigger or ensure execution of certain events or scenes.

Features

• Supports individual lights and groups known to the bridge
• Multiple rules with multiple conditions and multiple events or a scene
• Scenes for reusing a specific set of events

Requirements

Hued is a pure Ruby application, so you need

• Ruby 1.9 (>= 1.9.3) or 2.x

The following Ruby libraries are required:

• Chronic (>= 0.10.0)
• EventMachine (>= 1.0.0)
• Huey (with Color) (>= 2.1.0)

At the moment, hued requires a patched version of Huey that supports a single light or set of lights for an event.

Installation

For now, Hued is in a developing state and not ready for other uses than tinkering.

Usage

Create bridge.yml which contains the IP address and API key (i.e. user) of the bridge. For example:

ip: 192.168.0.1
user: 1234567890abcdef1234567890abcdef

Then, set up some rules and add the needed events and/or scenes.

Rules

A rule is a central object that combines conditions, events and or scenes. When a rule is valid given its conditions, the associated events or scene can be executed (or triggered). Create rules.yml to contain a list of named rules. The full format with defaults is as follows:

Default rule:
  conditions: []
  trigger: true
  priority: 0
  events: []
  scene:

So, a rule has a priority of 0, no conditions, no events and no scene by default, but either a event or scene needs to be given. If both are given, the scene takes precedence. If trigger is enabled, the events or the scene will only be executed when becoming valid and active. (Being valid but not active can happen when a higher priority rule is valid.)

Events

An event is a bundle of light state changes for a single light, a set of lights or a group known to the bridge. Create events.yml if you want to use (named) events. The full format with defaults is as follows:

Default event:
  light:
  lights: 
  group:
  actions: {}

An event is required to have at least one action (i.e. a state variable change) and a single light, set of lights or group. If two or more are specified then group takes precedence over set of lights which in turn takes precedence over single light. A single light can be specified by a light name or ID. A set of lights can be specified by an array of IDs or a partial light name which will be matched against all light names. A group can be specified by a group name or ID.

Scenes

A scene is a series of nameless events. A scene is executed by executing all its events and can be used to set up different lights with different light states. It is similar to what is used on remote controls or the hue tap. Create scenes.yml if you want to use scenes.

Default scene: []

A default scene contains no events.

Example setup

An example setup:

rules.yml:

Off when closed:
  trigger: false
  events:
    - All off

Office lighting during working ours:
  conditions:
    from: today at 9:00
    until: today at 18:00
  priority: 1
  scene: Nice office lighting

The rule "Off when closed" has no conditions, thus it is always valid. It is also not a trigger so when valid and active it will always excute the "All off" event (see below).

Between 9:00 and 18:00, the rule "Office lighting during working hours" is valid and it has a higher priority, so "Off when closed" will become inactive. By default this is a trigger, so at activation it will execute the scene "Nice office lighting" (see below).

At 18:00 the "Office lighting during working hours" will become inactive again and the always-valid "All off" rule will take over and start

events.yml:

  All off:
    lights: [1, 2, 3, 4]
    actions:
      "on": false

scenes.yml:

Nice office lighting:
  - light: Hue light window
    actions: 
    hue: 12345
      sat: 200
      bri: 255
  - lights: LivingColor light
    actions:
      xy: [0.5, 0.6]
      bri: 211
  - group: Anti-burglary
    actions:
      "on": false

Running hued

Currently, all the files mentiond above need to be in the current working directory from where hued is started.

See hued --help for the available command-line options.

License

Hued is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.