Have ideas to improve npm?Join in the discussion! »

    tplink-lightbulb

    1.6.3 • Public • Published

    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 wifi join
    LB100 X X X X X X X X
    LB120 X X X X X X X X
    LB130 X X X X X X X X X X
    HS100 X X X X X X
    HS105 X X X X X X
    HS110 X X X X X X
    HS200 X X X X X X
    KP100 X X X X X X
    LB200 X X X X X X X X
    LB230 X X X X X X X X X X
    KL110 X X X X X X
    KL120 X X X X X X X X
    KL130 X X 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:
      tplight scan                               Scan for lightbulbs
      tplight on <ip>                            Turn on lightbulb
      tplight off <ip>                           Turn off lightbulb
      tplight bright <ip> <brightness>           Set the brightness of the lightbulb
                                                (for those that support it)
      tplight temp <ip> <color>                  Set the color-temperature of the
                                                lightbulb (for those that support
                                                it)
      tplight hex <ip> <color>                   Set color of lightbulb using hex
                                                color (for those that support it)
      tplight hsb <ip> <hue> <saturation>        Set color of lightbulb using HSB
      <brightness>                              color (for those that support it)
      tplight cloud <ip>                         Get cloud info
      tplight raw <ip> <json>                    Send a raw JSON command
      tplight details <ip>                       Get details about the device
      tplight led <ip> <ledState>                Turn on/off LED indicator
      tplight wifi <ip>                          List available wifi for a particular
                                                device
      tplight join <ip> <SSID> [SECRET]          Configure the device to use these
                                                wifi settings
    
    Options:
      -h, --help     Show help                                             [boolean]
          --version  Show version number                                   [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
      tplight led -h      Get more detailed help with `led` command
      tplight wifi -h     Get more detailed help with `wifi` command
      tplight join -h     Get more detailed help with `join` 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

    listwifiPromise

    Scans the wifi networks in range of the device

    connectwifiPromise

    Connects the device to the access point in the parameters

    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

    namePromise

    Set the name 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()
          })
      })

    listwifi ⇒ Promise

    Scans the wifi networks in range of the device

    Returns: Promise - Resolves to output of command
    Example

    // scan for available wifi
    const light = new TPLSmartDevice('10.0.0.200')
    light.listwifi()
      .then(info => {
        console.log(info)
      })

    connectwifi ⇒ Promise

    Connects the device to the access point in the parameters

    Returns: Promise - Resolves to output of command

    Param Type Description
    ssid String Your wifi SSID
    password String Your wifi secret
    keyType Number The type of key (WPA 2 is 3, no key is 0)
    cypherType Number The type of cypher (WPA2 is 2)

    Example

    // command a device to join a wifi network
    const light = new TPLSmartDevice('10.0.0.200')
    light.connectwifi("SSID", "PASSWORD", 3, 2)
      .then(info => {
        console.log(info)
      })

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

    name ⇒ Promise

    Set the name of lightbulb

    Returns: Promise - Resolves to output of command

    Param Type
    newAlias String

    Example

    // change the name of a light
    const light = new TPLSmartDevice('10.0.0.200')
    light.name("New Name")
    .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)

    Install

    npm i tplink-lightbulb

    DownloadsWeekly Downloads

    43

    Version

    1.6.3

    License

    MIT

    Unpacked Size

    22.8 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar