illumination
A small, composable Philips Hue interface for Node and the browser.
Under development, unstable API.
Why?
Hue's API is rather unintuitive, and has more baggage than probably needed. For example: there are three ways to set a lamp color:
- XY - Coordinates in CIE color space.
- Temperature - The degrees in Mired color space.
- HSB - Hue, saturation, and brightness.
The most intuitive of the three is HSB (aka HSL, which you've probably used in CSS), but the API implements it differently. Brightness goes from 1-254, saturation from 0-254, and hue from 0-65535. That's a far cry from hsl(240, 40%, 45%)
.
This library handles some of the rougher edges, using TinyColor to collapse any CSS color expression into an API-compliant HSB expression.
lightstatecolor'blue'lightstatecolor'#00F'lightstatecolor'rgb(0, 0, 255)' // Supports alpha channels, toolightstatecolor'#0000FFFF'
Note: due to hardware limitations, colors may seem a bit off. Try
yellow
and you'll see what I mean.
Colors are the most obvious, but not the only way Hue's API can be improved...
- Transition time, measured in second/10 (not milliseconds)
- Groups (which requires an entirely new API)
- Scenes (same as groups)
Illumination is created to address these problems, simplifying the hue interface.
It introduces four simpler concepts:
- States (such as color, alerts/effects, transitions...)
- Lights (holds state and light information)
- Presets (Groupings of lights and states)
- Bridges (for applying presets)
API
Illumination is under development, and APIs are subject to change at little more than a whim. Because of that, I haven't invested much into documenting what they do.
If you want to try it out now, I suggest poking around in the source code - I use JSDoc liberally.
You can install illumination with npm:
$ npm install illumination --save
Then import it (with ES6 modules FTW!)
State
State is an interface over hue light state, but it doesn't need to be tied to a light.
const state =
From there, you can start editing the light state. Once you're ready, you add it to a Preset (more on this soon) and submit it to the bridge. If you need to import an existing hue state, you can pass it directly to the constructor.
const state = hue: 30000 sat: 251 bri: 101
Methods
Since the API is changing often, I'm just gonna run through these really quick. Look in the source code for more details.
// Blink the light.statestatestate // Turn the light on.statestate // Turn the light off.statestate // Start a colorloop.state// Stop it.state // Change the color.statecolor'blue'statecolor'#00f'statecolor'rgb(0, 0, 255)' // Degrees, 0-360.state// Percent saturation.state// Percent brightness.state
Light
This class has no methods. It could be implemented as a function, but, you know, symmetry.
You pass Light
an object (like one returned from GET /api/lights/1
) and it copies the metadata onto itself, but upgrades .state
into a State
instance.
You'll be able to access the state object from the Light instance like so:
const light = state: hue: 10000 uniqueid: 'bob' lightstate
Like I said, no methods though. Maybe in the future.
Preset
This is where things get fun! Presets are collections of light states, most comparable to a hue scene (but lightweight).
A preset might be what lights are on at a time, or what colors a group of lights are set to. You can manipulate entire groups at once using some convenience methods.
For example: you might want to create a general preset containing your living room lights, then five more presets that build off it and change the colors and transition times.
// Either add them on at once...const preset = 1: name: 'Living Room Lamp' 2: name: 'Office Lamp' // Or add them later.const light = name: 'Porch Light'preset
Methods
// Change all colors at once.presetcolor'blue' // Set transition time.preset // Like Object.keys.preset // Adds a new light to the preset.preset // Iterate over each light.preset
Bridge
Creates a bridge interface that understands presets and has a reasonable api.
No bridge discovery mechanism is included, as I think that would be feature bloat and belongs in a separate module.
Also, it would prevent illumination from being browser friendly.
// `ip` is the IP address,// `key` is the API key.const bridge = ip key
Methods
The Bridge
class is fairly new and doesn't have many methods. As needed I'll add some more.
// Formats an absolute urlbridge// Also works with arraysbridge // Resolves to the http response databridge // Sends preset state to the bridge.// This is probably what you're looking for.bridge
Installing from GitHub
I love all the cool toys ES6/7 brings. For now, that means compiling the project through Babel.
$ git clone https://github.com/PsychoLlama/iillumination.git$ cd illumination$ npm install # `npm run dev` if you're editing. $ npm run babel
To run mocha, do npm test
.
Support
If you find a problem, lemme know by filing a GitHub issue. This is a hobby project, but I'll try to follow up asap.
You can support this project and my narcissism by starring it 😀