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.
This repository has been archived on 2020-04-11. You can view files and clone it, but cannot push or open issues or pull requests.
Go to file
2016-02-02 17:34:11 +01:00
bin Add support for non-interactive usage of huec 2016-02-02 17:34:11 +01:00
lib Actually cache the new sunrise/sunset data of the correct day 2015-09-22 19:38:48 +02:00
.gitignore Only ignore configuration files in the config directory 2014-11-16 11:27:12 +01:00
LICENSE Fix spacing in LICENSE 2014-11-16 11:28:50 +01:00
README.md Replace the dark_at condition implementation 2015-09-18 23:34:32 +02:00

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.


  • Controls individual lights, sets of lights and groups known to the bridge
  • Uses scenes for bundling a specific set of events
  • Supports multiple rules with multiple conditions for executing certain events or activating a certain scene
  • Supports rule prioritization
  • Has an addiotional command-line tool for light manipulation

Support conditions:

  • Host (machine/phone/other IP-enabled device) online
  • Start time (per day or globally)
  • End time (per day or globally)
  • Specific weekdays
  • When it is dark (using sunset/sunrise time using the Sunrise-Sunset API 1)


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)
  • Nokogiri (>= 1.5.0)
  • Rainbow (>= 0.8.0)

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


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


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

user: 1234567890abcdef1234567890abcdef

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


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: []

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.)

FIXME: say something about conditions


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:
  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.


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:


Off when closed:
  trigger: false
    - All off

Office lighting during working hours:
    from: today at 9:00
    until: today at 18:00
    weekdays: mon,tue,wed,thu,fri
  priority: 1
  scene: Nice office lighting

The rule "Off when closed" has no conditions, thus it is always valid. Since it is not a trigger, when valid and active it will keep excuting the event "All off" (see below) repeatedly.

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

At 18:00 the "Office lighting during working hours" will become inactive and the always-valid rule "All off" will become active and start executing the event "All off" repeatedly again during the night.


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


Nice office lighting:
  - light: Hue light window
      hue: 12345
      sat: 200
      bri: 255
  - lights: LivingColor light
      xy: [0.5, 0.6]
      bri: 211
  - group: Anti-burglary
      "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.


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.