lifx-http-api

Lifx HTTP Api Node.js Wrapper

A thin Node.js API wrapper of the Lifx HTTP protocol.

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

Installation

$ npm install lifx-http-api --save

Compatibility

Node.js 4.2.6+ is tested and supported on Mac, Linux and Windows.

Bearer Token

A bearer token is mandatory to use the API. A new token can be obtain in the Lifx Cloud Settings.

Usage

The thin API wrapper uses a client for network communication. This client handles all requests against the Lifx API.

var lifx = require('lifx-http-api'),
    client;
    
client = new lifx({
    bearerToken: '<your api token>'
});

The Client object provides promises by the great Q library. You can either use callbacks or promises.

// Using callbacks
client.listLights('all', function(err, data) {
    if(err) {
    	console.error(err);
    	return;
    }
    
    console.log(data)
});

// Using promises
client.listLights('all').then(console.log, console.error);

Getting lights and scenes

client.listLights(selector, [cb])

Gets lights belonging to the authenticated account. Filter the lights using selectors.

Option	Type	Default	Description
selector	string		Selector for the light bulb you want to get. See the Selector section to get more information.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.listLights('all', function(err, data) {
    if(err) {
    	console.error(err);
    	return;
    }
    
    console.log(data)
});

// Using promises
client.listLights('all').then(console.log, console.error);

Modifying light state

client.setState(selector, settings, [cb])

Sets the state of the lights within the selector.

Option	Type	Default	Description
selector	string		Selector for the light bulb you want to get. See the Selector section to get more information.
settings	object	{}	State configuration object. See the official documentation for further information.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.setState('all', {
	power: 'on',
	color: 'blue saturation:0.5',
	brightness: 0.5,
	duration: 5		
}, function(err, data) {
    if(err) {
    	console.error(err);
    	return;
    }
    
    console.log(data)
});

// Using promises
client.setState('all', {
	power: 'on',
	color: 'blue saturation:0.5',
	brightness: 0.5,
	duration: 5		
}).then(console.log, console.error);

client.setStates(settings, [cb])

This endpoint allows you to set different states on multiple selectors in a single request.

Option	Type	Default	Description
settings	Mixed	{}	Multiple State configuration object. See the official documentation for further information.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.setState('all', {
    "states": [ {
        "selector": "all",
        "power": "on"
    }, {
        "selector": "group:test",
        "brightness": 0.5
    } ],
    "defaults": {
        "duration": 5.0
    }
}, function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

client.togglePower(selector, [duration], [cb])

Turn off lights if they are on, or turn them on if they are off. Physically powered off lights are ignored.

Option	Type	Default	Description
selector	string	all	Selector for the light bulb you want to get. See the Selector section to get more information.
duration	int	0	Turning on or off will be faded over the time (in seconds).
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.togglePower('all', 1.5, function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

client.breathe(selector, [settings], [cb])

Performs a breathe effect by slowly fading between the given colors. Use the parameters to tweak the effect.

Option	Type	Default	Description
selector	string	all	Selector for the light bulb you want to get. See the Selector section to get more information.
settings	Object	{}	Breathe effect object, see the official documentation for all available parameter.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.breathe('all', {
    color: '#006633',
    from_color: '#00AF33',
    period: 1,
    cycles: 10,
    persist: true,
    power_on: true,
    peak: 0.8
}, function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

client.pulse(selector, [settings], [cb])

Performs a pulse effect by quickly flashing between the given colors. Use the parameters to tweak the effect.

Option	Type	Default	Description
selector	string	all	Selector for the light bulb you want to get. See the Selector section to get more information.
settings	Object	{}	Pulse effect object, see the official documentation for all available parameter.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.pulse('all', {
    color: '#006633',
    from_color: '#00AF33',
    period: 1,
    cycles: 10,
    persist: true,
    power_on: true,
    peak: 0.8
}, function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

client.cycle(selector, [settings], [cb])

Make the light(s) cycle to the next or previous state in a list of states.

Option	Type	Default	Description
selector	string	all	Selector for the light bulb you want to get. See the Selector section to get more information.
settings	Object	{}	Cycle states object, see the official documentation for all available parameter.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.cycle('all', {
    "states": [{
        "brightness": 1.0
    }, {
        "brightness": 0.5
    }, {
        "brightness": 0.1
    }, {
        "power": "off"
    }],
    "defaults": {
        "power": "on", // all states default to on
        "saturation": 0, // every state is white
        "duration": 2.0 // all transitions will be applied over 2 seconds
    }
}, function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

Working with scenes

client.listScenes([cb])

Lists all the scenes available in the users account.

Option	Type	Default	Description
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.listScene(function(err, data) {
    if(err) {
    	console.error(err);
    	return;
    }
    
    console.log(data)
});

// Using promises
client.listScenes().then(console.log, console.error);

client.activateScene(selector, [duration], [cb])

Activates a scene from the users account.

Option	Type	Default	Description
selector	string	all	Scene selector. See the Selector section to get more information.
duration	int	0	Fades to the scene (in seconds).
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.activateScene('scene_id:d073d501cf2c', 1.2, function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

Utility methods

client.validateColor(color, [cb])

This method lets you validate a user's color string and return the hue, saturation, brightness and kelvin values that the API will interpret as.

Option	Type	Default	Description
color	string		Color string you'd like to validate. See the Color section to get more information.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

// Using callbacks
client.validateColor('#0198E1', function (err, data) {
    if (err) {
        console.error(err);
        return;
    }

    console.log(data)
});

Client API

client.getVersion()

Returns the api version.

Usage example:

client.getVersion();  // outputs "v1"

client.setVersion(version)

Sets the api version. Returns true if the version was set sucessfully, otherwise false.

Option	Type	Default	Description
version	string		API version which will be used by the Client object.

Usage example:

client.setVersion('v2beta');

client.getUrl()

Returns the api url.

Usage example:

client.getUrl();  // outputs "https://lifx.com/api/"

client.setUrl(url)

Sets the api url. Returns true if the url was set sucessfully, otherwise false.

Option	Type	Default	Description
url	string		API url which will be used by the Client object.

Usage example:

client.setUrl('https://my-lifx-api-url.com');

client.getApiUrl()

Returns the full Lifx api endpoint

Usage example:

client.getApiUrl(); // outputs "https://lifx.com/api/v1"

client.getBearerToken()

Returns the bearer authentication token.

Usage example:

client.getBearerToken();  // outputs "<your-token>"

client.setBearerToken(token)

Sets the bearer authentication token. Returns true if the token was set sucessfully, otherwise false.

Option	Type	Default	Description
token	string		Bearer authentication token which will be used by the Client object.

Usage example:

client.setBearerToken('<your-token>');

client.send(settings, cb)

Sends a request to the Lifx API.

Option	Type	Default	Description
settings	Object	{}	request configuration settings. See the offical documentation for further information.
cb	function	null	function(err, data) {} Callback function which will be called when the HTTP request to the API was processed.

Usage example:

client.send({
    url: 'lights/all/state',
    body: {
        power: 'on',
        color: 'blue saturation:0.5',
        brightness: 0.5,
        duration: 5        
    },
    method: 'PUT'
}, function(err, data) {
    if (err) console.error(err);
    else console.log(data);
})

Client settings

The Client object can be configured at initialization:

var lifx = require('lifx-http-api'),
    client;
    
client = new lifx({
    bearerToken: '<your api token>',	// Authentication token
    version: 'v2beta',					// API version
    url: 'https://api.lifx.com'			// API endpoint
});