Giters

LLYRICZ / tplink-smarthome-api

TP-Link Smarthome WiFi API (formerly hs100-api)

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

tplink-smarthome-api

NPM Version Build Status codecov js-semistandard-style

TP-Link Smart Home API

Changelog

Supported Devices

Model Type
HS100, HS105, HS107, HS110, HS200, HS220, HS300 Plug
LB100, LB110, LB120, LB130, LB200, LB230 Bulb

Related Projects

Examples

See more examples.

const { Client } = require('tplink-smarthome-api');

const client = new Client();
const plug = client.getDevice({host: '10.0.1.2'}).then((device)=>{
  device.getSysInfo().then(console.log);
  device.setPowerState(true);
});

// Look for devices, log to console, and turn them on
client.startDiscovery().on('device-new', (device) => {
  device.getSysInfo().then(console.log);
  device.setPowerState(true);
});

CLI

Install the command line utility with npm install -g tplink-smarthome-api. Run tplink-smarthome-api --help for help.

API

Full API docs can be found here.

For functions that send commands, the last argument is SendOptions where you can set the transport ('tcp','udp') and timeout.

Functions that take more than 3 arguments are passed a single options object as the first argument (and if its a network commmand, SendOptions as the second.)

Client ⇐ EventEmitter

Client that sends commands to specified devices or discover devices on the local subnet.

  • Contains factory methods to create devices.
  • Events are emitted after #startDiscovery is called.

Kind: global class
Extends: EventEmitter

new Client(options)

Param Type Default Description
options Object
[options.defaultSendOptions] SendOptions
[options.defaultSendOptions.timeout] Number 10000 (ms)
[options.defaultSendOptions.transport] string "tcp" 'tcp' or 'udp'
[options.logLevel] string level for built in logger ['error','warn','info','debug','trace']

client.send(payload, host, [port], [sendOptions]) ⇒ Promise.<Object, Error>

Encrypts payload and sends to device.

  • If payload is not a string, it is JSON.stringify'd.
  • Promise fulfills with parsed JSON response.

Devices use JSON to communicate.
For Example:

  • If a device receives:
    • {"system":{"get_sysinfo":{}}}
  • It responds with:
    • {"system":{"get_sysinfo":{ err_code: 0, sw_ver: "1.0.8 Build 151113 Rel.24658", hw_ver: "1.0", ... }}}

All responses from device contain an err_code (0 is success).

Kind: instance method of Client

Param Type Default
payload Object | string
host string
[port] number 9999
[sendOptions] SendOptions

client.getSysInfo(host, [port], [sendOptions]) ⇒ Promise.<Object, Error>

Requests {system:{get_sysinfo:{}}} from device.

Kind: instance method of Client
Returns: Promise.<Object, Error> - parsed JSON response

Param Type Default
host string
[port] number 9999
[sendOptions] SendOptions

client.getBulb(deviceOptions) ⇒ Bulb

Creates Bulb object.

See Device constructor and Bulb constructor for valid options.

Kind: instance method of Client

Param Type Description
deviceOptions Object passed to Bulb constructor

client.getPlug(deviceOptions) ⇒ Plug

Creates Plug object.

See Device constructor and Plug constructor for valid options.

Kind: instance method of Client

Param Type Description
deviceOptions Object passed to Plug constructor

client.getDevice(deviceOptions, [sendOptions]) ⇒ Promise.<(Plug|Bulb), Error>

Creates a Plug or Bulb after querying device to determine type.

See Device constructor, Bulb constructor, Plug constructor for valid options.

Kind: instance method of Client

Param Type Description
deviceOptions Object passed to Device constructor
[sendOptions] SendOptions

client.getCommonDevice(deviceOptions) ⇒ Device

Create Device object.

  • Device object only supports common Device methods.
  • See Device constructor for valid options.
  • Instead use #getDevice to create a fully featured object.

Kind: instance method of Client

Param Type Description
deviceOptions Object passed to Device constructor

client.getDeviceFromSysInfo(sysInfo, deviceOptions) ⇒ Plug | Bulb

Creates device corresponding to the provided sysInfo.

See Device constructor, Bulb constructor, Plug constructor for valid options

Kind: instance method of Client

Param Type Description
sysInfo Object
deviceOptions Object passed to device constructor

client.getTypeFromSysInfo(sysInfo) ⇒ string

Guess the device type from provided sysInfo.

Based on sys_info.[type|mic_type]

Kind: instance method of Client
Returns: string - 'plug','bulb','device'

Param Type
sysInfo Object

client.startDiscovery(options) ⇒ Client

