lifx-node-wrapper
Node.js Lifx HTTP API Wrapper
Features
- Promise based REST API calls
- Easy access to API responses
- Supports most LIFX HTTP API endpoints (more to be added)
Installation
Install lifx-node-wrapper with npm:
$ npm install lifx-node-wrapper
To run this project, you will need a LIFX HTTP API key. Get your key here: https://api.developer.lifx.com/docs/authentication
Usage
Getting started
import Lifx from 'lifx-node-wrapper';
//create instance with our Lifx Token
var lifx = new Lifx(LIFX_KEY);
//lifx.<method> will now always use the key provided
Get list of all lights
Most functions require a selector
to determine which lights to control. To stay consistent and avoid the package breaking, the wrapper uses standard LIFX selectors laid out in their documentation.
var lights = await lifx.ListLights('all')
console.log(lights.data);
//OR
lifx.ListLights('all')
//grab returned data
.then(data => {
//handle data
console.log(data)
})
.catch(err =>
//handle errors
console.log(err)
);
Not using a parameter in a function
If you don't need a certain parameter, fill the spot with undefined
. Note: selector
and power
are required if they are part of the function.
lifx.SetState('group_id:6a2e3...', 'on', undefined, 6.0, undefined, true)
You do not have to list undefined
in every unused parameter.
lifx.SetState('group_id:6a2e3...', 'on')
API Reference
Get all items
lifx.ListLights()
Parameter | Type | Example | Description |
---|---|---|---|
selector |
string |
'all' | Required |
Returns all available lights and their unique selectors. It's recommended to use their unique ID's instead of names like "Living Room" since the ID's will never change.
Example response converted to JSON:
[
{
"id": "d07...949",
"uuid": "029...609d",
"label": "Office Light",
"connected": true,
"power": "off",
"color": {
"hue": 0,
"saturation": 0,
"kelvin": 2000
},
"brightness": 0.3,
"group": {
"id": "e1ad...537",
"name": "Office"
},
"location": {
"id": "fd599...08350",
"name": "Home"
},
"product": {
"name": "LIFX Mini Day and Dusk",
"identifier": "lifx_mini_day_and_dusk2",
"company": "LIFX",
"vendor_id": 1,
"product_id": 60,
"capabilities": {
"has_color": false,
"has_variable_color_temp": true,
"has_ir": false,
"has_hev": false,
"has_chain": false,
"has_matrix": false,
"has_multizone": false,
"min_kelvin": 1500,
"max_kelvin": 4000
}
},
"last_seen": "2022-06-19T02:50:56Z",
"seconds_since_seen": 0
}
]
lifx.SetState()
Parameter | Type | Example | Description |
---|---|---|---|
selector |
string |
'group_id:6a2e3b...' | Required |
power |
string |
'on' | Required |
color |
string |
||
brightness |
double |
0.1 | |
duration |
double |
1.0 | Defaults to 1.0 |
infared |
double |
'0.5' | |
fast |
boolean |
false | Defaults to false |
lifx.TogglePower()
Parameter | Type | Example | Description |
---|---|---|---|
selector |
string |
'id:3a9b0x...' | Required |
Turn off lights if any of them are on, or turn them on if they are all off.
lifx.ListScenes()
Lists all scenes associated with the API Key provided.
Example response converted to JSON:
[
{
"uuid": "1b3a...s3451",
"name": "Night Time",
"account": {
"uuid": "435dza...5182z"
},
"states": [
{
"selector": "id:d07...ee46",
"power": "on",
"brightness": 0.1297,
"color": {
"hue": 350.6141,
"saturation": 1,
"kelvin": 3500
}
}
],
"created_at": 1639715780,
"updated_at": 1652936342
}
]
lifx.ActivateScene()
Parameter | Type | Example | Description |
---|---|---|---|
selector |
string |
'scene_id:6a2e3b...' | Required |
duration |
double |
1.0 | Defaults to 1.0 |
ignore |
array |
This has not been tested | |
overrides |
array |
This has not been tested | |
fast |
boolean |
false | Defaults to false |
Examples
Turn on a group of lights over 10 seconds with fast mode enabled
lifx.SetState('group_id:6a2e3...', 'on', undefined, 10.0, undefined, true)
//OR
//Note: no response is given in fast mode
lifx.SetState('group_id:6a2e3...', 'on', undefined, 10.0, undefined, true)
.catch(err =>
//handle errors
);
Toggle all lights off/on
lifx.TogglePower('group_id:6a2e3...', 'on')
//OR
lifx.TogglePower('group_id:6a2e3...', 'on')
//grab returned data
.then(data => {
//handle data
})
.catch(err =>
//handle errors
);
Activate a scene that was previously set-up in the LIFX app
lifx.ActivateScene('scene_id:1c4d3c7...338fa9', 1.0)
//OR
lifx.ActivateScene('scene_id:1c4d3c7...338fa9', 1.0)
//grab returned data
.then(data => {
//handle data
})
.catch(err =>
//handle errors
);
Future Goals
-
Add remaining API Endpoints
-
Add additional error handling to improve usability
-
Implement automated tests / checks using jest
Related
Inspired by other related projects:
📖 Feedback
I wrote this wrapper to use in my personal project to control my apartments smart devices through a custom Telegram Bot. LIFX lights had several nodejs libraries available, but few were up to date.
My goal was to not only to reduce outside dependencies in my own projects, but also make the API easier to use for others.
Writing this wrapper introduced me to javascript prototypes, classes, publishing NPM packages, and exporting/importing ES modules. Now to update my Telegram Bot to support this module...
Any and all feedback is appreciated.