Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    tplink-lightbulbpublic

    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.

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

    I have LB120, LB130, and HS105, so any testing (and packet-capture) with other devices would be greatly appreciated.

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

    daystatPromise

    Get schedule info

    cloudPromise

    Get cloud info from bulb

    schedulePromise

    Get schedule from bulb

    detailsPromise

    Get operational details from bulb

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

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

    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)

    development

    I use standard. You can auto-format your code with standard --fix and there's plugins for lots of editors.

    sound

    Kyle Dixon made a cool beat-match script for syncing lights to music.

    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.

    install

    npm i tplink-lightbulb

    Downloadslast 7 days

    41

    version

    1.4.1

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar