Skip to content

thetrueavatar/tplink-smarthome-api

BranchesTags
 
 

Repository files navigation

tplink-smarthome-api

NPM Version Build Status codecov js-semistandard-style

TP-Link Smart Home API

Changelog

Supported Devices

Model Type
HS100, HS105, HS110, HS200 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

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

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>

Get device's TP-Link cloud firmware list.

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. Older devices return current, voltage,... while newer devices return current_ma, voltage_mv... This will return a normalized response including both old and new style properies for backwards compatibility.

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

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>

Get device's TP-Link cloud firmware list.

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. Older devices return current, voltage,... while newer devices return current_ma, voltage_mv... This will return a normalized response including both old and new style properies for backwards compatibility.

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

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. https://blog.georgovassilis.com/2016/05/07/controlling-the-tp-link-hs100-wi-fi-smart-plug/

Some design cues for Client based on node-lifx

About

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

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

31 tags

Packages

No packages published

Languages

  • JavaScript 99.5%
  • Shell 0.5%