hs100-api

2019-12-04 admin

hs100-api是什么

什么是hs100-api,TPLink HS100/HS105/HS110 WiFi Smart Plug API

hs100-api使用教程帮助文档

tplink-smarthome-api

NPM Version Build Status codecov js-semistandard-style

TP-Link Smart Home API

Changelog

Supported Devices

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

Related Projects

Examples

See more examples.

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

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

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

CLI

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

API

Full API docs can be found here.

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

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

  • Client ⇐ EventEmitter

    • new Client(options)
    • .send(payload, host, [port], [sendOptions]) ⇒ Promise.<Object, Error>
    • .getSysInfo(host, [port], [sendOptions]) ⇒ Promise.<Object, Error>
    • .getBulb(deviceOptions) ⇒ Bulb
    • .getPlug(deviceOptions) ⇒ Plug
    • .getDevice(deviceOptions, [sendOptions]) ⇒ Promise.<(Plug|Bulb), Error>
    • .getCommonDevice(deviceOptions) ⇒ Device
    • .getDeviceFromSysInfo(sysInfo, deviceOptions) ⇒ Plug | Bulb
    • .getTypeFromSysInfo(sysInfo) ⇒ string
    • .startDiscovery(options) ⇒ Client
    • .stopDiscovery()
    • “device-new”
    • “device-online”
    • “device-offline”
    • “bulb-new”
    • “bulb-online”
    • “bulb-offline”
    • “plug-new”
    • “plug-online”
    • “plug-offline”
    • “discovery-invalid”
    • “error”
  • Bulb ⇐ Device

    • new Bulb(options)
    • .cloud
      • .getInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .bind(username, password, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .unbind([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getFirmwareList([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setServerUrl(server, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .emeter
      • .realtime ⇒ Object
      • .getRealtime([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .lighting
      • .lightState ⇒ Object
      • .getLightState([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setLightState(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .schedule
      • .getNextAction([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .editRule([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .time
      • .getTime([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getTimezone([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .sysInfo ⇒ Object
    • .supportsBrightness ⇒ boolean
    • .supportsColor ⇒ boolean
    • .supportsColorTemperature ⇒ boolean
    • .getColorTemperatureRange ⇒ Object
    • .alias ⇒ string
    • .id ⇒ string
    • .deviceId ⇒ string
    • .description ⇒ string
    • .model ⇒ string
    • .name ⇒ string
    • .type ⇒ string
    • .deviceType ⇒ string
    • .softwareVersion ⇒ string
    • .hardwareVersion ⇒ string
    • .mac ⇒ string
    • .macNormalized ⇒ string
    • .getInfo([sendOptions]) ⇒ Promise.<Object, Error>
    • .getPowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setPowerState(value, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .togglePowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .send(payload, [sendOptions]) ⇒ Promise.<Object, Error>
    • .sendCommand(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .sendCommandWithChildren(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .startPolling(interval) ⇒ Device | Bulb | Plug
    • .stopPolling()
    • .getSysInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setAlias(alias, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setLocation(latitude, longitude, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getModel([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .reboot(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .reset(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • “emeter-realtime-update”
    • “lightstate-on”
    • “lightstate-off”
    • “lightstate-change”
    • “lightstate-update”
  • Plug ⇐ Device

    • new Plug(options)
    • .away
      • .getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .cloud
      • .getInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .bind(username, password, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .unbind([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getFirmwareList([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setServerUrl(server, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .dimmer
      • .setBrightness(brightness, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getDefaultBehavior([sendOptions]) ⇒ Promise.<boolean, ResponseError>
      • .getDimmerParameters([sendOptions]) ⇒ Promise.<boolean, ResponseError>
      • .setDimmerTransition(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setDoubleClickAction(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
      • .setFadeOffTime(duration, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setFadeOnTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setGentleOffTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setGentleOnTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setLongPressAction(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
      • .setSwitchState(state, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .emeter
      • .realtime ⇒ Object
      • .getRealtime([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .schedule
      • .getNextAction([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .time
      • .getTime([sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .getTimezone([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .timer
      • .getRules([childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
      • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .sysInfo ⇒ Object
    • .children ⇒ Map
    • .childId ⇒ string
    • .alias ⇒ string
    • .id ⇒ string
    • .inUse ⇒ boolean
    • .relayState ⇒ boolean
    • .supportsDimmer ⇒ boolean
    • .deviceId ⇒ string
    • .description ⇒ string
    • .model ⇒ string
    • .name ⇒ string
    • .type ⇒ string
    • .deviceType ⇒ string
    • .softwareVersion ⇒ string
    • .hardwareVersion ⇒ string
    • .mac ⇒ string
    • .macNormalized ⇒ string
    • .getInfo([sendOptions]) ⇒ Promise.<Object, Error>
    • .getInUse([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .getLedState([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setLedState(value, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .getPowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setPowerState(value, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .togglePowerState([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .blink([times], [rate], [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .send(payload, [sendOptions]) ⇒ Promise.<Object, Error>
    • .sendCommand(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .sendCommandWithChildren(command, [childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .startPolling(interval) ⇒ Device | Bulb | Plug
    • .stopPolling()
    • .getSysInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setAlias(alias, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setLocation(latitude, longitude, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getModel([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .reboot(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .reset(delay, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • “power-on”
    • “power-off”
    • “power-update”
    • “in-use”
    • “not-in-use”
    • “in-use-update”
    • “emeter-realtime-update”

<a name=“user-content-client”></a>

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 <a name=“user-content-new_client_new”></a>

new Client(options)

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

<a name=“user-content-client+send”></a>

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

<a name=“user-content-client+getsysinfo”></a>

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

<a name=“user-content-client+getbulb”></a>

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

<a name=“user-content-client+getplug”></a>

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

<a name=“user-content-client+getdevice”></a>

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

<a name=“user-content-client+getcommondevice”></a>

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

<a name=“user-content-client+getdevicefromsysinfo”></a>

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

<a name=“user-content-client+gettypefromsysinfo”></a>

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

<a name=“user-content-client+startdiscovery”></a>

client.startDiscovery(options) ⇒ Client

Discover TP-Link Smarthome devices on the network.

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

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

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

<a name=“user-content-client+stopdiscovery”></a>

client.stopDiscovery()

Stops discovery and closes UDP socket.

Kind: instance method of Client <a name=“user-content-client+event_device-new”></a>

“device-new”

First response from device.

Kind: event emitted by Client Properties

Type
Device

<a name=“user-content-client+event_device-online”></a>

“device-online”

Follow up response from device.

Kind: event emitted by Client Properties

Type
Device

<a name=“user-content-client+event_device-offline”></a>

“device-offline”

No response from device.

Kind: event emitted by Client Properties

Type
Device

<a name=“user-content-client+event_bulb-new”></a>

“bulb-new”

First response from Bulb.

Kind: event emitted by Client Properties

Type
Bulb

<a name=“user-content-client+event_bulb-online”></a>

“bulb-online”

Follow up response from Bulb.

Kind: event emitted by Client Properties

Type
Bulb

<a name=“user-content-client+event_bulb-offline”></a>

“bulb-offline”

No response from Bulb.

Kind: event emitted by Client Properties

Type
Bulb

<a name=“user-content-client+event_plug-new”></a>

“plug-new”

First response from Plug.

Kind: event emitted by Client Properties

Type
Plug

<a name=“user-content-client+event_plug-online”></a>

“plug-online”

Follow up response from Plug.

Kind: event emitted by Client Properties

Type
Plug

<a name=“user-content-client+event_plug-offline”></a>

“plug-offline”

No response from Plug.

Kind: event emitted by Client Properties

Type
Plug

<a name=“user-content-client+event_discovery-invalid”></a>

“discovery-invalid”

Invalid/Unknown response from device.

Kind: event emitted by Client Properties

Name Type
rinfo Object
response Buffer
decryptedResponse Buffer

<a name=“user-content-client+event_error”></a>

“error”

Error during discovery.

Kind: event emitted by Client Properties

Type
Error

<a name=“user-content-bulb”></a>

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 <a name=“user-content-new_bulb_new”></a>

new Bulb(options)

Created by Client - Do not instantiate directly.

See Device constructor for common options.

Param Type
options Object

<a name=“user-content-bulb+cloud”></a>

bulb.cloud

Kind: instance property of Bulb

  • .cloud
    • .getInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .bind(username, password, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .unbind([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getFirmwareList([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setServerUrl(server, [sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-bulb+cloud+getinfo”></a>

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

Gets device’s TP-Link cloud info.

Requests cloud.get_info. Does not support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+cloud+bind”></a>

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

Add device to TP-Link cloud.

Sends cloud.bind command. Does not support childId.

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

Param Type
username string
password string
[sendOptions] SendOptions

<a name=“user-content-bulb+cloud+unbind”></a>

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

Remove device from TP-Link cloud.

Sends cloud.unbind command. Does not support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+cloud+getfirmwarelist”></a>

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

Get device’s TP-Link cloud firmware list.

Sends cloud.get_intl_fw_list command. Does not support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+cloud+setserverurl”></a>

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

Sets device’s TP-Link cloud server URL.

Sends cloud.set_server_url command. Does not support childId.

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

Param Type Description
server string URL
[sendOptions] SendOptions

<a name=“user-content-bulb+emeter”></a>

bulb.emeter

Kind: instance property of Bulb

  • .emeter
    • .realtime ⇒ Object
    • .getRealtime([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-bulb+emeter+realtime”></a>

emeter.realtime ⇒ Object

Returns cached results from last retrieval of emeter.get_realtime.

Kind: instance property of emeter <a name=“user-content-bulb+emeter+getrealtime”></a>

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

Gets device’s current energy stats.

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+emeter+getdaystats”></a>

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

Get Daily Emeter Statisics.

Sends emeter.get_daystat command. Supports childId.

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

Param Type
year number
month number
[sendOptions] SendOptions

<a name=“user-content-bulb+emeter+getmonthstats”></a>

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

Get Monthly Emeter Statisics.

Sends emeter.get_monthstat command. Supports childId.

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

Param Type
year number
[sendOptions] SendOptions

<a name=“user-content-bulb+emeter+erasestats”></a>

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

Erase Emeter Statistics.

Sends emeter.erase_runtime_stat command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+lighting”></a>

bulb.lighting

Kind: instance property of Bulb

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

<a name=“user-content-bulb+lighting+lightstate”></a>

lighting.lightState ⇒ Object

Returns cached results from last retrieval of lightingservice.get_light_state.

Kind: instance property of lighting <a name=“user-content-bulb+lighting+getlightstate”></a>

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

<a name=“user-content-bulb+lighting+setlightstate”></a>

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

<a name=“user-content-bulb+schedule”></a>

bulb.schedule

Kind: instance property of Bulb

  • .schedule
    • .getNextAction([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .editRule([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-bulb+schedule+getnextaction”></a>

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

Gets Next Schedule Rule Action.

Requests schedule.get_next_action. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+getrules”></a>

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

Gets Schedule Rules.

Requests schedule.get_rules. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+getrule”></a>

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

Gets Schedule Rule.

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

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

Param Type
id string
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+addrule”></a>

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
[options.daysOfWeek] Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.name] string
[options.enable] boolean true
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+editrule”></a>

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
[options.daysOfWeek] Array.<number> [0,6] = weekend, [1,2,3,4,5] = weekdays
[options.name] string [description]
[options.enable] boolean true
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+deleteallrules”></a>

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

Deletes All Schedule Rules.

Sends schedule.delete_all_rules command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+deleterule”></a>

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

Deletes Schedule Rule.

Sends schedule.delete_rule command. Supports childId.

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

Param Type
id string
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+setoverallenable”></a>

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

Enables or Disables Schedule Rules.

Sends schedule.set_overall_enable command. Supports childId.

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

Param Type
enable boolean
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+getdaystats”></a>

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

Get Daily Usage Statisics.

Sends schedule.get_daystat command. Supports childId.

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

Param Type
year number
month number
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+getmonthstats”></a>

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

Get Monthly Usage Statisics.

Sends schedule.get_monthstat command. Supports childId.

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

Param Type
year number
[sendOptions] SendOptions

<a name=“user-content-bulb+schedule+erasestats”></a>

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

Erase Usage Statistics.

Sends schedule.erase_runtime_stat command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+time”></a>

bulb.time

Kind: instance property of Bulb

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

<a name=“user-content-bulb+time+gettime”></a>

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

Gets device’s time.

Requests timesetting.get_time. Does not support ChildId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+time+gettimezone”></a>

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

Gets device’s timezone.

Requests timesetting.get_timezone. Does not support ChildId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-bulb+sysinfo”></a>

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 <a name=“user-content-bulb+supportsbrightness”></a>

bulb.supportsBrightness ⇒ boolean

Cached value of sys_info.is_dimmable === 1

Kind: instance property of Bulb <a name=“user-content-bulb+supportscolor”></a>

bulb.supportsColor ⇒ boolean

Cached value of sys_info.is_color === 1

Kind: instance property of Bulb <a name=“user-content-bulb+supportscolortemperature”></a>

bulb.supportsColorTemperature ⇒ boolean

Cached value of sys_info.is_variable_color_temp === 1

Kind: instance property of Bulb <a name=“user-content-bulb+getcolortemperaturerange”></a>

bulb.getColorTemperatureRange ⇒ Object

Returns array with min and max supported color temperatures

Kind: instance property of Bulb Returns: Object - range <a name=“user-content-device+alias”></a>

bulb.alias ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Bulb Overrides: alias <a name=“user-content-device+id”></a>

bulb.id ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Bulb <a name=“user-content-device+deviceid”></a>

bulb.deviceId ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Bulb <a name=“user-content-device+description”></a>

bulb.description ⇒ string

Cached value of sys_info.[description|dev_name].

Kind: instance property of Bulb <a name=“user-content-device+model”></a>

bulb.model ⇒ string

Cached value of sys_info.model.

Kind: instance property of Bulb <a name=“user-content-device+name”></a>

bulb.name ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Bulb <a name=“user-content-device+type”></a>

bulb.type ⇒ string

Cached value of sys_info.[type|mic_type].

Kind: instance property of Bulb <a name=“user-content-device+devicetype”></a>

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’ <a name=“user-content-device+softwareversion”></a>

bulb.softwareVersion ⇒ string

Cached value of sys_info.sw_ver.

Kind: instance property of Bulb <a name=“user-content-device+hardwareversion”></a>

bulb.hardwareVersion ⇒ string

Cached value of sys_info.hw_ver.

Kind: instance property of Bulb <a name=“user-content-device+mac”></a>

bulb.mac ⇒ string

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

Kind: instance property of Bulb <a name=“user-content-device+macnormalized”></a>

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 <a name=“user-content-bulb+getinfo”></a>

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

<a name=“user-content-bulb+getpowerstate”></a>

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

<a name=“user-content-bulb+setpowerstate”></a>

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

<a name=“user-content-bulb+togglepowerstate”></a>

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

<a name=“user-content-device+send”></a>

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
[sendOptions] SendOptions

<a name=“user-content-device+sendcommand”></a>

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

Sends command(s) to device.

Calls #send and processes the response.

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

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

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

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

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

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

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

<a name=“user-content-device+sendcommandwithchildren”></a>

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

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

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

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

<a name=“user-content-device+startpolling”></a>

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)

<a name=“user-content-device+stoppolling”></a>

bulb.stopPolling()

Stops device polling.

Kind: instance method of Bulb <a name=“user-content-device+getsysinfo”></a>

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

Gets device’s SysInfo.

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-device+setalias”></a>

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

Change device’s alias (name).

Sends system.set_dev_alias command. Supports childId.

Kind: instance method of Bulb

Param Type
alias string
[sendOptions] SendOptions

<a name=“user-content-device+setlocation”></a>

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

Set device’s location.

Sends system.set_dev_location command. Does not support childId.

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

Param Type
latitude number
longitude number
[sendOptions] SendOptions

<a name=“user-content-device+getmodel”></a>

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

Gets device’s model.

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-device+reboot”></a>

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

Reboot device.

Sends system.reboot command. Does not support childId.

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

Param Type
delay number
[sendOptions] SendOptions

<a name=“user-content-device+reset”></a>

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

Reset device.

Sends system.reset command. Does not support childId.

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

Param Type
delay number
[sendOptions] SendOptions

<a name=“user-content-bulb+event_emeter-realtime-update”></a>

“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

<a name=“user-content-bulb+event_lightstate-on”></a>

“lightstate-on”

Bulb was turned on (lightstate.on_off).

Kind: event emitted by Bulb Properties

Name Type Description
value Object lightstate

<a name=“user-content-bulb+event_lightstate-off”></a>

“lightstate-off”

Bulb was turned off (lightstate.on_off).

Kind: event emitted by Bulb Properties

Name Type Description
value Object lightstate

<a name=“user-content-bulb+event_lightstate-change”></a>

“lightstate-change”

Bulb’s lightstate was changed.

Kind: event emitted by Bulb Properties

Name Type Description
value Object lightstate

<a name=“user-content-bulb+event_lightstate-update”></a>

“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

<a name=“user-content-plug”></a>

Plug ⇐ Device

Plug Device.

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

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

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

Kind: global class Extends: Device, EventEmitter Emits: power-on, power-off, power-update, in-use, not-in-use, in-use-update, emeter-realtime-update <a name=“user-content-new_plug_new”></a>

new Plug(options)

Created by Client - Do not instantiate directly.

See Device constructor for common options.

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

<a name=“user-content-plug+away”></a>

plug.away

Kind: instance property of Plug

  • .away
    • .getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-plug+away+getrules”></a>

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

Gets Away Rules.

Requests anti_theft.get_rules. Support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+away+addrule”></a>

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

Adds Away Rule.

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

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

Param Type Default Description
options Object
options.start Date number
options.end Date number
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

<a name=“user-content-plug+away+editrule”></a>

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

Edits Away rule.

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

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

Param Type Default Description
options Object
options.id string
options.start Date number
options.end Date number
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

<a name=“user-content-plug+away+deleteallrules”></a>

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

Deletes All Away Rules.

Sends anti_theft.delete_all_rules command. Support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+away+deleterule”></a>

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

Deletes Away Rule.

Sends anti_theft.delete_rule command. Support childId.

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

Param Type
id string
[sendOptions] SendOptions

<a name=“user-content-plug+away+setoverallenable”></a>

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

Enables or Disables Away Rules.

Sends anti_theft.set_overall_enable command. Support childId.

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

Param Type
enable boolean
[sendOptions] SendOptions

<a name=“user-content-plug+cloud”></a>

plug.cloud

Kind: instance property of Plug

  • .cloud
    • .getInfo([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .bind(username, password, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .unbind([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getFirmwareList([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setServerUrl(server, [sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-plug+cloud+getinfo”></a>

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

Gets device’s TP-Link cloud info.

Requests cloud.get_info. Does not support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+cloud+bind”></a>

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

Add device to TP-Link cloud.

Sends cloud.bind command. Does not support childId.

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

Param Type
username string
password string
[sendOptions] SendOptions

<a name=“user-content-plug+cloud+unbind”></a>

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

Remove device from TP-Link cloud.

Sends cloud.unbind command. Does not support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+cloud+getfirmwarelist”></a>

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

Get device’s TP-Link cloud firmware list.

Sends cloud.get_intl_fw_list command. Does not support childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+cloud+setserverurl”></a>

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

Sets device’s TP-Link cloud server URL.

Sends cloud.set_server_url command. Does not support childId.

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

Param Type Description
server string URL
[sendOptions] SendOptions

<a name=“user-content-plug+dimmer”></a>

plug.dimmer

Kind: instance property of Plug

  • .dimmer
    • .setBrightness(brightness, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getDefaultBehavior([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .getDimmerParameters([sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setDimmerTransition(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setDoubleClickAction(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setFadeOffTime(duration, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setFadeOnTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setGentleOffTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setGentleOnTime(fadeTime, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setLongPressAction(options, [sendOptions]) ⇒ Promise.<boolean, ResponseError>
    • .setSwitchState(state, [sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-plug+dimmer+setbrightness”></a>

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

Sets Plug to the specified brightness.

Sends dimmer.set_brightness command. Does not support childId.

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

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

<a name=“user-content-plug+dimmer+getdefaultbehavior”></a>

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

Get Plug/Dimmer default behavior configuration.

Requests dimmer.get_default_behavior. Does not support childId.

Kind: instance method of dimmer

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+dimmer+getdimmerparameters”></a>

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

Get Plug/Dimmer parameters configuration.

Requests dimmer.get_dimmer_parameters. Does not support childId.

Kind: instance method of dimmer

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+dimmer+setdimmertransition”></a>

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

Transitions Plug to the specified brightness.

Sends dimmer.set_dimmer_transition command. Does not support childId.

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

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

<a name=“user-content-plug+dimmer+setdoubleclickaction”></a>

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

Set Plug/Dimmer default_behavior configuration for double_click.

Sends dimmer.set_double_click_action. Does not support childId.

Kind: instance method of dimmer

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

<a name=“user-content-plug+dimmer+setfadeofftime”></a>

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

Set Plug dimmer_parameters for fadeOffTime.

Sends dimmer.set_fade_off_time. Does not support childId.

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

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

<a name=“user-content-plug+dimmer+setfadeontime”></a>

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

Set Plug dimmer_parameters for fadeOnTime.

Sends dimmer.set_fade_on_time. Does not support childId.

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

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

<a name=“user-content-plug+dimmer+setgentleofftime”></a>

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

Set Plug dimmer_parameters for gentleOffTime.

Sends dimmer.set_gentle_off_time. Does not support childId.

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

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

<a name=“user-content-plug+dimmer+setgentleontime”></a>

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

Set Plug dimmer_parameters for gentleOnTime.

Sends dimmer.set_gentle_on_time. Does not support childId.

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

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

<a name=“user-content-plug+dimmer+setlongpressaction”></a>

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

Set Plug/Dimmer default_behavior configuration for long_press.

Sends dimmer.set_long_press_action. Does not support childId.

Kind: instance method of dimmer

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

<a name=“user-content-plug+dimmer+setswitchstate”></a>

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

Sets Plug to the specified on/off state.

Sends dimmer.set_switch_state command. Does not support childId.

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

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

<a name=“user-content-plug+emeter”></a>

plug.emeter

Kind: instance property of Plug

  • .emeter
    • .realtime ⇒ Object
    • .getRealtime([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-plug+emeter+realtime”></a>

emeter.realtime ⇒ Object

Returns cached results from last retrieval of emeter.get_realtime.

Kind: instance property of emeter <a name=“user-content-plug+emeter+getrealtime”></a>

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

Gets device’s current energy stats.

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+emeter+getdaystats”></a>

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

Get Daily Emeter Statisics.

Sends emeter.get_daystat command. Supports childId.

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

Param Type
year number
month number
[sendOptions] SendOptions

<a name=“user-content-plug+emeter+getmonthstats”></a>

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

Get Monthly Emeter Statisics.

Sends emeter.get_monthstat command. Supports childId.

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

Param Type
year number
[sendOptions] SendOptions

<a name=“user-content-plug+emeter+erasestats”></a>

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

Erase Emeter Statistics.

Sends emeter.erase_runtime_stat command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+schedule”></a>

plug.schedule

Kind: instance property of Plug

  • .schedule
    • .getNextAction([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteRule(id, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .setOverallEnable(enable, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getDayStats(year, month, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .getMonthStats(year, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .eraseStats([sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-plug+schedule+getnextaction”></a>

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

Gets Next Schedule Rule Action.

Requests schedule.get_next_action. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+getrules”></a>

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

Gets Schedule Rules.

Requests schedule.get_rules. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+getrule”></a>

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

Gets Schedule Rule.

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

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

Param Type
id string
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+addrule”></a>

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

Adds Schedule rule.

Sends schedule.add_rule command and returns rule id.

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

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

<a name=“user-content-plug+schedule+editrule”></a>

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

Edits Schedule rule.

Sends schedule.edit_rule command and returns rule id.

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

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

<a name=“user-content-plug+schedule+deleteallrules”></a>

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

Deletes All Schedule Rules.

Sends schedule.delete_all_rules command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+deleterule”></a>

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

Deletes Schedule Rule.

Sends schedule.delete_rule command. Supports childId.

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

Param Type
id string
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+setoverallenable”></a>

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

Enables or Disables Schedule Rules.

Sends schedule.set_overall_enable command. Supports childId.

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

Param Type
enable boolean
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+getdaystats”></a>

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

Get Daily Usage Statisics.

Sends schedule.get_daystat command. Supports childId.

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

Param Type
year number
month number
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+getmonthstats”></a>

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

Get Monthly Usage Statisics.

Sends schedule.get_monthstat command. Supports childId.

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

Param Type
year number
[sendOptions] SendOptions

<a name=“user-content-plug+schedule+erasestats”></a>

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

Erase Usage Statistics.

Sends schedule.erase_runtime_stat command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+time”></a>

plug.time

Kind: instance property of Plug

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

<a name=“user-content-plug+time+gettime”></a>

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

Gets device’s time.

Requests timesetting.get_time. Does not support ChildId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+time+gettimezone”></a>

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

Gets device’s timezone.

Requests timesetting.get_timezone. Does not support ChildId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+timer”></a>

plug.timer

Kind: instance property of Plug

  • .timer
    • .getRules([childIds], [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .addRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .editRule(options, [sendOptions]) ⇒ Promise.<Object, ResponseError>
    • .deleteAllRules([sendOptions]) ⇒ Promise.<Object, ResponseError>

<a name=“user-content-plug+timer+getrules”></a>

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

Get Countdown Timer Rule (only one allowed).

Requests count_down.get_rules. Supports childId.

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

Param Type Description
[childIds] Array.<string> string
[sendOptions] SendOptions

<a name=“user-content-plug+timer+addrule”></a>

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

Add Countdown Timer Rule (only one allowed).

Sends count_down.add_rule command. Supports childId.

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

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

<a name=“user-content-plug+timer+editrule”></a>

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

Edit Countdown Timer Rule (only one allowed).

Sends count_down.edit_rule command. Supports childId.

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

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

<a name=“user-content-plug+timer+deleteallrules”></a>

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

Delete Countdown Timer Rule (only one allowed).

Sends count_down.delete_all_rules command. Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+sysinfo”></a>

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 <a name=“user-content-plug+children”></a>

plug.children ⇒ Map

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

Kind: instance property of Plug Returns: Map - children <a name=“user-content-plug+childid”></a>

plug.childId ⇒ string

Returns childId.

Kind: instance property of Plug Returns: string - childId <a name=“user-content-plug+alias”></a>

plug.alias ⇒ string

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

Kind: instance property of Plug Overrides: alias <a name=“user-content-plug+id”></a>

plug.id ⇒ string

Cached value of sys_info.deviceId or childId if set.

Kind: instance property of Plug Overrides: id <a name=“user-content-plug+inuse”></a>

plug.inUse ⇒ boolean

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

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

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

Supports childId.

Kind: instance property of Plug <a name=“user-content-plug+relaystate”></a>

plug.relayState ⇒ boolean

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

Kind: instance property of Plug Returns: boolean - On (true) or Off (false) <a name=“user-content-plug+supportsdimmer”></a>

plug.supportsDimmer ⇒ boolean

Cached value of sys_info.brightness != null

Kind: instance property of Plug <a name=“user-content-device+deviceid”></a>

plug.deviceId ⇒ string

Cached value of sys_info.deviceId.

Kind: instance property of Plug <a name=“user-content-device+description”></a>

plug.description ⇒ string

Cached value of sys_info.[description|dev_name].

Kind: instance property of Plug <a name=“user-content-device+model”></a>

plug.model ⇒ string

Cached value of sys_info.model.

Kind: instance property of Plug <a name=“user-content-device+name”></a>

plug.name ⇒ string

Cached value of sys_info.alias.

Kind: instance property of Plug <a name=“user-content-device+type”></a>

plug.type ⇒ string

Cached value of sys_info.[type|mic_type].

Kind: instance property of Plug <a name=“user-content-device+devicetype”></a>

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’ <a name=“user-content-device+softwareversion”></a>

plug.softwareVersion ⇒ string

Cached value of sys_info.sw_ver.

Kind: instance property of Plug <a name=“user-content-device+hardwareversion”></a>

plug.hardwareVersion ⇒ string

Cached value of sys_info.hw_ver.

Kind: instance property of Plug <a name=“user-content-device+mac”></a>

plug.mac ⇒ string

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

Kind: instance property of Plug <a name=“user-content-device+macnormalized”></a>

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 <a name=“user-content-plug+getinfo”></a>

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

Requests common Plug status details in a single request.

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

Supports childId.

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+getinuse”></a>

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

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

Kind: instance method of Plug

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+getledstate”></a>

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

Get Plug LED state (night mode).

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+setledstate”></a>

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

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

Sends system.set_led_off command.

Kind: instance method of Plug

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

<a name=“user-content-plug+getpowerstate”></a>

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

Get Plug relay state (on/off).

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

Kind: instance method of Plug

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+setpowerstate”></a>

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

Turns Plug relay on/off.

Sends system.set_relay_state command. Supports childId.

Kind: instance method of Plug

Param Type
value boolean
[sendOptions] SendOptions

<a name=“user-content-plug+togglepowerstate”></a>

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

Toggles Plug relay state.

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

Kind: instance method of Plug

Param Type
[sendOptions] SendOptions

<a name=“user-content-plug+blink”></a>

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

Blink Plug LED.

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

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

Kind: instance method of Plug

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

<a name=“user-content-device+send”></a>

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
[sendOptions] SendOptions

<a name=“user-content-device+sendcommand”></a>

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

Sends command(s) to device.

Calls #send and processes the response.

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

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

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

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

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

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

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

<a name=“user-content-device+sendcommandwithchildren”></a>

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

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

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

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

<a name=“user-content-device+startpolling”></a>

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)

<a name=“user-content-device+stoppolling”></a>

plug.stopPolling()

Stops device polling.

Kind: instance method of Plug <a name=“user-content-device+getsysinfo”></a>

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

Gets device’s SysInfo.

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-device+setalias”></a>

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

Change device’s alias (name).

Sends system.set_dev_alias command. Supports childId.

Kind: instance method of Plug

Param Type
alias string
[sendOptions] SendOptions

<a name=“user-content-device+setlocation”></a>

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

Set device’s location.

Sends system.set_dev_location command. Does not support childId.

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

Param Type
latitude number
longitude number
[sendOptions] SendOptions

<a name=“user-content-device+getmodel”></a>

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

Gets device’s model.

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

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

Param Type
[sendOptions] SendOptions

<a name=“user-content-device+reboot”></a>

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

Reboot device.

Sends system.reboot command. Does not support childId.

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

Param Type
delay number
[sendOptions] SendOptions

<a name=“user-content-device+reset”></a>

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

Reset device.

Sends system.reset command. Does not support childId.

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

Param Type
delay number
[sendOptions] SendOptions

<a name=“user-content-plug+event_power-on”></a>

“power-on”

Plug’s relay was turned on.

Kind: event emitted by Plug <a name=“user-content-plug+event_power-off”></a>

“power-off”

Plug’s relay was turned off.

Kind: event emitted by Plug <a name=“user-content-plug+event_power-update”></a>

“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

<a name=“user-content-plug+event_in-use”></a>

“in-use”

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

Kind: event emitted by Plug <a name=“user-content-plug+event_not-in-use”></a>

“not-in-use”

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

Kind: event emitted by Plug <a name=“user-content-plug+event_in-use-update”></a>

“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

<a name=“user-content-plug+event_emeter-realtime-update”></a>

“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

<a name=“user-content-sendoptions”></a>

SendOptions : Object

Send Options.

Kind: global typedef Properties

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

<a name=“user-content-responseerror”></a>

ResponseError ⇐ Error

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

Where response err_code != 0.

Kind: global class Extends: Error

Credits

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

Some design cues for Client based on node-lifx

本站文章除注明转载外,均为本站原创或编译。欢迎任何形式的转载,但请务必注明出处。

转载请注明:文章转载自 JavaScript中文网 [https://www.javascriptcn.com]

本文地址:https://www.javascriptcn.com/read-80420.html

文章标题:hs100-api

回到顶部