tplink-lightbulb

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.

supported devices

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
KL130	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.

command-line

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

wireshark

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.

library

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'

API

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 ⇒ `EventEmitter`

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

info ⇒ `Promise`

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 ⇒ `Promise`

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

power ⇒ `Promise`

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

led ⇒ `Promise`

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

daystat ⇒ `Promise`

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

cloud ⇒ `Promise`

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

schedule ⇒ `Promise`

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

details ⇒ `Promise`

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 ⇒ `Promise`

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

encrypt ⇒ `Buffer`

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'))

decrypt ⇒ `Buffer`

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)

lachesis / tplink-lightbulb

tplink-lightbulb

related

supported devices

command-line

wireshark

library

API

scan ⇒ `EventEmitter`

info ⇒ `Promise`

send ⇒ `Promise`

power ⇒ `Promise`

led ⇒ `Promise`

daystat ⇒ `Promise`

cloud ⇒ `Promise`

schedule ⇒ `Promise`

details ⇒ `Promise`

reboot ⇒ `Promise`

encrypt ⇒ `Buffer`

decrypt ⇒ `Buffer`

About

Languages

tplink-lightbulb

related

supported devices

command-line

wireshark

library

API

scan ⇒ EventEmitter

info ⇒ Promise

send ⇒ Promise

power ⇒ Promise

led ⇒ Promise

daystat ⇒ Promise

cloud ⇒ Promise

schedule ⇒ Promise

details ⇒ Promise

reboot ⇒ Promise

encrypt ⇒ Buffer

decrypt ⇒ Buffer

About

Languages

scan ⇒ `EventEmitter`

info ⇒ `Promise`

send ⇒ `Promise`

power ⇒ `Promise`

led ⇒ `Promise`

daystat ⇒ `Promise`

cloud ⇒ `Promise`

schedule ⇒ `Promise`

details ⇒ `Promise`

reboot ⇒ `Promise`

encrypt ⇒ `Buffer`

decrypt ⇒ `Buffer`