Discover TP-Link Smarthome devices on the network.

  • Sends a discovery packet (via UDP) to the broadcast address every discoveryInterval(ms).
  • Stops discovery after discoveryTimeout(ms) (if 0, runs until #stopDiscovery is called).
    • If a device does not respond after offlineTolerance number of attempts, event:Client#device-offline is emitted.
  • If deviceTypes are specified only matching devices are found.
  • If macAddresses are specified only devices with matching MAC addresses are found.
  • If excludeMacAddresses are specified devices with matching MAC addresses are excluded.
  • if filterCallback is specified only devices where the callback returns a truthy value are found.
  • If devices are specified it will attempt to contact them directly in addition to sending to the broadcast address.
    • devices are specified as an array of [{host, [port: 9999]}].

Kind: instance method of Client
Returns: Client - this
Emits: error, device-new, device-online, device-offline, bulb-new, bulb-online, bulb-offline, plug-new, plug-online, plug-offline

Param Type Default Description
options Object
[options.address] string address to bind udp socket
[options.port] number port to bind udp socket
[options.broadcast] string "255.255.255.255" broadcast address
[options.discoveryInterval] number 10000 (ms)
[options.discoveryTimeout] number 0 (ms)
[options.offlineTolerance] number 3 # of consecutive missed replies to consider offline
[options.deviceTypes] Array.<string> 'plug','bulb'
[options.macAddresses] Array.<string> MAC will be normalized, comparison will be done after removing special characters (:,-, etc.) and case insensitive, glob style *, and ? in pattern are supported
[options.excludeMacAddresses] Array.<string> MAC will be normalized, comparison will be done after removing special characters (:,-, etc.) and case insensitive, glob style *, and ? in pattern are supported
[options.filterCallback] function called with fn(sysInfo), return truthy value to include device
[options.breakoutChildren] boolean true if device has multiple outlets, create a separate plug for each outlet, otherwise create a plug for the main device
[options.deviceOptions] Object {} passed to device constructors
[options.devices] Array.<Object> known devices to query instead of relying on broadcast

client.stopDiscovery()

Stops discovery and closes UDP socket.

Kind: instance method of Client

"device-new"

First response from device.

Kind: event emitted by Client
Properties

Type
Device | Bulb | Plug

"device-online"

Follow up response from device.

Kind: event emitted by Client
Properties

Type
Device | Bulb | Plug

"device-offline"

No response from device.

Kind: event emitted by Client
Properties

Type
Device | Bulb | Plug

"bulb-new"

First response from Bulb.

Kind: event emitted by Client
Properties

Type
Bulb

"bulb-online"

Follow up response from Bulb.

Kind: event emitted by Client
Properties

Type
Bulb

"bulb-offline"

No response from Bulb.

Kind: event emitted by Client
Properties

Type
Bulb

"plug-new"

First response from Plug.

Kind: event emitted by Client
Properties

Type
Plug

"plug-online"

Follow up response from Plug.

Kind: event emitted by Client
Properties

Type
Plug

"plug-offline"

No response from Plug.

Kind: event emitted by Client
Properties

Type
Plug

"discovery-invalid"

Invalid/Unknown response from device.

Kind: event emitted by Client
Properties

Name Type
rinfo Object
response Buffer
decryptedResponse Buffer

"error"

Error during discovery.

Kind: event emitted by Client
Properties

Type
Error

Bulb ⇐ Device

Bulb Device.

TP-Link models: LB100, LB110, LB120, LB130.

Kind: global class
Extends: Device, EventEmitter
Emits: lightstate-on, lightstate-off, lightstate-change, lightstate-update, emeter-realtime-update

new Bulb(options)

Created by Client - Do not instantiate directly.

See Device constructor for common options.

Param Type
options Object

bulb.cloud

Kind: instance property of Bulb

cloud.getInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's TP-Link cloud info.

Requests cloud.get_info. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

cloud.bind(username, password, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Add device to TP-Link cloud.

Sends cloud.bind command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
username string
password string
[sendOptions] SendOptions

cloud.unbind([sendOptions]) ⇒ Promise.<Object, ResponseError>

Remove device from TP-Link cloud.

Sends cloud.unbind command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

cloud.getFirmwareList([sendOptions]) ⇒ Promise.<Object, ResponseError>

Get device's TP-Link cloud firmware list.

Sends cloud.get_intl_fw_list command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

cloud.setServerUrl(server, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sets device's TP-Link cloud server URL.

Sends cloud.set_server_url command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
server string URL
[sendOptions] SendOptions

bulb.emeter

Kind: instance property of Bulb

emeter.realtime ⇒ Object

Returns cached results from last retrieval of emeter.get_realtime.

Kind: instance property of emeter

emeter.getRealtime([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's current energy stats.

Requests emeter.get_realtime. Older devices return current, voltage, etc, while newer devices return current_ma, voltage_mv etc This will return a normalized response including both old and new style properies for backwards compatibility. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

emeter.getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Daily Emeter Statisics.

Sends emeter.get_daystat command. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
month number
[sendOptions] SendOptions

emeter.getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Monthly Emeter Statisics.

Sends emeter.get_monthstat command. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
[sendOptions] SendOptions

emeter.eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

Erase Emeter Statistics.

Sends emeter.erase_runtime_stat command. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

bulb.lighting

Kind: instance property of Bulb

lighting.lightState ⇒ Object

Returns cached results from last retrieval of lightingservice.get_light_state.

Kind: instance property of lighting

lighting.getLightState([sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Bulb light state.

Requests lightingservice.get_light_state.

Kind: instance method of lighting
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

lighting.setLightState(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Sets Bulb light state (on/off, brightness, color, etc).

Sends lightingservice.transition_light_state command.

Kind: instance method of lighting

Param Type Default Description
options Object
[options.transition_period] number (ms)
[options.on_off] boolean
[options.mode] string
[options.hue] number 0-360
[options.saturation] number 0-100
[options.brightness] number 0-100
[options.color_temp] number Kelvin (LB120:2700-6500 LB130:2500-9000)
[options.ignore_default] boolean true
[sendOptions] SendOptions

bulb.schedule

Kind: instance property of Bulb

schedule.getNextAction([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Next Schedule Rule Action.

Requests schedule.get_next_action. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

schedule.getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Schedule Rules.

Requests schedule.get_rules. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

schedule.getRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Schedule Rule.

Requests schedule.get_rules and return rule matching Id. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response of rule

Param Type
id string
[sendOptions] SendOptions

schedule.addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Adds Schedule rule.

Sends schedule.add_rule command and returns rule id.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
options.lightState Object
options.start Date | number Date or number of minutes
[options.daysOfWeek] Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.name] string
[options.enable] boolean true
[sendOptions] SendOptions

schedule.editRule([sendOptions]) ⇒ Promise.<Object, ResponseError>

Edits Schedule rule.

Sends schedule.edit_rule command and returns rule id.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options.id string
options.lightState Object
options.start Date | number Date or number of minutes
[options.daysOfWeek] Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.name] string [description]
[options.enable] boolean true
[sendOptions] SendOptions

schedule.deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Deletes All Schedule Rules.

Sends schedule.delete_all_rules command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

schedule.deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Deletes Schedule Rule.

Sends schedule.delete_rule command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
id string
[sendOptions] SendOptions

schedule.setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Enables or Disables Schedule Rules.

Sends schedule.set_overall_enable command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
enable boolean
[sendOptions] SendOptions

schedule.getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Daily Usage Statisics.

Sends schedule.get_daystat command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
month number
[sendOptions] SendOptions

schedule.getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Monthly Usage Statisics.

Sends schedule.get_monthstat command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
[sendOptions] SendOptions

schedule.eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

Erase Usage Statistics.

Sends schedule.erase_runtime_stat command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

bulb.time

Kind: instance property of Bulb

time.getTime([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's time.

Requests timesetting.get_time. Does not support ChildId.

Kind: instance method of time
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

time.getTimezone([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's timezone.

Requests timesetting.get_timezone. Does not support ChildId.

Kind: instance method of time
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

bulb.sysInfo ⇒ Object

Returns cached results from last retrieval of system.sys_info.

Kind: instance property of Bulb
Overrides: sysInfo
Returns: Object - system.sys_info

bulb.supportsBrightness ⇒ boolean

Cached value of sys_info.is_dimmable === 1

Kind: instance property of Bulb

bulb.supportsColor ⇒ boolean

Cached value of sys_info.is_color === 1

Kind: instance property of Bulb

bulb.supportsColorTemperature ⇒ boolean

Cached value of sys_info.is_variable_color_temp === 1

Kind: instance property of Bulb

bulb.getColorTemperatureRange ⇒ Object

Returns array with min and max supported color temperatures

Kind: instance property of Bulb
Returns: Object - range

bulb.alias ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Bulb
Overrides: alias

bulb.id ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Bulb

bulb.deviceId ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Bulb

bulb.description ⇒ string

Cached value of sys_info.[description|dev_name].

Kind: instance property of Bulb

bulb.model ⇒ string

Cached value of sys_info.model.

Kind: instance property of Bulb

bulb.name ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Bulb

bulb.type ⇒ string

Cached value of sys_info.[type|mic_type].

Kind: instance property of Bulb

bulb.deviceType ⇒ string

Type of device (or device if unknown).

Based on cached value of sys_info.[type|mic_type]

Kind: instance property of Bulb
Returns: string - 'plub'|'bulb'|'device'

bulb.softwareVersion ⇒ string

Cached value of sys_info.sw_ver.

Kind: instance property of Bulb

bulb.hardwareVersion ⇒ string

Cached value of sys_info.hw_ver.

Kind: instance property of Bulb

bulb.mac ⇒ string

Cached value of sys_info.[mac|mic_mac|ethernet_mac].

Kind: instance property of Bulb

bulb.macNormalized ⇒ string

Normalized cached value of sys_info.[mac|mic_mac|ethernet_mac]

Removes all non alphanumeric characters and makes uppercase aa:bb:cc:00:11:22 will be normalized to AABBCC001122

Kind: instance property of Bulb

bulb.getInfo([sendOptions]) ⇒ Promise.<Object, Error>

Requests common Bulb status details in a single request.

  • system.get_sysinfo
  • cloud.get_sysinfo
  • emeter.get_realtime
  • schedule.get_next_action

Kind: instance method of Bulb
Returns: Promise.<Object, Error> - parsed JSON response

Param Type
[sendOptions] SendOptions

bulb.getPowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Gets on/off state of Bulb.

Requests lightingservice.get_light_state and returns true if on_off === 1.

Kind: instance method of Bulb

Param Type
[sendOptions] SendOptions

bulb.setPowerState(value, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Sets on/off state of Bulb.

Sends lightingservice.transition_light_state command with on_off value.

Kind: instance method of Bulb

Param Type Description
value boolean true: on, false: off
[sendOptions] SendOptions

bulb.togglePowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Toggles state of Bulb.

Requests lightingservice.get_light_state sets the power state to the opposite of on_off === 1 and returns the new power state.

Kind: instance method of Bulb

Param Type
[sendOptions] SendOptions

bulb.send(payload, [sendOptions]) ⇒ Promise.<Object, Error>

Sends payload to device (using send)

Kind: instance method of Bulb
Returns: Promise.<Object, Error> - parsed JSON response

Param Type
payload Object | string
[sendOptions] SendOptions

bulb.sendCommand(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sends command(s) to device.

Calls #send and processes the response.

  • Adds context.child_ids:[] to the command.

    • If childIds parameter is set. or
    • If device was instantiated with a childId it will default to that value.

  • If only one operation was sent:

    • Promise fulfills with specific parsed JSON response for command.
      Example: {system:{get_sysinfo:{}}}
      • resolves to: {err_code:0,...}\
      • instead of: {system:{get_sysinfo:{err_code:0,...}}} (as #send would)

  • If more than one operation was sent:

    • Promise fulfills with full parsed JSON response (same as #send)

Also, the response's err_code(s) are checked, if any are missing or != 0 the Promise is rejected with ResponseError.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
command Object | string
[childIds] Array.<string> | string
[sendOptions] SendOptions

bulb.sendCommandWithChildren(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>

Adds context.child_ids:[] to the command and sends via #sendCommand.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
command Object | string
[childIds] Array.<string> | string
[sendOptions] SendOptions

bulb.startPolling(interval) ⇒ Device | Bulb | Plug

Polls the device every interval.

Returns this (for chaining) that emits events based on state changes. Refer to specific device sections for event details.

Kind: instance method of Bulb
Returns: Device | Bulb | Plug - this

Param Type Description
interval number (ms)

bulb.stopPolling()

Stops device polling.

Kind: instance method of Bulb

bulb.getSysInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's SysInfo.

Requests system.sys_info from device. Does not support childId.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

bulb.setAlias(alias, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Change device's alias (name).

Sends system.set_dev_alias command. Supports childId.

Kind: instance method of Bulb

Param Type
alias string
[sendOptions] SendOptions

bulb.setLocation(latitude, longitude, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Set device's location.

Sends system.set_dev_location command. Does not support childId.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
latitude number
longitude number
[sendOptions] SendOptions

bulb.getModel([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's model.

Requests system.sys_info and returns model name. Does not support childId.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

bulb.reboot(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Reboot device.

Sends system.reboot command. Does not support childId.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
delay number
[sendOptions] SendOptions

bulb.reset(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Reset device.

Sends system.reset command. Does not support childId.

Kind: instance method of Bulb
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
delay number
[sendOptions] SendOptions

"emeter-realtime-update"

Bulb's Energy Monitoring Details were updated from device. Fired regardless if status was changed.

Kind: event emitted by Bulb
Properties

Name Type Description
value Object emeterRealtime

"lightstate-on"

Bulb was turned on (lightstate.on_off).

Kind: event emitted by Bulb
Properties

Name Type Description
value Object lightstate

"lightstate-off"

Bulb was turned off (lightstate.on_off).

Kind: event emitted by Bulb
Properties

Name Type Description
value Object lightstate

"lightstate-change"

Bulb's lightstate was changed.

Kind: event emitted by Bulb
Properties

Name Type Description
value Object lightstate

"lightstate-update"

Bulb's lightstate state was updated from device. Fired regardless if status was changed.

Kind: event emitted by Bulb
Properties

Name Type Description
value Object lightstate

Plug ⇐ Device

Plug Device.

TP-Link models: HS100, HS105, HS107, HS110, HS200, HS210, HS220, HS300.

Models with multiple outlets (HS107, HS300) will have a children property. If Plug is instantiated with a childId it will control the outlet associated with that childId. Some functions only apply to the entire device, and are noted below.

Emits events after device status is queried, such as #getSysInfo and #getEmeterRealtime.

Kind: global class
Extends: Device, EventEmitter
Emits: power-on, power-off, power-update, in-use, not-in-use, in-use-update, emeter-realtime-update

new Plug(options)

Created by Client - Do not instantiate directly.

See Device constructor for common options.

Param Type Default Description
options Object
[options.inUseThreshold] number 0.1 Watts
[options.childId] string If passed an integer or string between 0 and 99 it will prepend the deviceId

plug.away

Kind: instance property of Plug

away.getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Away Rules.

Requests anti_theft.get_rules. Support childId.

Kind: instance method of away
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

away.addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Adds Away Rule.

Sends anti_theft.add_rule command and returns rule id. Support childId.

Kind: instance method of away
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
options.start Date | number Date or number of minutes
options.end Date | number Date or number of minutes (only time component of date is used)
options.daysOfWeek Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.frequency] number 5
[options.name] string
[options.enable] boolean true
[sendOptions] SendOptions

away.editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Edits Away rule.

Sends anti_theft.edit_rule command and returns rule id. Support childId.

Kind: instance method of away
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
options.id string
options.start Date | number Date or number of minutes
options.end Date | number Date or number of minutes (only time component of date is used)
options.daysOfWeek Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.frequency] number 5
[options.name] string
[options.enable] boolean true
[sendOptions] SendOptions

away.deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Deletes All Away Rules.

Sends anti_theft.delete_all_rules command. Support childId.

Kind: instance method of away
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

away.deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Deletes Away Rule.

Sends anti_theft.delete_rule command. Support childId.

Kind: instance method of away
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
id string
[sendOptions] SendOptions

away.setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Enables or Disables Away Rules.

Sends anti_theft.set_overall_enable command. Support childId.

Kind: instance method of away
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
enable boolean
[sendOptions] SendOptions

plug.cloud

Kind: instance property of Plug

cloud.getInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's TP-Link cloud info.

Requests cloud.get_info. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

cloud.bind(username, password, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Add device to TP-Link cloud.

Sends cloud.bind command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
username string
password string
[sendOptions] SendOptions

cloud.unbind([sendOptions]) ⇒ Promise.<Object, ResponseError>

Remove device from TP-Link cloud.

Sends cloud.unbind command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

cloud.getFirmwareList([sendOptions]) ⇒ Promise.<Object, ResponseError>

Get device's TP-Link cloud firmware list.

Sends cloud.get_intl_fw_list command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

cloud.setServerUrl(server, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sets device's TP-Link cloud server URL.

Sends cloud.set_server_url command. Does not support childId.

Kind: instance method of cloud
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
server string URL
[sendOptions] SendOptions

plug.dimmer

Kind: instance property of Plug

dimmer.setBrightness(brightness, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sets Plug to the specified brightness.

Sends dimmer.set_brightness command. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
brightness Boolean 0-100
[sendOptions] SendOptions

dimmer.getDefaultBehavior([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Get Plug/Dimmer default behavior configuration.

Requests dimmer.get_default_behavior. Does not support childId.

Kind: instance method of dimmer

Param Type
[sendOptions] SendOptions

dimmer.getDimmerParameters([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Get Plug/Dimmer parameters configuration.

Requests dimmer.get_dimmer_parameters. Does not support childId.

Kind: instance method of dimmer

Param Type
[sendOptions] SendOptions

dimmer.setDimmerTransition(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Transitions Plug to the specified brightness.

Sends dimmer.set_dimmer_transition command. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
options Object
[options.brightness] Boolean 0-100
[options.mode] number "gentle_on_off", etc.
[options.duration] number duration in seconds
[sendOptions] SendOptions

dimmer.setDoubleClickAction(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Set Plug/Dimmer default_behavior configuration for double_click.

Sends dimmer.set_double_click_action. Does not support childId.

Kind: instance method of dimmer

Param Type
options Object
[options.mode] string
[options.index] number
[sendOptions] SendOptions

dimmer.setFadeOffTime(duration, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Set Plug dimmer_parameters for fadeOffTime.

Sends dimmer.set_fade_off_time. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
duration number duration in ms
[sendOptions] SendOptions

dimmer.setFadeOnTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Set Plug dimmer_parameters for fadeOnTime.

Sends dimmer.set_fade_on_time. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
fadeTime number duration in ms
[sendOptions] SendOptions

dimmer.setGentleOffTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Set Plug dimmer_parameters for gentleOffTime.

Sends dimmer.set_gentle_off_time. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
fadeTime number duration in ms
[sendOptions] SendOptions

dimmer.setGentleOnTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Set Plug dimmer_parameters for gentleOnTime.

Sends dimmer.set_gentle_on_time. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
fadeTime number duration in ms
[sendOptions] SendOptions

dimmer.setLongPressAction(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Set Plug/Dimmer default_behavior configuration for long_press.

Sends dimmer.set_long_press_action. Does not support childId.

Kind: instance method of dimmer

Param Type
options Object
[options.mode] string
[options.index] number
[sendOptions] SendOptions

dimmer.setSwitchState(state, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sets Plug to the specified on/off state.

Sends dimmer.set_switch_state command. Does not support childId.

Kind: instance method of dimmer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
state Boolean true=on, false=off
[sendOptions] SendOptions

plug.emeter

Kind: instance property of Plug

emeter.realtime ⇒ Object

Returns cached results from last retrieval of emeter.get_realtime.

Kind: instance property of emeter

emeter.getRealtime([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's current energy stats.

Requests emeter.get_realtime. Older devices return current, voltage, etc, while newer devices return current_ma, voltage_mv etc This will return a normalized response including both old and new style properies for backwards compatibility. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

emeter.getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Daily Emeter Statisics.

Sends emeter.get_daystat command. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
month number
[sendOptions] SendOptions

emeter.getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Monthly Emeter Statisics.

Sends emeter.get_monthstat command. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
[sendOptions] SendOptions

emeter.eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

Erase Emeter Statistics.

Sends emeter.erase_runtime_stat command. Supports childId.

Kind: instance method of emeter
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.schedule

Kind: instance property of Plug

schedule.getNextAction([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Next Schedule Rule Action.

Requests schedule.get_next_action. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

schedule.getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Schedule Rules.

Requests schedule.get_rules. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

schedule.getRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets Schedule Rule.

Requests schedule.get_rules and return rule matching Id. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response of rule

Param Type
id string
[sendOptions] SendOptions

schedule.addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Adds Schedule rule.

Sends schedule.add_rule command and returns rule id.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
[options.powerState] boolean
[options.dimmer] Object dimmer data (dimmable plugs only)
options.start Date | number Date or number of minutes
[options.daysOfWeek] Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.name] string
[options.enable] boolean true
[sendOptions] SendOptions

schedule.editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Edits Schedule rule.

Sends schedule.edit_rule command and returns rule id.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
options.id string
[options.powerState] boolean
[options.dimmer] Object dimmer data (dimmable plugs only)
options.start Date | number Date or number of minutes
[options.daysOfWeek] Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.name] string [description]
[options.enable] boolean true
[sendOptions] SendOptions

schedule.deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Deletes All Schedule Rules.

Sends schedule.delete_all_rules command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

schedule.deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Deletes Schedule Rule.

Sends schedule.delete_rule command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
id string
[sendOptions] SendOptions

schedule.setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Enables or Disables Schedule Rules.

Sends schedule.set_overall_enable command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
enable boolean
[sendOptions] SendOptions

schedule.getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Daily Usage Statisics.

Sends schedule.get_daystat command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
month number
[sendOptions] SendOptions

schedule.getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Monthly Usage Statisics.

Sends schedule.get_monthstat command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
year number
[sendOptions] SendOptions

schedule.eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

Erase Usage Statistics.

Sends schedule.erase_runtime_stat command. Supports childId.

Kind: instance method of schedule
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.time

Kind: instance property of Plug

time.getTime([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's time.

Requests timesetting.get_time. Does not support ChildId.

Kind: instance method of time
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

time.getTimezone([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's timezone.

Requests timesetting.get_timezone. Does not support ChildId.

Kind: instance method of time
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.timer

Kind: instance property of Plug

timer.getRules([childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Countdown Timer Rule (only one allowed).

Requests count_down.get_rules. Supports childId.

Kind: instance method of timer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Description
[childIds] Array.<string> | string | Array.<number> | number for multi-outlet devices, which outlet(s) to target
[sendOptions] SendOptions

timer.addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Add Countdown Timer Rule (only one allowed).

Sends count_down.add_rule command. Supports childId.

Kind: instance method of timer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
options.delay number delay in seconds
options.powerState boolean turn on or off device
[options.name] string "'timer'" rule name
[options.enable] boolean true rule enabled
[options.deleteExisting] boolean true send delete_all_rules command before adding
[sendOptions] SendOptions

timer.editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Edit Countdown Timer Rule (only one allowed).

Sends count_down.edit_rule command. Supports childId.

Kind: instance method of timer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type Default Description
options Object
options.id string rule id
options.delay number delay in seconds
options.powerState number turn on or off device
[options.name] string "'timer'" rule name
[options.enable] Boolean true rule enabled
[sendOptions] SendOptions

timer.deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

Delete Countdown Timer Rule (only one allowed).

Sends count_down.delete_all_rules command. Supports childId.

Kind: instance method of timer
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.sysInfo ⇒ Object

Returns cached results from last retrieval of system.sys_info.

Kind: instance property of Plug
Overrides: sysInfo
Returns: Object - system.sys_info

plug.children ⇒ Map

Returns children as a map keyed by childId. From cached results from last retrieval of system.sys_info.children.

Kind: instance property of Plug
Returns: Map - children

plug.childId ⇒ string

Returns childId.

Kind: instance property of Plug
Returns: string - childId

plug.alias ⇒ string

Cached value of sys_info.alias or sys_info.children[childId].alias if childId set.

Kind: instance property of Plug
Overrides: alias

plug.id ⇒ string

Cached value of sys_info.deviceId or childId if set.

Kind: instance property of Plug
Overrides: id

plug.inUse ⇒ boolean

Determines if device is in use based on cached emeter.get_realtime results.

If device supports energy monitoring (e.g. HS110): power > inUseThreshold. inUseThreshold is specified in Watts

Otherwise fallback on relay state: relay_state === 1 or sys_info.children[childId].state === 1.

Supports childId.

Kind: instance property of Plug

plug.relayState ⇒ boolean

Cached value of sys_info.relay_state === 1 or sys_info.children[childId].state === 1. Supports childId.

Kind: instance property of Plug
Returns: boolean - On (true) or Off (false)

plug.supportsDimmer ⇒ boolean

Cached value of sys_info.brightness != null

Kind: instance property of Plug

plug.deviceId ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Plug

plug.description ⇒ string

Cached value of sys_info.[description|dev_name].

Kind: instance property of Plug

plug.model ⇒ string

Cached value of sys_info.model.

Kind: instance property of Plug

plug.name ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Plug

plug.type ⇒ string

Cached value of sys_info.[type|mic_type].

Kind: instance property of Plug

plug.deviceType ⇒ string

Type of device (or device if unknown).

Based on cached value of sys_info.[type|mic_type]

Kind: instance property of Plug
Returns: string - 'plub'|'bulb'|'device'

plug.softwareVersion ⇒ string

Cached value of sys_info.sw_ver.

Kind: instance property of Plug

plug.hardwareVersion ⇒ string

Cached value of sys_info.hw_ver.

Kind: instance property of Plug

plug.mac ⇒ string

Cached value of sys_info.[mac|mic_mac|ethernet_mac].

Kind: instance property of Plug

plug.macNormalized ⇒ string

Normalized cached value of sys_info.[mac|mic_mac|ethernet_mac]

Removes all non alphanumeric characters and makes uppercase aa:bb:cc:00:11:22 will be normalized to AABBCC001122

Kind: instance property of Plug

plug.getInfo([sendOptions]) ⇒ Promise.<Object, Error>

Requests common Plug status details in a single request.

  • system.get_sysinfo
  • cloud.get_sysinfo
  • emeter.get_realtime
  • schedule.get_next_action

Supports childId.

Kind: instance method of Plug
Returns: Promise.<Object, Error> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.getInUse([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Same as #inUse, but requests current emeter.get_realtime. Supports childId.

Kind: instance method of Plug

Param Type
[sendOptions] SendOptions

plug.getLedState([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Get Plug LED state (night mode).

Requests system.sys_info and returns true if led_off === 0. Does not support childId.

Kind: instance method of Plug
Returns: Promise.<boolean, ResponseError> - LED State, true === on

Param Type
[sendOptions] SendOptions

plug.setLedState(value, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Turn Plug LED on/off (night mode). Does not support childId.

Sends system.set_led_off command.

Kind: instance method of Plug

Param Type Description
value boolean LED State, true === on
[sendOptions] SendOptions

plug.getPowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Get Plug relay state (on/off).

Requests system.get_sysinfo and returns true if On. Calls #relayState. Supports childId.

Kind: instance method of Plug

Param Type
[sendOptions] SendOptions

plug.setPowerState(value, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Turns Plug relay on/off.

Sends system.set_relay_state command. Supports childId.

Kind: instance method of Plug

Param Type
value boolean
[sendOptions] SendOptions

plug.togglePowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>

Toggles Plug relay state.

Requests system.get_sysinfo sets the power state to the opposite relay_state === 1 and returns the new power state. Supports childId.

Kind: instance method of Plug

Param Type
[sendOptions] SendOptions

plug.blink([times], [rate], [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Blink Plug LED.

Sends system.set_led_off command alternating on and off number of times at rate, then sets the led to its pre-blink state. Does not support childId.

Note: system.set_led_off is particulally slow, so blink rate is not guaranteed.

Kind: instance method of Plug

Param Type Default
[times] number 5
[rate] number 1000
[sendOptions] SendOptions

plug.send(payload, [sendOptions]) ⇒ Promise.<Object, Error>

Sends payload to device (using send)

Kind: instance method of Plug
Returns: Promise.<Object, Error> - parsed JSON response

Param Type
payload Object | string
[sendOptions] SendOptions

plug.sendCommand(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sends command(s) to device.

Calls #send and processes the response.

  • Adds context.child_ids:[] to the command.

    • If childIds parameter is set. or
    • If device was instantiated with a childId it will default to that value.

  • If only one operation was sent:

    • Promise fulfills with specific parsed JSON response for command.
      Example: {system:{get_sysinfo:{}}}
      • resolves to: {err_code:0,...}\
      • instead of: {system:{get_sysinfo:{err_code:0,...}}} (as #send would)

  • If more than one operation was sent:

    • Promise fulfills with full parsed JSON response (same as #send)

Also, the response's err_code(s) are checked, if any are missing or != 0 the Promise is rejected with ResponseError.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
command Object | string
[childIds] Array.<string> | string
[sendOptions] SendOptions

plug.sendCommandWithChildren(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>

Adds context.child_ids:[] to the command and sends via #sendCommand.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
command Object | string
[childIds] Array.<string> | string
[sendOptions] SendOptions

plug.startPolling(interval) ⇒ Device | Bulb | Plug

Polls the device every interval.

Returns this (for chaining) that emits events based on state changes. Refer to specific device sections for event details.

Kind: instance method of Plug
Returns: Device | Bulb | Plug - this

Param Type Description
interval number (ms)

plug.stopPolling()

Stops device polling.

Kind: instance method of Plug

plug.getSysInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's SysInfo.

Requests system.sys_info from device. Does not support childId.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.setAlias(alias, [sendOptions]) ⇒ Promise.<boolean, ResponseError>

Change device's alias (name).

Sends system.set_dev_alias command. Supports childId.

Kind: instance method of Plug

Param Type
alias string
[sendOptions] SendOptions

plug.setLocation(latitude, longitude, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Set device's location.

Sends system.set_dev_location command. Does not support childId.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
latitude number
longitude number
[sendOptions] SendOptions

plug.getModel([sendOptions]) ⇒ Promise.<Object, ResponseError>

Gets device's model.

Requests system.sys_info and returns model name. Does not support childId.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
[sendOptions] SendOptions

plug.reboot(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Reboot device.

Sends system.reboot command. Does not support childId.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
delay number
[sendOptions] SendOptions

plug.reset(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Reset device.

Sends system.reset command. Does not support childId.

Kind: instance method of Plug
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
delay number
[sendOptions] SendOptions

"power-on"

Plug's relay was turned on.

Kind: event emitted by Plug

"power-off"

Plug's relay was turned off.

Kind: event emitted by Plug

"power-update"

Plug's relay state was updated from device. Fired regardless if status was changed.

Kind: event emitted by Plug
Properties

Name Type Description
value boolean Relay State

"in-use"

Plug's relay was turned on or power draw exceeded inUseThreshold for HS110

Kind: event emitted by Plug

"not-in-use"

Plug's relay was turned off or power draw fell below inUseThreshold for HS110

Kind: event emitted by Plug

"in-use-update"

Plug's in-use state was updated from device. Fired regardless if status was changed.

Kind: event emitted by Plug
Properties

Name Type Description
value boolean In Use State

"emeter-realtime-update"

Plug's Energy Monitoring Details were updated from device. Fired regardless if status was changed.

Kind: event emitted by Plug
Properties

Name Type Description
value Object emeterRealtime

SendOptions : Object

Send Options.

Kind: global typedef
Properties

Name Type Description
timeout number (ms)
transport string 'tcp','udp'

ResponseError ⇐ Error

Represents an error result received from a TP-Link device.

Where response err_code != 0.

Kind: global class
Extends: Error

Credits

Thanks to George Georgovassilis and Thomas Baust for figuring out the HS1XX encryption.

Some design cues for Client based on node-lifx

About

TP-Link Smarthome WiFi API (formerly hs100-api)

License:MIT License

Languages

Language:JavaScript 99.6%Language:Shell 0.4%