node-lifx v0.8.0

LIFX Node.js Library

A Node.js implementation of the LIFX protocol. Developed to work with a minimum firmware version of 2.0.

This library is not, in any way, affiliated or related to LiFi Labs, Inc.. Use it at your own risk.

Installation

$ npm install node-lifx --save

Compatibility

Node.js 0.12+ and io.js are tested and supported on Mac, Linux and Windows.

Usage

The file cli.js contains a working example.

Client

The library uses a client for network communication. This client handles communication with all lights in the network.

var LifxClient = require('node-lifx').Client;
var client = new LifxClient();

client.init();

The Client object is an EventEmitter and emmits events whenever any changes occur. This can be a new light discovery, a light sending a message or similar. The client starts discovery of lights right after it is initialized with the init method. If a new light is found the client emmits a light-new event. This event contains the light as an object on which methods can be called then:

var LifxClient = require('node-lifx').Client;
var client = new LifxClient();

client.on('light-new', function(light) {
  // Change light state here
});

client.init();

Changing light state

The states of a light can be changed with different methods:

light.on([duration], [callback])

This turns a light on.

Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.on(); // Turns the light on instantly
light.on(2000); // Fading the light on over two seconds

light.off([duration], [callback])

This turns a light off.

Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.off(); // Turns the light off instantly
light.off(2000); // Fading the light off over two seconds

light.color(hue, saturation, brightness, [kelvin], [duration], [callback])

Changes the color of a light to an HSB color value. This is the preferred method to change the color of a light.

Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.color(0, 100, 50); // Set to red at 50% brightness
light.color(50, 50, 80, 3500, 2000); // Set to a light green at 80% brightness over next two seconds

light.colorRgbHex(hexString, [duration], [callback])

Changes the color of a light to an RGB color value given in Hex Format. Note that RGB poorly represents color of light, prefer HSBK values given via the color method.

Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.colorRgbHex('#F00'); // Set to red
light.colorRgbHex('#FFFF00'); // Set to yellow

light.colorRgb(red, green, blue, [duration], [callback])

Changes the color of a light to an RGB color value. Note that RGB poorly represents color of light, prefer HSBK values given via the color method.

Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.colorRgb(255, 0, 0); // Set to red
light.colorRgb(255, 255, 0); // Set to yellow

light.maxIR(brightness, callback)

Set's the maximum infrared brightness of the light (only for lights that support infrared light)

Usage examples:

light.maxIR(0); // Set's a maximum infrared brightness of 0
light.maxIR(25); // Set's a maximum infrared brightness of 25

light.getMaxIR(callback)

Requests the maximum infrared brightness of the light (only for lights that support infrared light)

Example result:

null,
{
  brightness: 25
}

Requesting light state and info

Infos of the state and spec of the light can be requested with the following methods:

light.getState(callback)

Requests general info from a light, this includes color, label and power state. This function is asynchronous.

Example result:

null,
{
  color: { hue: 120, saturation: 0, brightness: 100, kelvin: 8994 },
  power: 0,
  label: 'Kitchen'
}

light.getPower(callback)

Requests current power state (on or off). This function is asynchronous.

Example result:

null,
0 // off

light.getFirmwareVersion(callback)

Requests the firmware version from a light (minor and major version). This function is asynchronous.

Example result:

null,
{
  majorVersion: 2,
  minorVersion: 1
}

light.getHardwareVersion(callback)

Requests the hardware version from a light (vendor, product and version). This function is asynchronous.

Example result:

null,
{
  vendorId: 1,
  vendorName: 'LIFX',
  productId: 1,
  productName: 'Original 1000',
  version: 6,
  productFeatures: {
    color: true,
    infrared: false,
    multizone: false
  }
}

light.getFirmwareInfo(callback)

Requests info from the micro controller unit of a light (signal, tx and rx). This function is asynchronous.

Example result:

null,
{
  signal: 0,
  tx: 0,
  rx: 0
}

light.getWifiInfo(callback)

Requests wifi info from a light (signal, tx and rx). This function is asynchronous.

Example result:

null,
{
  signal: 0.000009999999747378752,
  tx: 16584,
  rx: 12580
}

light.getWifiVersion(callback)

Requests the wifi firmware version from the light (minor and major version). This function is asynchronous.

Example result:

null,
{
  majorVersion: 2,
  minorVersion: 1
}

light.getAmbientLight(callback)

Requests the ambient light value in flux from the light. This function is asynchronous.

Example result:

null,
10

Labels

Labels of lights can be requested and set using the following methods:

light.getLabel(callback, [cache])

Requests the label of a light. This function is asynchronous.

Example result:

null,
'Kitchen'

light.setLabel(label, [callback])

Sets a new label for a light.

Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.setLabel('Bedroom Light');
light.setLabel('Kitchen Light 4', function(err) {
  if (err) { throw err; }
  console.log('New light label has been set');
});

Get a light

client.light(identifier)

Find a light in the list off all lights by ip, label or id.

Returns a light object that can then be used to call methods on it. For example client.light('192.168.2.102').on().

Get all lights

client.lights([filter])

Get a list of all known lights

Client events

The following events might be thrown by the client.

light-new

This event is thrown when there is a new light discovery that has not been seen at runtime before. This event is provided with the new light object. client.on('light-new', function(light) {});

light-offline

This event is thrown when a light hasn't been discovered for a time. The light given is no longer expected to be reachable. client.on('light-offline', function(light) {});

light-online

This event is thrown when a light is discovered again after being offline. client.on('light-online', function(light) {});

Start / Stop discovery

The discovery for each client can be started and stopped at runtime using these commands:

client.startDiscovery()

Starts the discovery process.

client.stopDiscovery()

Stops the discovery process.

Client settings

For the initialization of the client different settings can be provided. This is an example with the default options:

var LifxClient = require('node-lifx').Client;
var client = new LifxClient();

// ...

client.init({
  lightOfflineTolerance: 3, // A light is offline if not seen for the given amount of discoveries
  messageHandlerTimeout: 45000, // in ms, if not answer in time an error is provided to get methods
  startDiscovery: true, // start discovery after initialization
  resendPacketDelay: 150, // delay between packages if light did not receive a packet (for setting methods with callback)
  resendMaxTimes: 3, // resend packages x times if light did not receive a packet (for setting methods with callback)
  debug: false, // logs all messages in console if turned on
  address: '0.0.0.0', // the IPv4 address to bind the udp connection to
  broadcast: '255.255.255.255', // set's the IPv4 broadcast address which is addressed to discover bulbs
  lights: [] // Can be used provide a list of known light IPv4 ip addresses if broadcast packets in network are not allowed
             // For example: ['192.168.0.112', '192.168.0.114'], this will then be addressed directly
});