Skip to content

Latest commit

 

History

History
3508 lines (2472 loc) · 132 KB

API.md

File metadata and controls

3508 lines (2472 loc) · 132 KB

Modules

tplink-smarthome-api

Classes

Bulb ⇐ Device

Bulb Device.

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

Lighting

Lighting

BulbSchedule

BulbSchedule

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.
Device ⇐ EventEmitter

TP-Link Device.

Shared behavior for Plug and Bulb.

Netif

Netif

Away

Away

Plug ⇐ Device

Plug Device.

TP-Link models: HS100, HS105, HS110, HS200.

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

PlugSchedule

PlugSchedule

Timer

Timer

Cloud

Cloud

Emeter

Eemter

Schedule

Schedule

Time

Time

ResponseError ⇐ Error

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

Where response err_code != 0.

Typedefs

SendOptions : Object

Send Options.

tplink-smarthome-api

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.

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.

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.

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

Param Type
[sendOptions] SendOptions

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

Remove device from TP-Link cloud.

Sends cloud.get_intl_fw_list command.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sends command(s) to device.

Calls #send and processes the response.

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

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.

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.

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.

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.

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.

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

Lighting

Lighting

Kind: global class

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

BulbSchedule

BulbSchedule

Kind: global class

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

Adds Schedule rule.

Sends schedule.add_rule command and returns rule id.

Kind: instance method of BulbSchedule
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

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

Edits Schedule rule.

Sends schedule.edit_rule command and returns rule id.

