166 lines
4.6 KiB
Markdown
166 lines
4.6 KiB
Markdown
|
# 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.
|