lha
lifx-http-api
npm i lifx-http-api
lha

lifx-http-api

💡 Thin wrapper around the Lifx HTTP API (http://api.developer.lifx.com/)

by Stephan Pohl

1.0.3 (see all)License:MITTypeScript:Not Found
npm i lifx-http-api
Readme

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.

OptionTypeDefaultDescription
selectorstringSelector for the light bulb you want to get. See the Selector section to get more information.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
selectorstringSelector for the light bulb you want to get. See the Selector section to get more information.
settingsobject{}State configuration object. See the official documentation for further information.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
settingsMixed{}Multiple State configuration object. See the official documentation for further information.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
selectorstringallSelector for the light bulb you want to get. See the Selector section to get more information.
durationint0Turning on or off will be faded over the time (in seconds).
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
selectorstringallSelector for the light bulb you want to get. See the Selector section to get more information.
settingsObject{}Breathe effect object, see the official documentation for all available parameter.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
selectorstringallSelector for the light bulb you want to get. See the Selector section to get more information.
settingsObject{}Pulse effect object, see the official documentation for all available parameter.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
selectorstringallSelector for the light bulb you want to get. See the Selector section to get more information.
settingsObject{}Cycle states object, see the official documentation for all available parameter.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
selectorstringallScene selector. See the Selector section to get more information.
durationint0Fades to the scene (in seconds).
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
colorstringColor string you'd like to validate. See the Color section to get more information.
cbfunctionnullfunction(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.

OptionTypeDefaultDescription
versionstringAPI 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.

OptionTypeDefaultDescription
urlstringAPI 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.

OptionTypeDefaultDescription
tokenstringBearer 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.

OptionTypeDefaultDescription
settingsObject{}request configuration settings. See the offical documentation for further information.
cbfunctionnullfunction(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
});
No alternatives found
No tutorials found
Add a tutorial
No dependencies found

Rate & Review

100
No reviews found
Be the first to rate