LIFX LAN 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 lifx-lan-client --save

$ yarn add lifx-lan-client

Compatibility

Node LTS and current versions are tested and supported on Mac, Linux and Windows. Older versions may work but are not supported or tested.

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('lifx-lan-client').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('lifx-lan-client').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.

Option	Type	Default	Description
`duration`	int	0	Turning on will be faded over the time (in milliseconds).
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
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.

Option	Type	Default	Description
`duration`	int	0	Turning off will be faded over the time (in milliseconds).
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
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.

Option	Type	Default	Description
`hue`	int		Between 0 and 360, representing the color hue in degree which changes the color.
`saturation`	int		Between 0 and 100, representing the color intensity from 0% to 100%.
`brightness`	int		Between 0 and 100, representing the light brightness from 0% to 100%.
`kelvin`	int	3500	Between 2500 and 9000, representing the color temperature.
`duration`	int	0	Fade the color to the new value over time (in milliseconds).
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
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.

Option	Type	Default	Description
`hexString`	string		A hex RGB string starting with `#`
`duration`	int	0	Fade the color to the new value over time (in milliseconds).
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
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.

Option	Type	Default	Description
`red`	int		Amout of red in color from 0 to 255
`green`	int		Amout of green in color from 0 to 255
`blue`	int		Amout of blue in color from 0 to 255
`duration`	int	0	Fade the color to the new value over time (in milliseconds).
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
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.setMultiZoneEffect(effectName, speed, direction, [callback])`

Changes a color zone range to the given HSBK value

Option	Type	Default	Description
`effectName`	string		Desired effect, currently available options are: `'MOVE'`, `'OFF'`
`speed`	number		Duration of one cycle of the effect, the higher the value the slower the effect animation
`direction`	string		Animate from or towards the controller, available options are: `'TOWARDS'`, `'AWAY'`
`callback`	function	null	Called after command has reached the light

`light.maxIR(brightness, callback)`

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

Option	Type	Default	Description
`brightness`	int		Between 0 and 100, representing the light brightness from 0% to 100%.
`callback`	function		`function(error, data) {}`

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.waveform(hue, saturation, brightness, [kelvin], [transient], [period], [cycles], [skewRatio], [waveform], [callback])`

Apply a waveform effect to the bulb.

Also see the LIFX waveform docs

Option	Type	Default	Description
`hue`	int		Between 0 and 360, representing the color hue in degree which changes the color.
`saturation`	int		Between 0 and 100, representing the color intensity from 0% to 100%.
`brightness`	int		Between 0 and 100, representing the light brightness from 0% to 100%.
`kelvin`	int	3500	Between 2500 and 9000, representing the color temperature.
`transient`	boolean	false	Whether to return to the previous color after the effect.
`period`	int	500	Duration of a cycle in miliseconds.
`cycles`	float	10e30	Number of wave cycles to stop after. Default value is effectively never. Total duration of the effect will be period * cycles.
`skewRatio`	float	0.5	The skew ratio to use for pulse waveforms (percentage of the time the old color is visible per period), between 0 and 1.
`waveform`	int	0	The waveform to use, between 0 and 4. 0 = SAW, 1 = SINE, 2 = HALF_SINE, 3 = TRIANGLE, 4 = PULSE.
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
Note: Using callback multiplies network load for this command by two or more times.

Usage examples:

light.waveform(0, 100, 50); // Set to a basic red wave at 50% brightness
light.waveform(50, 50, 80, 3500, true, 200, 5); // Set to a light green wave at 80% brightness over next two seconds, which will return to the previous color after five 200ms cycles

`light.getMaxIR(callback)`

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

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

Example result:

null,
0 // off

`light.getFirmwareVersion(callback)`

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

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

Example result:

null,
{
  majorVersion: 2,
  minorVersion: 1
}

