{"id":13550680,"url":"https://github.com/adumont/tplink-cloud-api","last_synced_at":"2025-04-03T00:34:33.857Z","repository":{"id":23422727,"uuid":"98924598","full_name":"adumont/tplink-cloud-api","owner":"adumont","description":"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)","archived":true,"fork":false,"pushed_at":"2022-12-30T20:34:08.000Z","size":248,"stargazers_count":131,"open_issues_count":23,"forks_count":44,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-04T23:05:59.292Z","etag":null,"topics":["hs100","hs110","iot","lb100","lb130","nodejs","npm","npm-module","npm-package","tplink"],"latest_commit_sha":null,"homepage":"https://itnerd.space","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adumont.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-31T19:56:03.000Z","updated_at":"2024-12-23T15:44:31.000Z","dependencies_parsed_at":"2023-01-13T23:16:47.828Z","dependency_job_id":null,"html_url":"https://github.com/adumont/tplink-cloud-api","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adumont%2Ftplink-cloud-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adumont%2Ftplink-cloud-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adumont%2Ftplink-cloud-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adumont%2Ftplink-cloud-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adumont","download_url":"https://codeload.github.com/adumont/tplink-cloud-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246916734,"owners_count":20854511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hs100","hs110","iot","lb100","lb130","nodejs","npm","npm-module","npm-package","tplink"],"created_at":"2024-08-01T12:01:36.117Z","updated_at":"2025-04-03T00:34:28.845Z","avatar_url":"https://github.com/adumont.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/adumont/tplink-cloud-api.svg?branch=master)](https://travis-ci.org/adumont/tplink-cloud-api)\n[![codebeat badge](https://codebeat.co/badges/14afe7d2-3666-4d35-8fd6-c2e1b027e386)](https://codebeat.co/projects/github-com-adumont-tplink-cloud-api-master)\n\n# Introduction\n\nThe `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.\n\nIt'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)...\n\nIt's based on my investigation work on the TP-Link API protocol, which I have been sharing in my blog http://itnerd.space.\n\n# Installation\n\nYou can install this module with `npm`:\n\n```bash\nnpm install --save tplink-cloud-api\n```\n\n# Usage\n\n## Authenticate\n\nFirst instantiate a TP-Link object. TermID (UUIDv4) is generated if not specified:\n\n```javascript\nconst { login } = require(\"tplink-cloud-api\");\nconst tplink = await login(\"username@example.com\", \"Password\", \"TermID\");\n```\n\n## Retrieve devices\n\nOnce authenticated, you can use your tplink instance to retrieve the list of your devices:\n\n```javascript\nlet deviceList = await tplink.getDeviceList();\n```\n\n## Control your devices\n\n### Smartplugs (HS100 \u0026 HS110)\n\nNow you can toggle a plug:\n\n```javascript\nawait tplink.getHS100(\"My Smart Plug\").toggle();\n```\n\nYou can also create an object and use it like this:\n\n```javascript\nlet myPlug = tplink.getHS100(\"My Smart Plug \");\nlet response = await myPlug.toggle();\nconsole.log(await myPlug.getRelayState());\n```\n\nReplace `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.\n\nInstead of `toggle()`, you can use `powerOn()` or `powerOff()`. See all available methods below.\n\nIf you want to trigger multiple plugs, you can do it like this:\n\n```javascript\nawait tplink.getHS100(\"My Smart Plug\").toggle();\nawait tplink.getHS100(\"My Smart Plug 2\").powerOn();\nawait tplink.getHS100(\"My Smart Plug 3\").powerOff();\nawait tplink.getHS100(\"My Smart Plug 4\").powerOff();\n```\n\nTo retrieve power consumption data for the HS110:\n\n```javascript\nawait tplink.getHS110(\"My Smart Plug\").getPowerUsage();\n```\n\n### Smart Switches (HS200, HS300...)\n\nYou can  toggle smart switches with the same API as the smart plugs.\n\nFor 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).\n\n### Smartbulbs (LB100/110/120/130, KL110/120/130)\n\nIf you have an LB100/110 or KL50/60/110 (dimmable), you can change its state with:\n\n```javascript\nawait tplink.getLB100(\"Bedroom LB120\").setState(1, 90);\n```\n\nThe two parameters are:\n\n- on_off: 1 on, 0 off\n- brightness: 0-100\n\nIf you have an LB120 or KL120 (tunable white), you can also change color temperature:\n\n```javascript\nawait tplink.getLB120(\"Lamp LB120\").setState(1, 90, 2700);\n```\n\nThe three parameters for LB120 or KL120 are:\n- on_off: 1 on, 0 off\n- brightness: 0-100\n- color_temp:\n  - 2500-6500 (LB120)\n  - 2700-5000 (KL120)\n\nIf you have an LB130 or KL130 (multicolor), use this:\n\n```javascript\n// to set hue:\nawait tplink.getLB130(\"Kitchen LB130\").setState(1, 90, 150, 80);\n// or to change white color temperature:\nawait tplink.getLB130(\"Kitchen LB130\").setState(1, 90, 0, 0, 2700);\n```\n\nThe five parameters for LB130 or KL130 are:\n\n- on_off: 1 on, 0 off\n- brightness: 0-100\n- hue: 0-360\n- saturation: 0-100\n- color_temp: 2500-9000\n\nFor 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.\n\nFor help to choose the hue/saturation value, you can head to http://colorizer.org/.\n\n# Example\n\n```javascript\nconst { login } = require(\"tplink-cloud-api\");\nconst uuidV4 = require(\"uuid/v4\");\n\nconst TPLINK_USER = process.env.TPLINK_USER;\nconst TPLINK_PASS = process.env.TPLINK_PASS;\nconst TPLINK_TERM = process.env.TPLINK_TERM || uuidV4();\n\nasync function main() {\n  // log in to cloud, return a connected tplink object\n  const tplink = await login(TPLINK_USER, TPLINK_PASS, TPLINK_TERM);\n  console.log(\"current auth token is\", tplink.getToken());\n\n  // get a list of raw json objects (must be invoked before .get* works)\n  const dl = await tplink.getDeviceList();\n  console.log(dl);\n\n  // find a device by alias:\n  let myPlug = tplink.getHS100(\"My Smart Plug\");\n  // or find by deviceId:\n  // let myPlug = tplink.getHS100(\"558185B7EC793602FB8802A0F002BA80CB96F401\");\n  console.log(\"myPlug:\", myPlug);\n\n  //let response = await myPlug.powerOn();\n  //console.log(\"response=\" + response );\n\n  let response = await myPlug.toggle();\n  console.log(\"response=\" + response);\n\n  response = await myPlug.getSysInfo();\n  console.log(\"relay_state=\" + response.relay_state);\n\n  console.log(await myPlug.getRelayState());\n}\n\nmain();\n```\n\n## Nodejs App example\n\nYou can remix this App on Glitch and call it via webhook using POST to the corresponing URL (given when you create the App):\n\nhttps://glitch.com/edit/#!/tplink-api-example\n\n# Available methods\n\n## TPLink class\n\n### login()\n\nThis _constructor_ method authenticates against the TP-Link cloud API and retrieves a token.\n\n#### Parameters\n\n| Parameter  | Specification | Description                         |\n| ---------- | ------------- | ----------------------------------- |\n| `user`     | String        | TP-Link account user name           |\n| `password` | String        | TP-Link account password            |\n| `termid`   | UUIDv4 String | Your client application Terminal ID |\n\n`termid` is an arbitrary value. The API expects a UUIDv4 string, but at this time it doesn't validate this.\n\n#### Returns\n\nReturns the TPLink instance that you can later use to retrieve the Device List.\n\n### getDeviceList()\n\nThis method returns an object that describe all the TP-Link devices registred to this TP-Link account.\n\nYou 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.\n\n#### Parameters\n\nNone\n\n#### Returns\n\nReturns an object that describe all the TP-Link devices registred to this TP-Link account.\n\n# Requires\n\nRequires Node.js \u003e v7.7 (async)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadumont%2Ftplink-cloud-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadumont%2Ftplink-cloud-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadumont%2Ftplink-cloud-api/lists"}