{"id":16990536,"url":"https://github.com/smdn/smdn.tpsmarthomedevices","last_synced_at":"2025-04-12T03:31:45.223Z","repository":{"id":123748585,"uuid":"610762060","full_name":"smdn/Smdn.TPSmartHomeDevices","owner":"smdn","description":".NET libraries for operating Tapo/Kasa, the TP-Link smart home devices.","archived":false,"fork":false,"pushed_at":"2025-01-30T10:26:34.000Z","size":1133,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T16:49:50.410Z","etag":null,"topics":["csharp","dotnet","homeautomation","kasa","kasa-devices","kasa-hs105","kasa-kl130","library","smartdevices","tapo","tapo-devices","tapo-l530","tapo-l900","tapo-light-bulb","tapo-light-strip","tapo-p105","tapo-p110m","tapo-smart-plug"],"latest_commit_sha":null,"homepage":"","language":"C#","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/smdn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"smdn","custom":["https://www.amazon.jp/hz/wishlist/ls/1K0WOH22FCL6W?ref_=wl_share\u0026filter=all\u0026sort=priority"]}},"created_at":"2023-03-07T12:37:19.000Z","updated_at":"2025-01-30T10:26:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"af849102-3649-4e79-a30d-8d88746d21a8","html_url":"https://github.com/smdn/Smdn.TPSmartHomeDevices","commit_stats":{"total_commits":450,"total_committers":3,"mean_commits":150.0,"dds":0.07111111111111112,"last_synced_commit":"a7ea2d7ba087277b6b683a1b5b8bfbd54b92bf88"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smdn%2FSmdn.TPSmartHomeDevices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smdn%2FSmdn.TPSmartHomeDevices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smdn%2FSmdn.TPSmartHomeDevices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smdn%2FSmdn.TPSmartHomeDevices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smdn","download_url":"https://codeload.github.com/smdn/Smdn.TPSmartHomeDevices/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248512745,"owners_count":21116674,"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":["csharp","dotnet","homeautomation","kasa","kasa-devices","kasa-hs105","kasa-kl130","library","smartdevices","tapo","tapo-devices","tapo-l530","tapo-l900","tapo-light-bulb","tapo-light-strip","tapo-p105","tapo-p110m","tapo-smart-plug"],"created_at":"2024-10-14T03:10:26.182Z","updated_at":"2025-04-12T03:31:44.773Z","avatar_url":"https://github.com/smdn.png","language":"C#","funding_links":["https://github.com/sponsors/smdn","https://www.amazon.jp/hz/wishlist/ls/1K0WOH22FCL6W?ref_=wl_share\u0026filter=all\u0026sort=priority","https://github.com/sponsors/smdn?frequency=one-time"],"categories":[],"sub_categories":[],"readme":"[![GitHub license](https://img.shields.io/github/license/smdn/Smdn.TPSmartHomeDevices)](https://github.com/smdn/Smdn.TPSmartHomeDevices/blob/main/COPYING.txt)\n[![tests/main](https://img.shields.io/github/actions/workflow/status/smdn/Smdn.TPSmartHomeDevices/test.yml?branch=main\u0026label=tests%2Fmain)](https://github.com/smdn/Smdn.TPSmartHomeDevices/actions/workflows/test.yml)\n[![CodeQL](https://github.com/smdn/Smdn.TPSmartHomeDevices/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/smdn/Smdn.TPSmartHomeDevices/actions/workflows/codeql-analysis.yml)\n\n# Smdn.TPSmartHomeDevices\nThe .NET implementations for controlling [Kasa](https://www.kasasmart.com) and [Tapo](https://www.tapo.com/), the TP-Link smart home devices.\n\n## Smdn.TPSmartHomeDevices.Tapo / Smdn.TPSmartHomeDevices.Kasa\n- Smdn.TPSmartHomeDevices.Tapo: [![NuGet](https://img.shields.io/nuget/v/Smdn.TPSmartHomeDevices.Tapo.svg)](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Tapo/) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n- Smdn.TPSmartHomeDevices.Kasa: [![NuGet](https://img.shields.io/nuget/v/Smdn.TPSmartHomeDevices.Kasa.svg)](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Kasa/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)|\n\n[Smdn.TPSmartHomeDevices.Tapo](./src/Smdn.TPSmartHomeDevices.Tapo/) and [Smdn.TPSmartHomeDevices.Kasa](./src/Smdn.TPSmartHomeDevices.Kasa/) are class libraries that provide .NET APIs for operating Tapo and Kasa smart home devices.\n\nThese class libraries provide device classes such as `L530` (`Smdn.TPSmartHomeDevices.Tapo` namespace) and `KL130` (`Smdn.TPSmartHomeDevices.Kasa` namespace), which have the same name as the device's product model name.\n\nThese device classes perform operations by communicating directly with Tapo/Kasa devices in the same network. Remote operation via the Internet is not supported.\n\n```csharp\nusing Smdn.TPSmartHomeDevices.Tapo;\n\n// Creates device object for L530 multicolor light bulb\nusing var bulb = new L530(\n  \"192.0.2.1\",      // IP address currently assigned to the device\n  \"user@mail.test\", // E-mail address for your Tapo account\n  \"password\"        // Password for your Tapo account\n);\n\n// Sets the color temperature and brightness.\n// In the off state, the bulb will automatically turn on.\nawait bulb.SetColorTemperatureAsync(colorTemperature: 5500, brightness: 80);\n```\n\n### Supported device and functions\n#### Supported devices\nThe following devices have been confirmed to work on the actual devices:\n\n|Model|Device type|Hardware version|Hardware specs|Firmware version|Usage example|\n|-|-|-|-|-|-|\n|Tapo L530|Bulb|1.0.0\u003cbr/\u003e1.20|JP\u003cbr/\u003eJP|1.3.0 Build 20230831 Rel. 75926\u003cbr/\u003e1.1.0 Build 230823 Rel.162531|[example](./examples/Smdn.TPSmartHomeDevices.Tapo/L530MulticolorBulb/)|\n|Tapo L900|Light strip|1.0|-|1.1.0 Build 230905 Rel.184939|[example](./examples/Smdn.TPSmartHomeDevices.Tapo/L900MulticolorLightStrip/)|\n|Tapo P105|Plug|1.0.0|JP|1.4.1 Build 20231103 Rel. 36519|[example](./examples/Smdn.TPSmartHomeDevices.Tapo/P105Plug/)|\n|Tapo P110M|Plug|1.0|JP|1.1.0 Build 231009 Rel.155719|[example](./examples/Smdn.TPSmartHomeDevices.Tapo/P110MPlug/)|\n|Kasa KL130|Bulb|1.0|JP|1.8.11 Build 191113 Rel.105336|[example](./examples/Smdn.TPSmartHomeDevices.Kasa/KL130MulticolorBulb/)|\n|Kasa HS105|Plug|1.0|JP|1.5.8 Build 191125 Rel.135255|[example](./examples/Smdn.TPSmartHomeDevices.Kasa/HS105Plug/)|\n\n#### Supported functions\nThe library supports performing the following device functions:\n\n- Turn on/off\n- Set color (color temperature)\n- Set color (hue and saturation)\n- Set brightness\n- Get on/off stete\n- Get current light color/brightness\n- Get monitoring data: power consumption and cumulative energy usage [Tapo P110M]\n- Get device informations ([Tapo example](./examples/Smdn.TPSmartHomeDevices.Tapo/DisplayDeviceInfo/), [Kasa example](./examples/Smdn.TPSmartHomeDevices.Kasa/DisplayDeviceInfo/))\n- Get device usage: operating time and cumulative energy usage (only for Tapo devices, [example](./examples/Smdn.TPSmartHomeDevices.Tapo/DeviceUsage/))\n\n#### Confirmed to work\nThe library has been tested and confirmed to work with actual devices, on the following environments:\n- Windows 10\n- Ubuntu 22.04 LTS\n- Raspbian GNU/Linux 9.13 (stretch); Raspberry Pi 3 Model B+\n\n\n### More library features\nThe device class such as `L530` does not simply provide methods to wrap the sending of requests to the device. `Smdn.TPSmartHomeDevices.Tapo` and `Smdn.TPSmartHomeDevices.Kasa` also provides the following features.\n\nThe following example illustrates the basic API usage as well as what happens in the background of a method.\n\n```csharp\nusing Smdn.TPSmartHomeDevices.Tapo;\n\n// Creates client for L530 multicolor light bulb\nusing var bulb = new L530(\"192.0.2.1\", \"user@mail.test\", \"password\");\n\n// Turn on the bulb, and set the color temperature and brightness.\nawait bulb.SetColorTemperatureAsync(colorTemperature: 5500, brightness: 80);\n//    Here, connections and sessions are established automatically.\n//    Also attempts retry automatically when recoverable errors\n//    such as device busy or timeout occur.\n\n// Suppose a few minutes, hours or days passes here.\nawait Task.Delay(TimeSpan.FromHours(...));\n\n// Then, sets the color and brightness of the bulb.\nawait bulb.SetColorTemperatureAsync(colorTemperature: 4000, brightness: 40);\n//    At this time, if the connection or session has expired,\n//    it will attempt to reconnect/re-authenticate automatically.\n//    Also, if the connection is established using a MAC address and\n//    the resolved endpoint is unreachable, it will attempt to\n//    resolve it again. (requires Smdn.TPSmartHomeDevices.MacAddressEndPoint)\n```\n\n#### Automated session management\nConnection and authentication to the device is performed automatically when a request is sent to the device. Reconnection and reauthentication is also performed automatically when an exception occurs or when a session expires.\n\n#### Built-in and customizable retry and error handling\nBuilt-in error handling is provided by default for typical errors such as device busy, session expired, or request timeout. Customized error handling is also available, allowing you to define handling for each type of exception and retries. See [Tapo example](./examples/Smdn.TPSmartHomeDevices.Tapo/CustomExceptionHandling/) and [Kasa example](./examples/Smdn.TPSmartHomeDevices.Kasa/CustomExceptionHandling/).\n\n#### Supports default protocol (`securePassthrough`) and new protocol (`KLAP`)\n`Smdn.TPSmartHomeDevices.Tapo` version 2.0.0 or later supports the new protocol `KLAP` for Tapo devices. By default, the appropriate protocol is automatically selected. You can also explicitly specify a protocol. See [this example](./examples/Smdn.TPSmartHomeDevices.Tapo/SelectProtocol/).\n\n#### Addressing devices using MAC addresses\nSupports specifying device endpoint by MAC address. This is useful in networks with variable IP addresses, such as networks using DHCP. This feature requires an extension library [Smdn.TPSmartHomeDevices.MacAddressEndPoint](#smdntpsmarthomedevicesmacaddressendpoint).\n\n#### Other features\n- Supports dependency injection (`Microsoft.Extensions.DependencyInjection`)\n  - Logging (`Microsoft.Extensions.Logging`) - [Tapo example](./examples/Smdn.TPSmartHomeDevices.Tapo/Logging/), [Kasa example](./examples/Smdn.TPSmartHomeDevices.Kasa/Logging/)\n  - HTTP (`Microsoft.Extensions.Http`) - [example](./examples/Smdn.TPSmartHomeDevices.Tapo/ConfigureTimeout/)\n- Providing Tapo credentials via environment variables - [example](./examples/Smdn.TPSmartHomeDevices.Tapo/CredentialsEnvVar/)\n- Customizable Tapo credential provider - [example](./examples/Smdn.TPSmartHomeDevices.Tapo/Credentials/)\n- Configuring timeout and cancellation - [Tapo example](./examples/Smdn.TPSmartHomeDevices.Tapo/ConfigureTimeout/), [Kasa example](./examples/Smdn.TPSmartHomeDevices.Kasa/ConfigureTimeout/)\n\n### Recommended usage on Tapo devices\nTapo devices have introduced secure authentication methods in new firmware released after summer 2023. If new firmware is installed, hashed credentials can be used for authentication. This means that it is no longer necessary to embed the username and password in plain text.\n\nAdditionally, Smdn.TPSmartHomeDevices.Tapo can retrieve hashed credentials from environment variables.\n\nThe following code shows an example of retrieving hashed credential from the `TAPO_KLAP_LOCALAUTHHASH` environment variable and using it when authenticating to a Tapo device.\n\n```csharp\nusing Microsoft.Extensions.DependencyInjection;\n\nusing Smdn.TPSmartHomeDevices.Tapo;\nusing Smdn.TPSmartHomeDevices.Tapo.Credentials;\nusing Smdn.TPSmartHomeDevices.Tapo.Protocol;\n\nvar services = new ServiceCollection();\n\n// Specifies that the device should be operated using the newer protocol.\nservices.AddTapoProtocolSelector(TapoSessionProtocol.Klap);\n\n// Specifies the environment variable in which the hashed credential\n// used for authentication is set.\nservices.AddTapoBase64EncodedKlapCredentialFromEnvironmentVariable(\n  envVarBase64KlapLocalAuthHash: \"TAPO_KLAP_LOCALAUTHHASH\"\n);\n\nusing var plug = new P105(\"192.0.2.1\", services.BuildServiceProvider());\n\nawait plug.TurnOnAsync();\n```\n\nThe environment variable `TAPO_KLAP_LOCALAUTHHASH` has to be a BASE64 string calculated by the formula `BASE64(SHA256(SHA1(username) + SHA1(password)))`. See [this example](./examples/Smdn.TPSmartHomeDevices.Tapo/CredentialsEnvVar/) for detail.\n\n\u003e [!NOTE]\n\u003e Although `Smdn.TPSmartHomeDevices.Tapo` still supports devices with older protocol/firmware, it is recommended that you update your Tapo device's firmware to the latest version before using the library.\n\n\n\n### Feature Request\nIf you have a request that you would like library to add API for the device functions to devices currently supported, please send it as a [Feature Request](/../../issues/new?template=02_feature-request.yml) or Pull Request.\n\n\u003e [!NOTE]\n\u003e See also [Contribution guidelines](#for-contributers).\n\nIf you would like to request support for a device that is not currently supported, please send a Pull Request. Alternatively, please consider [supporting this project](https://github.com/sponsors/smdn?frequency=one-time) through GitHub Sponsors.\n\n[![](https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86)](https://github.com/sponsors/smdn?frequency=one-time)\n\nWhen adding support for a new device, I would like to purchase and perform testing with the actual device as much as possible, if it is available in Japan.\n\n## Smdn.TPSmartHomeDevices.MacAddressEndPoint\n[![NuGet](https://img.shields.io/nuget/v/Smdn.TPSmartHomeDevices.MacAddressEndPoint.svg)](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.MacAddressEndPoint/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[Smdn.TPSmartHomeDevices.MacAddressEndPoint](./src/Smdn.TPSmartHomeDevices.MacAddressEndPoint/) is an extension library that enables to use MAC addresses to specify the device endpoints, instead of IP addresses or host names. This library also enables to support following changes of the device endpoint in network where IP addresses are dynamic, such as networks using DHCP.\n\nSee [this example](./examples/Smdn.TPSmartHomeDevices.MacAddressEndPoint/MacAddressResolution/) for using MAC addresses to identify the Tapo and Kasa devices.\n\nThis library relies on [Smdn.Net.AddressResolution](https://www.nuget.org/packages/Smdn.Net.AddressResolution) [![Smdn.Net.AddressResolution](https://img.shields.io/nuget/v/Smdn.Net.AddressResolution.svg)](https://www.nuget.org/packages/Smdn.Net.AddressResolution/) for MAC address resolution. For further details such as functions and supported platforms, refer [smdn/Smdn.Net.AddressResolution](https://github.com/smdn/Smdn.Net.AddressResolution) repository.\n\n## Smdn.TPSmartHomeDevices.Primitives\n[![NuGet](https://img.shields.io/nuget/v/Smdn.TPSmartHomeDevices.Primitives.svg)](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Primitives/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[Smdn.TPSmartHomeDevices.Primitives](./src/Smdn.TPSmartHomeDevices.Primitives/) provides common types for `Smdn.TPSmartHomeDevices.*`. This library includes abstraction interfaces, extension methods and custom `JsonConverter`s. This library does not provide any specific implementations to operate Kasa and Tapo devices.\n\nMore description to be added.\n\n# For contributers\nContributions are appreciated!\n\nIf there's a feature you would like to add or a bug you would like to fix, please read [Contribution guidelines](./CONTRIBUTING.md) and create an Issue or Pull Request.\n\nIssueやPull Requestを送る際は、[Contribution guidelines](./CONTRIBUTING.md)をご覧頂ください。　可能なら英語が望ましいですが、日本語で構いません。\n\n# Notice\n\u003c!-- #pragma section-start NupkgReadmeFile_Notice --\u003e\n## License\nThis project is licensed under the [GNU GPL version 3 or later](./COPYING.txt).\n\nThis project includes source code licensed under MIT or GPLv3 as described below and produces artifacts licensed in accordance therewith.\n\n### Smdn.TPSmartHomeDevices.Tapo (GPLv3)\nThe some source files in the directory under the [src/Smdn.TPSmartHomeDevices.Tapo/](./src/Smdn.TPSmartHomeDevices.Tapo/) include codes that has been ported from codes which licensed under the GPLv3, and are licensed under the [GNU GPL version 3 or later](./src/Smdn.TPSmartHomeDevices.Tapo/COPYING.txt).\n\nTherefore, artifacts from this directory, including NuGet package [Smdn.TPSmartHomeDevices.Tapo](https://www.nuget.org/packages/Smdn.TPSmartHomeDevices.Tapo/), are released under the [GNU GPL version 3 or later](./src/Smdn.TPSmartHomeDevices.Tapo/COPYING.txt).\n\nFor the license of individual files, refer to `SPDX-License-Identifier` at the top of each file header.\n\n### Smdn.TPSmartHomeDevices.Kasa, Smdn.TPSmartHomeDevices.MacAddressEndPoint, Smdn.TPSmartHomeDevices.Primitives (MIT)\nThe source files and generated artifacts from the directory under the [src/](./src/), excluding Smdn.TPSmartHomeDevices.Tapo, are licensed and released under the terms of the [MIT License](./src/LICENSE.txt).\n\n## Disclaimer\n(An English translation for the reference follows the text written in Japanese.)\n\n本プロジェクトは、TP-Linkとは無関係の非公式なものです。\n\nThis is an unofficial project that has no affiliation with TP-Link.\n\n本プロジェクトが提供するソフトウェアは、デバイスの設定の取得・変更等、製品仕様の範囲内での操作のみを行うものであり、ファームウェアの改変・修正および製品の改造や製品仕様の変更を引き起こさないものの、**製品使用上の許諾事項に抵触する可能性は否定できないため、使用の際はその点にご留意ください。**\n\nThe software provided by this project is intended only for operations within the scope of the product specifications, such as acquiring and changing device settings, and while it does not cause altering the product itself, product's firmware or operating specifications. **Nevertheless, please note that the possibility of violating terms of use of the product cannot be dismissed when using the software provided by this project.**\n\n[Tapo](https://www.tapo.com/)、[Kasa](https://www.kasasmart.com/)、および各製品名の著作権は[TP-Link](https://www.tp-link.com/)に帰属します。\n\n[Tapo](https://www.tapo.com/), [Kasa](https://www.kasasmart.com/) and all respective product names are copyright of [TP-Link](https://www.tp-link.com/).\n\n## Credit\nThis project incorporates implementations partially ported from the following projects. See also [ThirdPartyNotices.md](./ThirdPartyNotices.md) for detail.\n\n- [fishbigger/TapoP100](https://github.com/fishbigger/TapoP100)\n- [europowergenerators/Tapo-plug-controller](https://github.com/europowergenerators/Tapo-plug-controller)\n- [petretiandrea/plugp100](https://github.com/petretiandrea/plugp100)\n- [plasticrake/tplink-smarthome-api](https://github.com/plasticrake/tplink-smarthome-api/)\n- [plasticrake/tplink-smarthome-crypto](https://github.com/plasticrake/tplink-smarthome-crypto)\n\n\u003c!-- #pragma section-end NupkgReadmeFile_Notice --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmdn%2Fsmdn.tpsmarthomedevices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmdn%2Fsmdn.tpsmarthomedevices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmdn%2Fsmdn.tpsmarthomedevices/lists"}