Smdn.TPSmartHomeDevices

The .NET implementations for controlling Kasa and Tapo, the TP-Link smart home devices.

Smdn.TPSmartHomeDevices.Tapo / Smdn.TPSmartHomeDevices.Kasa

• Smdn.TPSmartHomeDevices.Tapo:
• Smdn.TPSmartHomeDevices.Kasa: |

Smdn.TPSmartHomeDevices.Tapo and Smdn.TPSmartHomeDevices.Kasa are class libraries that provide .NET APIs for operating Tapo and Kasa smart home devices.

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

These device classes perform operations by communicating directly with Tapo/Kasa devices in the same network. Remote operation via the Internet is not supported.

using Smdn.TPSmartHomeDevices.Tapo;

// Creates device object for L530 multicolor light bulb
using var bulb = new L530(
  "192.0.2.1",      // IP address currently assigned to the device
  "user@mail.test", // E-mail address for your Tapo account
  "password"        // Password for your Tapo account
);

// Sets the color temperature and brightness.
// In the off state, the bulb will automatically turn on.
await bulb.SetColorTemperatureAsync(colorTemperature: 5500, brightness: 80);

Supported device and functions

Supported devices

The following devices have been confirmed to work on the actual devices:

|Model|Device type|Hardware version|Hardware specs|Firmware version|Usage example| |-|-|-|-|-|-| |Tapo L530|Bulb|1.0.0<br/>1.20|JP<br/>JP|1.3.0 Build 20230831 Rel. 75926<br/>1.1.0 Build 230823 Rel.162531|example| |Tapo L900|Light strip|1.0|-|1.1.0 Build 230905 Rel.184939|example| |Tapo P105|Plug|1.0.0|JP|1.4.1 Build 20231103 Rel. 36519|example| |Tapo P110M|Plug|1.0|JP|1.1.0 Build 231009 Rel.155719|example| |Kasa KL130|Bulb|1.0|JP|1.8.11 Build 191113 Rel.105336|example| |Kasa HS105|Plug|1.0|JP|1.5.8 Build 191125 Rel.135255|example|

Supported functions

The library supports performing the following device functions:

• Turn on/off
• Set color (color temperature)
• Set color (hue and saturation)
• Set brightness
• Get on/off stete
• Get current light color/brightness
• Get monitoring data: power consumption and cumulative energy usage [Tapo P110M]
• Get device informations (Tapo example, Kasa example)
• Get device usage: operating time and cumulative energy usage (only for Tapo devices, example)

Confirmed to work

The library has been tested and confirmed to work with actual devices, on the following environments:

• Windows 10
• Ubuntu 22.04 LTS
• Raspbian GNU/Linux 9.13 (stretch); Raspberry Pi 3 Model B+

More library features

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

The following example illustrates the basic API usage as well as what happens in the background of a method.

using Smdn.TPSmartHomeDevices.Tapo;

// Creates client for L530 multicolor light bulb
using var bulb = new L530("192.0.2.1", "user@mail.test", "password");

// Turn on the bulb, and set the color temperature and brightness.
await bulb.SetColorTemperatureAsync(colorTemperature: 5500, brightness: 80);
//    Here, connections and sessions are established automatically.
//    Also attempts retry automatically when recoverable errors
//    such as device busy or timeout occur.

// Suppose a few minutes, hours or days passes here.
await Task.Delay(TimeSpan.FromHours(...));

// Then, sets the color and brightness of the bulb.
await bulb.SetColorTemperatureAsync(colorTemperature: 4000, brightness: 40);
//    At this time, if the connection or session has expired,
//    it will attempt to reconnect/re-authenticate automatically.
//    Also, if the connection is established using a MAC address and
//    the resolved endpoint is unreachable, it will attempt to
//    resolve it again. (requires Smdn.TPSmartHomeDevices.MacAddressEndPoint)

Automated session management

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

Built-in and customizable retry and error handling

Built-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 and Kasa example.

Supports default protocol (securePassthrough) and new protocol (KLAP)

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.

Addressing devices using MAC addresses

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

Other features

• Supports dependency injection (Microsoft.Extensions.DependencyInjection)
  • Logging (Microsoft.Extensions.Logging) - Tapo example, Kasa example
  • HTTP (Microsoft.Extensions.Http) - example
• Providing Tapo credentials via environment variables - example
• Customizable Tapo credential provider - example
• Configuring timeout and cancellation - Tapo example, Kasa example

Recommended usage on Tapo devices

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

Additionally, Smdn.TPSmartHomeDevices.Tapo can retrieve hashed credentials from environment variables.

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

using Microsoft.Extensions.DependencyInjection;

using Smdn.TPSmartHomeDevices.Tapo;
using Smdn.TPSmartHomeDevices.Tapo.Credentials;
using Smdn.TPSmartHomeDevices.Tapo.Protocol;

var services = new ServiceCollection();

// Specifies that the device should be operated using the newer protocol.
services.AddTapoProtocolSelector(TapoSessionProtocol.Klap);

// Specifies the environment variable in which the hashed credential
// used for authentication is set.
services.AddTapoBase64EncodedKlapCredentialFromEnvironmentVariable(
  envVarBase64KlapLocalAuthHash: "TAPO_KLAP_LOCALAUTHHASH"
);

using var plug = new P105("192.0.2.1", services.BuildServiceProvider());

await plug.TurnOnAsync();

The environment variable TAPO_KLAP_LOCALAUTHHASH has to be a BASE64 string calculated by the formula BASE64(SHA256(SHA1(username) + SHA1(password))). See this example for detail.

[!NOTE] 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.

Feature Request

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