/tplink-lightbulb

Control TP-Link smart lightbulbs from nodejs

Primary LanguageJavaScriptMIT LicenseMIT

tested with LB120

tplink-lightbulb

Control TP-Link smart-home devices from nodejs

NPM

This will allow you to control TP-Link smart-home devices from nodejs or the command-line.

related

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

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

scanEventEmitter

Scan for lightbulbs on your network

infoPromise

Get info about the TPLSmartDevice

sendPromise

Send a message to a lightbulb (for RAW JS message objects)

powerPromise

Set power-state of lightbulb

ledPromise

Set led-state of lightbulb

daystatPromise

Get schedule info

cloudPromise

Get cloud info from bulb

schedulePromise

Get schedule from bulb

detailsPromise

Get operational details from bulb

rebootPromise

Reboot the device

encryptBuffer

Badly encrypt message in format bulbs use

decryptBuffer

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)