tplink-lightbulb

Control TP-Link smart lightbulbs from nodejs

This will allow you to control TP-Link smart lightbulbs from nodejs or the command-line. I have only tested with LB120 bulbs, and am eager to add support for more, so send a PR, or even just a pcap file of network traffic to add support for your lightbulb.

command-line

You can install it for your system with this:

npm i -g tplink-lightbulb

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:
  -?, --help  Show help                                                [boolean]

Examples:
  tplight scan -?     Get more detailed help with `scan` command
  tplight on -?       Get more detailed help with `on` command
  tplight off -?      Get more detailed help with `off` command
  tplight temp -?     Get more detailed help with `temp` command
  tplight hex -?      Get more detailed help with `hex` command
  tplight hsb -?      Get more detailed help with `hsb` command
  tplight cloud -?    Get more detailed help with `cloud` command
  tplight raw -?      Get more detailed help with `raw` command
  tplight details -?  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 Bulb = require('tplink-lightbulb')

or for ES6:

import Bulb from 'tplink-lightbulb'

API

scan ⇒ EventEmitter

Scan for lightbulbs on your network

info ⇒ Promise

Get info about the Bulb

send ⇒ Promise

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

set ⇒ Promise

Change 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

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	Only return devices with this class, (ie 'IOT.SMARTBULB')

Example

// turn first discovered light off
const scan = Bulb.scan()
  .on('light', light => {
    light.set(false)
      .then(status => {
        console.log(status)
        scan.stop()
      })
  })

info ⇒ Promise

Get info about the Bulb

Returns: Promise - Resolves to info
Example

// get info about a light
const light = new Bulb('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 Bulb('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 ⇒ Promise

Change state of lightbulb

Returns: Promise - Resolves to output of command

Param	Type	Description
power	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 Bulb('10.0.0.200')
light.set(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 Bulb('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 Bulb('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 Bulb('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 Bulb('10.0.0.200')
light.details()
  .then(details => {
    console.log(details)
  })
  .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 = Bulb.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 = Bulb.decrypt(encrypted)

thanks

Thanks to hs100-api to for some good ideas, and tplink-smartplug for a good start to a wireshark dissector and some good ideas. @DaveGut really helped with bulb-hacking and research on LB130's.