lifx-http-api

1.0.3 • Public • Published

Lifx HTTP Api Node.js Wrapper

NPM Version Dependency Status Build Status License MIT codecov.io

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

/lifx-http-api/

    Package Sidebar

    Install

    npm i lifx-http-api

    Weekly Downloads

    15

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • klarstil