Kind: instance method of BulbSchedule
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

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 5000 (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 matching device with matching MAC addresses 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
[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

Device ⇐ EventEmitter

TP-Link Device.

Shared behavior for Plug and Bulb.

Kind: global class
Extends: EventEmitter
Emits: Device#event:emeter-realtime-update

new Device(options)

Created by getCommonDevice - Do not instantiate directly

Param Type Default
options Object
options.client Client
options.sysInfo Object
options.host string
[options.port] number 9999
[options.logger] Object
[options.defaultSendOptions] SendOptions

device.sysInfo ⇒ Object

Returns cached results from last retrieval of system.sys_info.

Kind: instance property of Device
Returns: Object - system.sys_info

device.alias ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Device

device.deviceId ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Device

device.description ⇒ string

Cached value of sys_info.[description|dev_name].

Kind: instance property of Device

device.model ⇒ string

Cached value of sys_info.model.

Kind: instance property of Device

device.name ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Device

device.type ⇒ string

Cached value of sys_info.[type|mic_type].

Kind: instance property of Device

device.deviceType ⇒ string

Type of device (or device if unknown).

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

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

device.softwareVersion ⇒ string

Cached value of sys_info.sw_ver.

Kind: instance property of Device

device.hardwareVersion ⇒ string

Cached value of sys_info.hw_ver.

Kind: instance property of Device

device.mac ⇒ string

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

Kind: instance property of Device

device.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 Device

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

Sends payload to device (using send)

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

Param Type
payload Object | string
[sendOptions] SendOptions

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

Sends command(s) to device.

Calls #send and processes the response.

  • 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 Device
Returns: Promise.<Object, ResponseError> - parsed JSON response

Param Type
command Object | string
[sendOptions] SendOptions

device.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 Device
Returns: Device | Bulb | Plug - this

Param Type Description
interval number (ms)

device.stopPolling()

Stops device polling.

Kind: instance method of Device

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

Gets device's SysInfo.

Requests system.sys_info from device.

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

Param Type
[sendOptions] SendOptions

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

Change device's alias (name).

Sends system.set_dev_alias command.

Kind: instance method of Device

Param Type
alias string
[sendOptions] SendOptions

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

Set device's location.

Sends system.set_dev_location command.

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

Param Type
latitude number
longitude number
[sendOptions] SendOptions

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

Gets device's model.

Requests system.sys_info and returns model name.

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

Param Type
[sendOptions] SendOptions

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

Reboot device.

Sends system.reboot command.

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

Param Type
delay number
[sendOptions] SendOptions

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

Reset device.

Sends system.reset command.

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

Param Type
delay number
[sendOptions] SendOptions

Netif

Netif

Kind: global class

netif.getScanInfo([refresh], [timeoutInSeconds], [sendOptions]) ⇒ Promise.<Object, ResponseError>

Requests netif.get_scaninfo (list of WiFi networks).

Note that timeoutInSeconds is sent in the request and is not the actual network timeout. The network timeout for the request is calculated by adding the default network timeout to timeoutInSeconds.

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

Param Type Default Description
[refresh] Boolean false request device's cached results
[timeoutInSeconds] number 10 timeout for scan in seconds
[sendOptions] SendOptions

Away

Away

Kind: global class

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

Gets Away Rules.

Requests anti_theft.get_rules.

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

Param Type
[sendOptions] SendOptions

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

Gets Away Rule.

Requests anti_theft.get_rules and return rule matching Id

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

Param Type
id string
[sendOptions] SendOptions

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

Adds Away Rule.

Sends anti_theft.add_rule command and returns rule id.

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.

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.

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.

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.

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

Param Type
enable boolean
[sendOptions] SendOptions

Plug ⇐ Device

Plug Device.

TP-Link models: HS100, HS105, HS110, HS200.

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
options Object
[options.inUseThreshold] Number 0

plug.away

Kind: instance property of Plug

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

Gets Away Rules.

Requests anti_theft.get_rules.

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.

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.

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.

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.

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.

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.

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.

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.

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

Param Type
[sendOptions] SendOptions

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

Remove device from TP-Link cloud.

Sends cloud.get_intl_fw_list command.

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.

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

Param Type Description
server string URL
[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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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([sendOptions]) ⇒ Promise.<Object, ResponseError>

Get Countdown Timer Rule (only one allowed).

Requests count_down.get_rules.

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

Param Type
[sendOptions] SendOptions

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

Add Countdown Timer Rule (only one allowed).

Sends count_down.add_rule command.

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.

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.

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.inUse ⇒ boolean

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

If device supports energy monitoring (HS110): power > inUseThreshold

Otherwise fallback on relay state: relay_state === 1

Kind: instance property of Plug

plug.relayState ⇒ boolean

sys_info.relay_state === 1

Kind: instance property of Plug

plug.alias ⇒ string

Cached value of sys_info.alias.

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

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.

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.

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

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 relay_state === 1.

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.

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 return the new power state.

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.

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, [sendOptions]) ⇒ Promise.<Object, ResponseError>

Sends command(s) to device.

Calls #send and processes the response.

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

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.

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.

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.

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.

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.

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

PlugSchedule

PlugSchedule

Kind: global class

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

Adds Schedule rule.

Sends schedule.add_rule command and returns rule id.

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

Param Type Default Description
options Object
options.powerState boolean
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

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

Edits Schedule rule.

Sends schedule.edit_rule command and returns rule id.

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

Param Type Default Description
options Object
options.id string
options.powerState boolean
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

Timer

Timer

Kind: global class

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

Get Countdown Timer Rule (only one allowed).

Requests count_down.get_rules.

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

Param Type
[sendOptions] SendOptions

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

Add Countdown Timer Rule (only one allowed).

Sends count_down.add_rule command.

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.

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.

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

Param Type
[sendOptions] SendOptions

Cloud

Cloud

Kind: global class

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

Gets device's TP-Link cloud info.

Requests cloud.get_info.

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.

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.

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

Param Type
[sendOptions] SendOptions

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

Remove device from TP-Link cloud.

Sends cloud.get_intl_fw_list command.

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.

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

Param Type Description
server string URL
[sendOptions] SendOptions

Emeter

Eemter

Kind: global class

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.

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.

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.

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.

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

Param Type
[sendOptions] SendOptions

Schedule

Schedule

Kind: global class

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

Gets Next Schedule Rule Action.

Requests schedule.get_next_action.

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.

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

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

Param Type
id string
[sendOptions] SendOptions

schedule.addRule(rule, [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
rule Object
[sendOptions] SendOptions

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

Edits Schedule Rule.

Sends schedule.edit_rule command.

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

Param Type
rule Object
[sendOptions] SendOptions

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

Deletes All Schedule Rules.

Sends schedule.delete_all_rules command.

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.

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.

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.

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.

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.

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

Param Type
[sendOptions] SendOptions

Time

Time

Kind: global class

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

Gets device's time.

Requests timesetting.get_time.

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.

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

Param Type
[sendOptions] SendOptions

ResponseError ⇐ Error

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

Where response err_code != 0.

Kind: global class
Extends: Error

SendOptions : Object

Send Options.

Kind: global typedef
Properties

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