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
});

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

klarstil / lifx-http-api

Programming Languages

Labels

Projects that are alternatives of or similar to lifx-http-api

Lifx HTTP Api Node.js Wrapper

Installation

Compatibility

Bearer Token

Usage

Getting lights and scenes

`client.listLights(selector, [cb])`

Modifying light state

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

`client.setStates(settings, [cb])`

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

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

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

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

Working with scenes

`client.listScenes([cb])`

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

Utility methods

`client.validateColor(color, [cb])`

Client API

`client.getVersion()`

`client.setVersion(version)`

`client.getUrl()`

`client.setUrl(url)`

`client.getApiUrl()`

`client.getBearerToken()`

`client.setBearerToken(token)`

`client.send(settings, cb)`

Client settings