Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adumont/tplink-cloud-api
A node.js npm module to remotely control TP-Link smartplugs (HS100, HS110) and smartbulbs (LB100, LB110, LB120, LB130) using their cloud web service (no need to be on the same wifi/lan)
https://github.com/adumont/tplink-cloud-api
hs100 hs110 iot lb100 lb130 nodejs npm npm-module npm-package tplink
Last synced: about 2 months ago
JSON representation
A node.js npm module to remotely control TP-Link smartplugs (HS100, HS110) and smartbulbs (LB100, LB110, LB120, LB130) using their cloud web service (no need to be on the same wifi/lan)
- Host: GitHub
- URL: https://github.com/adumont/tplink-cloud-api
- Owner: adumont
- License: gpl-3.0
- Archived: true
- Created: 2017-07-31T19:56:03.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T20:34:08.000Z (almost 2 years ago)
- Last Synced: 2024-10-13T12:44:55.954Z (2 months ago)
- Topics: hs100, hs110, iot, lb100, lb130, nodejs, npm, npm-module, npm-package, tplink
- Language: TypeScript
- Homepage: https://itnerd.space
- Size: 242 KB
- Stars: 126
- Watchers: 13
- Forks: 44
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/adumont/tplink-cloud-api)
[](https://codebeat.co/projects/github-com-adumont-tplink-cloud-api-master)
# Introduction
The `tplink-cloud-api` NPM module allows your to remotely control your TP-Link smartplugs (HS100, HS110, HS300...), smart switches (HS200), and smartbulbs (LB100, LB110, LB120, LB130, KL60, KL110, KL120, KL130, and more) using the TP-Link cloud web service, from anywhere, without the need to be on the same wifi/lan.
It's especially useful in scenarios where you want to control your devices from public web services, like [IFTTT](https://ifttt.com/), [Thinger.io](https://thinger.io/), [Webtask.io](https://webtask.io/), [Glitch.com](http://glitch.com/), Tasker (Android)...
It's based on my investigation work on the TP-Link API protocol, which I have been sharing in my blog http://itnerd.space.
# Installation
You can install this module with `npm`:
```bash
npm install --save tplink-cloud-api
```
# Usage
## Authenticate
First instantiate a TP-Link object. TermID (UUIDv4) is generated if not specified:
```javascript
const { login } = require("tplink-cloud-api");
const tplink = await login("[email protected]", "Password", "TermID");
```
## Retrieve devices
Once authenticated, you can use your tplink instance to retrieve the list of your devices:
```javascript
let deviceList = await tplink.getDeviceList();
```
## Control your devices
### Smartplugs (HS100 & HS110)
Now you can toggle a plug:
```javascript
await tplink.getHS100("My Smart Plug").toggle();
```
You can also create an object and use it like this:
```javascript
let myPlug = tplink.getHS100("My Smart Plug ");
let response = await myPlug.toggle();
console.log(await myPlug.getRelayState());
```
Replace `My Smart Plug` with the alias you gave to your plug in the Kasa app (be sure to give a different alias to each device). Alternatively, you can also specify the unique deviceId or each device.
Instead of `toggle()`, you can use `powerOn()` or `powerOff()`. See all available methods below.
If you want to trigger multiple plugs, you can do it like this:
```javascript
await tplink.getHS100("My Smart Plug").toggle();
await tplink.getHS100("My Smart Plug 2").powerOn();
await tplink.getHS100("My Smart Plug 3").powerOff();
await tplink.getHS100("My Smart Plug 4").powerOff();
```
To retrieve power consumption data for the HS110:
```javascript
await tplink.getHS110("My Smart Plug").getPowerUsage();
```
### Smart Switches (HS200, HS300...)
You can toggle smart switches with the same API as the smart plugs.
For an example of how to control a multiplug power outlet like the HS300 series, see examples of code in [Issue 27](https://github.com/adumont/tplink-cloud-api/issues/27#issuecomment-642304749). (Support for multiplug outlet was added after v0.8 of the npm module).
### Smartbulbs (LB100/110/120/130, KL110/120/130)
If you have an LB100/110 or KL50/60/110 (dimmable), you can change its state with:
```javascript
await tplink.getLB100("Bedroom LB120").setState(1, 90);
```
The two parameters are:
- on_off: 1 on, 0 off
- brightness: 0-100
If you have an LB120 or KL120 (tunable white), you can also change color temperature:
```javascript
await tplink.getLB120("Lamp LB120").setState(1, 90, 2700);
```
The three parameters for LB120 or KL120 are:
- on_off: 1 on, 0 off
- brightness: 0-100
- color_temp:
- 2500-6500 (LB120)
- 2700-5000 (KL120)
If you have an LB130 or KL130 (multicolor), use this:
```javascript
// to set hue:
await tplink.getLB130("Kitchen LB130").setState(1, 90, 150, 80);
// or to change white color temperature:
await tplink.getLB130("Kitchen LB130").setState(1, 90, 0, 0, 2700);
```
The five parameters for LB130 or KL130 are:
- on_off: 1 on, 0 off
- brightness: 0-100
- hue: 0-360
- saturation: 0-100
- color_temp: 2500-9000
For color bulbs, color_temp overrides hue/saturation. If a bulb is in white mode, color_temp must be set to 0 in order to change colors.
For help to choose the hue/saturation value, you can head to http://colorizer.org/.
# Example
```javascript
const { login } = require("tplink-cloud-api");
const uuidV4 = require("uuid/v4");
const TPLINK_USER = process.env.TPLINK_USER;
const TPLINK_PASS = process.env.TPLINK_PASS;
const TPLINK_TERM = process.env.TPLINK_TERM || uuidV4();
async function main() {
// log in to cloud, return a connected tplink object
const tplink = await login(TPLINK_USER, TPLINK_PASS, TPLINK_TERM);
console.log("current auth token is", tplink.getToken());
// get a list of raw json objects (must be invoked before .get* works)
const dl = await tplink.getDeviceList();
console.log(dl);
// find a device by alias:
let myPlug = tplink.getHS100("My Smart Plug");
// or find by deviceId:
// let myPlug = tplink.getHS100("558185B7EC793602FB8802A0F002BA80CB96F401");
console.log("myPlug:", myPlug);
//let response = await myPlug.powerOn();
//console.log("response=" + response );
let response = await myPlug.toggle();
console.log("response=" + response);
response = await myPlug.getSysInfo();
console.log("relay_state=" + response.relay_state);
console.log(await myPlug.getRelayState());
}
main();
```
## Nodejs App example
You can remix this App on Glitch and call it via webhook using POST to the corresponing URL (given when you create the App):
https://glitch.com/edit/#!/tplink-api-example
# Available methods
## TPLink class
### login()
This _constructor_ method authenticates against the TP-Link cloud API and retrieves a token.
#### Parameters
| Parameter | Specification | Description |
| ---------- | ------------- | ----------------------------------- |
| `user` | String | TP-Link account user name |
| `password` | String | TP-Link account password |
| `termid` | UUIDv4 String | Your client application Terminal ID |
`termid` is an arbitrary value. The API expects a UUIDv4 string, but at this time it doesn't validate this.
#### Returns
Returns the TPLink instance that you can later use to retrieve the Device List.
### getDeviceList()
This method returns an object that describe all the TP-Link devices registred to this TP-Link account.
You need to call this method once after login() in order to be able to get a particular device. Call this method every time you need to refresh the list of devices.
#### Parameters
None
#### Returns
Returns an object that describe all the TP-Link devices registred to this TP-Link account.
# Requires
Requires Node.js > v7.7 (async)