`light.getAmbientLight(callback)`

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

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`

Example result:

null,
10

Switch

The following methods are used to control a Switch device with relays:

`light.hasRelays(callback)`

Checks to see if the device is a switch with relays. This function is asynchronous.

Option	Type	Default	Description
`callback`	function		`function(result) {}`

Example result:

true

`light.getRelayPower(relayIndex, callback)`

Gets the value of the relay at zero-based index i (0-3). This function is asynchronous.

Option	Type	Default	Description
`relayIndex`	int		The zero-based index of the relay (from 0 to 3)
`callback`	function		`function(error, level) {}`

Example result:

null,
65535

`light.relayOn(relayIndex, callback)`

Turns the relay on. This function is asynchronous.

Option	Type	Default	Description
`relayIndex`	int		The zero-based index of the relay (from 0 to 3)
`callback`	function		`function(error, data) {}`

Example result:

null,
65535

`light.relayOff(relayIndex, callback)`

Turns the relay off. This function is asynchronous.

Option	Type	Default	Description
`relayIndex`	int		The zero-based index of the relay (from 0 to 3)
`callback`	function		`function(error, data) {}`

Example result:

null,
0

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.

Option	Type	Default	Description
`callback`	function		`function(error, data) {}`
`cache`	boolean	false	Use the last known value for the label and and do not request from the light again

Example result:

null,
'Kitchen'

`light.setLabel(label, [callback])`

Sets a new label for a light.

Option	Type	Default	Description
`label`	string		New Label with 32 bit size maximum (which is a length of 32 with non unicode chars).
`callback`	function	null	`function(error) {}` Called after the command has reached the light or after `client.resendMaxTimes` with `client.resendPacketDelay` in case it has not. `error` is `null` in case of success and given if the sending has failed.
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.

Option	Type	Default	Description
`identifier`	string		Light label (case sensitive) `client.light('Kitchen')`, the ip address `client.light('192.168.2.102')` or the light id `client.light('0123456789012')`

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

Option	Type	Default	Description
`filter`	string	null	Filter list of lights to return only active (`null` or `'on'`), inactive (`'off'`) or all (`''`)

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('lifx-lan-client').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
  stopAfterDiscovery: false, // stops discovery process after discovering all known lights (requires list
                             // of addresses provided with "lights" setting)
  discoveryInterval: 5000, // Interval (in ms) between discovery operations
  messageRateLimit: 50, // The delay (in ms) between sending any two packets to a single light
});

Files

README.md

Latest commit

History

README.md

File metadata and controls

LIFX LAN Node.js Library

Installation

Compatibility

Usage

Client

Changing light state

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

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

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

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

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

light.setMultiZoneEffect(effectName, speed, direction, [callback])

light.maxIR(brightness, callback)

light.waveform(hue, saturation, brightness, [kelvin], [transient], [period], [cycles], [skewRatio], [waveform], [callback])

light.getMaxIR(callback)

Requesting light state and info

light.getState(callback)

light.getPower(callback)

light.getFirmwareVersion(callback)

light.getHardwareVersion(callback)

light.getFirmwareInfo(callback)

light.getWifiInfo(callback)

light.getWifiVersion(callback)

light.getAmbientLight(callback)

Switch

light.hasRelays(callback)

light.getRelayPower(relayIndex, callback)

light.relayOn(relayIndex, callback)

light.relayOff(relayIndex, callback)

Labels

light.getLabel(callback, [cache])

light.setLabel(label, [callback])

Get a light

client.light(identifier)

Get all lights

client.lights([filter])

Client events

light-new

light-offline

light-online

Start / Stop discovery

client.startDiscovery()

client.stopDiscovery()

Client settings

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

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

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

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

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

`light.setMultiZoneEffect(effectName, speed, direction, [callback])`

`light.maxIR(brightness, callback)`

`light.waveform(hue, saturation, brightness, [kelvin], [transient], [period], [cycles], [skewRatio], [waveform], [callback])`

`light.getMaxIR(callback)`

`light.getState(callback)`

`light.getPower(callback)`

`light.getFirmwareVersion(callback)`

`light.getHardwareVersion(callback)`

`light.getFirmwareInfo(callback)`

`light.getWifiInfo(callback)`

`light.getWifiVersion(callback)`

`light.getAmbientLight(callback)`

`light.hasRelays(callback)`

`light.getRelayPower(relayIndex, callback)`

`light.relayOn(relayIndex, callback)`

`light.relayOff(relayIndex, callback)`

`light.getLabel(callback, [cache])`

`light.setLabel(label, [callback])`

`client.light(identifier)`

`client.lights([filter])`

`light-new`

`light-offline`

`light-online`

`client.startDiscovery()`

`client.stopDiscovery()`