JS library for LIFX bulbs

A NodeJS client for the LIFX bulbs based on my observations of the network protocol using tcpdump and Wireshark. This is very much experimental, so is most likely incorrect or inaccurate, although it seems to work for me. You have been warned. Observations are documented in Protocol.md.

This is based on my setup of 2 bulbs in a single group. That may or may not affect the network protocol. Also, I've not looked at how the bulbs are initially setup to hop onto your wireless network; I configured mine with the iPhone app, and this library is (currently) for manipulating the bulbs once they are already attached to your network.

Bonus: There's a demo web app in the "web" dir which just displays a colour picker and sets the bulbs to the chosen colour, and a demo mqtt bridge in the "mqtt" dir which bridges between an MQTT broker and the bulbs

Install

To install from NPM, do npm install lifx, or just clone the github repo (but you'll need to run npm install in this dir to get the "clone" dependency if you get from github).

If you install form NPM, then do require("lifx");. If you cloned the github repo then you'll need to do something like require("./lifx"); (ie specify the path to the dir you cloned into).

If you want to run the web or mqtt app, you also need to run npm install in the respective dir to get their dependencies.

Files

There is 1 main file (lifx.js) which is all you need plus some example CLI apps:

• cli.js which is an example CLI app using the library
• cli2.js which lets you cycle through individual parameters to get a feel for what they mean
• cli3.js controls individual bulbs

My observations of the network protocol are documented in this doc. Hopefully LIFXLabs will release an official spec for the network protocol which will make this a lot easier.

Usage

The file cli.js is a working example.

In addition to the main "Lifx" object which acts as your agent to the Lifx bulbs, there are 2 fundamental objects in the library; a "gateway" object which represents the wifi interface (and can do things like discovery of the other bulbs, send messages to a bulb etc) and a "bulb" object which is useful for sending commands to individual bulbs.

To begin with, you must include the library and then call lifx.init() which will return a new Lifx object and initialise discovery of gateways and bulbs.

var lifx = require('./lifx');
var lx   = lifx.init();

The Lifx object is an EventEmitter, and emits a "bulb" event whenever a new bulb is found and a "gateway" event whenever a new gateway is found. Note that multiple bulbs can be acting as gateways on your network, especially if they haven't yet formed their mesh network.

Once you have the Lifx object, you can use it to send commands to all of the bulbs in the mesh network:

lx.lightsOn();
lx.lightsOff();
lx.lightsColour(hue,    saturation, luminance, whiteColour, fadeTime);
lx.lightsColour(0xd49e, 0xffff,     0x028f,    0x0dac,      0x0513);

or to target an individual bulb, pass an optional parameter:

var bulb = lx.bulbs[0];
lx.lightsOn(bulb);
lx.lightsOff(bulb);
lx.lightsColour(hue,    saturation, luminance, whiteColour, fadeTime, bulb);
lx.lightsColour(0xd49e, 0xffff,     0x028f,    0x0dac,      0x0513,   bulb);

The params are always 16-bit numbers, which get their bytes shuffled around before being sent over the network (see the protocol doc for the underlying details).

• hue represents the colour to use, and is manipulated by the colour wheel in the iPhone app.
• saturation represents how much of the colour to use, and is generally either 0xffff (if using the "Colors" screen in the iPhone app) or 0x0000 (if using the "Whites" screen in the iPhone app).
• luminance is how bright the bulbs should be.
• whiteColour is something like the colour temperatue, and is the wheel used in the "Whites" screen in the iPhone app.
• fadeTime says how quickly the bulbs should move to the given state, and seem to roughly be in milliseconds. Use 0 for an immediate change.

The "packet.js" module constructs each raw packet type, which can be sent to all bulbs using something like lx.sendToAll(packet.getLightState()). Similarly, to send a raw command to an individual bulb, use lx.sendToOne(packet.getLightState(), bulb) passing in a bulb object from the lx.bulbs array.

If you want to see debug messages (including network traffic) then call

lifx.setDebug(true);

Wireshark dissector

There is a wireshark dissector for the LIFX protocol in the "wireshark" directory. To load it, run Wireshark with:

/path/to/wireshark -X lua_script:/path/to/lifx.lua