A small, composable Philips Hue interface for Node and the browser.
Under development, unstable API.
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
yellowand 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)
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 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: 30000sat: 251bri: 101
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
This class has no methods. It could be implemented as a function, but, you know, symmetry.
Light an object (like one returned from
GET /api/lights/1) and it copies the metadata onto itself, but upgrades
.state into a
You'll be able to access the state object from the Light instance like so:
const light =state: hue: 10000uniqueid: 'bob'lightstate
Like I said, no methods though. Maybe in the future.
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
// 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
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
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
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 😀