Control TP-Link smart-home devices from nodejs
This will allow you to control TP-Link smart-home devices from nodejs or the command-line.
- If you want to use kasa (allows you to hit your tplink devices, on an external network) have a look at kasa_control.
- If you'd like to run a GraphQL server to control your lights, see tplink-graphql.
- If you like to see a demo web-app that uses react & websockets, see tpserver.
Not all TP-Link smart-home devices can do all things, here's the support-matrix:
| raw | details | on | off | temp | hex | hsb | cloud | |
|---|---|---|---|---|---|---|---|---|
| LB100 | X | X | X | X | X | X | ||
| LB120 | X | X | X | X | X | X | ||
| LB130 | X | X | X | X | X | X | X | X |
| HS100 | X | X | X | X | ||||
| HS105 | X | X | X | X | ||||
| HS110 | X | X | X | X | ||||
| HS200 | X | X | X | X | ||||
| KP100 | X | X | X | X | ||||
| LB200 | X | X | X | X | X | X | ||
| LB230 | X | X | X | X | X | X | X | X |
| KL110 | X | X | X | X | ||||
| KL120 | X | X | X | X | X | X | ||
| KL130 | X | X | X | X | X | X | X | X |
I have LB120, LB130, and HS105, so any testing (and packet-capture) with other devices would be greatly appreciated.
If you have nodejs installed, you can install it for your system with this:
npm i -g tplink-lightbulb
If you don't want to install nodejs, or just want the standalone-version, install a release for your system.
Now, you can use it like this:
Usage: tplight <COMMAND>
Commands:
scan Scan for lightbulbs
on <ip> Turn on lightbulb
off <ip> Turn off lightbulb
temp <ip> <color> Set the color-temperature of the
lightbulb (for those that support
it)
hex <ip> <color> Set color of lightbulb using hex
color (for those that support it)
hsb <ip> <hue> <saturation> <brightness> Set color of lightbulb using HSB
color (for those that support it)
cloud <ip> Get cloud info
raw <ip> <json> Send a raw JSON command
details <ip> Get details about the device
Options:
-h, --help Show help [boolean]
Examples:
tplight scan -h Get more detailed help with `scan` command
tplight on -h Get more detailed help with `on` command
tplight off -h Get more detailed help with `off` command
tplight temp -h Get more detailed help with `temp` command
tplight hex -h Get more detailed help with `hex` command
tplight hsb -h Get more detailed help with `hsb` command
tplight cloud -h Get more detailed help with `cloud` command
tplight raw -h Get more detailed help with `raw` command
tplight details -h Get more detailed help with `details` command
If you want to analyze the protocol, you can use the included tplink-smarthome.lua.
Install in the location listed in About Wireshark/Folders/Personal Plugins
I captured packets with tcpdump running on a raspberry pi pretending to be a router. In general, this is a really useful way to capture IOT protocols and mess around with them.
I ssh'd into my pi, ran sudo apt update && sudo apt install tcpdump, then tcpdump -i wlan0 -w lights.pcap
I connected the lights to that network (reset them to factory default by turning the power off/on 5 times, then configure in Kasa app.)
After I did stuff like switch the lights on/off in app, I open the pcap file in wireshark on my desktop.
You can install it in your project like this:
npm i -S tplink-lightbulb
Include it in your project like this:
const TPLSmartDevice = require('tplink-lightbulb')or for ES6:
import TPLSmartDevice from 'tplink-lightbulb'- scan ⇒
EventEmitter Scan for lightbulbs on your network
- info ⇒
Promise Get info about the TPLSmartDevice
- send ⇒
Promise Send a message to a lightbulb (for RAW JS message objects)
- power ⇒
Promise Set power-state of lightbulb
- led ⇒
Promise Set led-state of lightbulb
- daystat ⇒
Promise Get schedule info
- cloud ⇒
Promise Get cloud info from bulb
- schedule ⇒
Promise Get schedule from bulb
- details ⇒
Promise Get operational details from bulb
- reboot ⇒
Promise Reboot the device
- encrypt ⇒
Buffer Badly encrypt message in format bulbs use
- decrypt ⇒
Buffer Badly decrypt message from format bulbs use
Scan for lightbulbs on your network
Returns: EventEmitter - Emit light events when lightbulbs are found
| Param | Type | Description |
|---|---|---|
| filter | string |
[none] Only return devices with this class, (ie 'IOT.SMARTBULB') |
| broadcast | string |
['255.255.255.255'] Use this broadcast IP |
Example
// turn first discovered light off
const scan = TPLSmartDevice.scan()
.on('light', light => {
light.power(false)
.then(status => {
console.log(status)
scan.stop()
})
})Get info about the TPLSmartDevice
Returns: Promise - Resolves to info
Example
// get info about a light
const light = new TPLSmartDevice('10.0.0.200')
light.info()
.then(info => {
console.log(info)
})Send a message to a lightbulb (for RAW JS message objects)
Returns: Promise - Resolves with answer
| Param | Type | Description |
|---|---|---|
| msg | Object |
Message to send to bulb |
Example
const light = new TPLSmartDevice('10.0.0.200')
light.send({
'smartlife.iot.smartbulb.lightingservice': {
'transition_light_state': {
'on_off': 1,
'transition_period': 0
}
}})
.then(response => {
console.log(response)
})
.catch(e => console.error(e))Set power-state of lightbulb
Returns: Promise - Resolves to output of command
| Param | Type | Description |
|---|---|---|
| powerState | Boolean |
On or off |
| transition | Number |
Transition to new state in this time |
| options | Object |
Object containing mode, hue, saturation, color_temp, brightness |
Example
// turn a light on
const light = new TPLSmartDevice('10.0.0.200')
light.power(true)
.then(status => {
console.log(status)
})
.catch(err => console.error(err))Set led-state of lightbulb
Returns: Promise - Resolves to output of command
| Param | Type | Description |
|---|---|---|
| ledState | Boolean |
On or off |
Example
// turn the LED status light on
const light = new TPLSmartDevice('10.0.0.200')
light.led(true)
.then(status => {
console.log(status)
})
.catch(err => console.error(err))Get schedule info
Returns: Promise - Resolves to schedule info
| Param | Type | Description |
|---|---|---|
| month | Number |
Month to check: 1-12 |
| year | Number |
Full year to check: ie 2017 |
Example
// get the light's schedule for 1/2017
const light = new TPLSmartDevice('10.0.0.200')
light.schedule(1, 2017)
.then(schedule => {
console.log(schedule)
})
.catch(e => console.error(e))Get cloud info from bulb
Returns: Promise - Resolves to cloud info
Example
// get the cloud info for the light
const light = new TPLSmartDevice('10.0.0.200')
light.cloud()
.then(info => {
console.log(info)
})
.catch(e => console.error(e))Get schedule from bulb
Returns: Promise - Resolves to schedule info
Example
// get the bulb's schedule
const light = new TPLSmartDevice('10.0.0.200')
light.schedule()
.then(schedule => {
console.log(schedule)
})
.catch(e => console.error(e))Get operational details from bulb
Returns: Promise - Resolves to operational details
Example
// get some extra details about the light
const light = new TPLSmartDevice('10.0.0.200')
light.details()
.then(details => {
console.log(details)
})
.catch(e => console.error(e))Reboot the device
Returns: Promise - Resolves to output of command
Example
// get some extra details about the light
const light = new TPLSmartDevice('10.0.0.200')
light.reboot()
.then(status => {
console.log(status)
})
.catch(e => console.error(e))Badly encrypt message in format bulbs use
Returns: Buffer - Encrypted data
| Param | Type | Description |
|---|---|---|
| buffer | Buffer |
Buffer of data to encrypt |
| key | Number |
Encryption key (default is generally correct) |
Example
const encrypted = TPLSmartDevice.encrypt(Buffer.from('super secret text'))Badly decrypt message from format bulbs use
Returns: Buffer - Decrypted data
| Param | Type | Description |
|---|---|---|
| buffer | Buffer |
Buffer of data to decrypt |
| key | Number |
Encryption key (default is generally correct) |
Example
const decrypted = TPLSmartDevice.decrypt(encrypted)