Table of Contents

Class KasaDevice

Namespace
KasaTapoClient
Assembly
KasaTapoClient.dll

Represents a single TP-Link Kasa or Tapo device.

public sealed class KasaDevice : IDisposable
Inheritance
KasaDevice
Implements
Inherited Members

Properties

Alarm

Gets the module-style alarm wrapper.

public AlarmModule Alarm { get; }

Property Value

AlarmModule

AlarmState

Gets the most recent normalized alarm state, when supported by the device.

public AlarmState? AlarmState { get; }

Property Value

AlarmState

Alias

Gets the best known alias for the device.

public string Alias { get; }

Property Value

string

AutoOff

Gets the module-style auto-off wrapper.

public AutoOffModule AutoOff { get; }

Property Value

AutoOffModule

AutoOffState

Gets the most recent auto-off state, when supported by the device.

public AutoOffState? AutoOffState { get; }

Property Value

AutoOffState

AvailableLightEffects

Gets the available light effects reported by the device.

public IReadOnlyList<LightEffectDefinition> AvailableLightEffects { get; }

Property Value

IReadOnlyList<LightEffectDefinition>

ChildDevices

Gets wrapper objects for child devices.

public IReadOnlyList<ChildDevice> ChildDevices { get; }

Property Value

IReadOnlyList<ChildDevice>

ChildLock

Gets the module-style child-lock wrapper.

public ChildLockModule ChildLock { get; }

Property Value

ChildLockModule

ChildLockState

Gets the most recent child-lock state, when supported by the device.

public ChildLockState? ChildLockState { get; }

Property Value

ChildLockState

ChildSetup

Gets the module-style child setup wrapper for smart hub devices.

public ChildSetupModule ChildSetup { get; }

Property Value

ChildSetupModule

Children

Gets the child devices reported by the device.

public IReadOnlyList<ChildDeviceInfo> Children { get; }

Property Value

IReadOnlyList<ChildDeviceInfo>

Cloud

Gets the module-style cloud wrapper.

public CloudModule Cloud { get; }

Property Value

CloudModule

CloudState

Gets the most recent normalized cloud-connection state, when supported by the device.

public CloudConnectionState? CloudState { get; }

Property Value

CloudConnectionState

Configuration

Gets the connection settings for the device.

public DeviceConfiguration Configuration { get; }

Property Value

DeviceConfiguration

Countdown

Gets the module-style countdown wrapper.

public CountdownModule Countdown { get; }

Property Value

CountdownModule

DeviceType

Gets the inferred device family.

public DeviceType DeviceType { get; }

Property Value

DeviceType

Energy

Gets the module-style energy wrapper.

public EnergyModule Energy { get; }

Property Value

EnergyModule

EnergyUsage

Gets the most recent normalized energy usage information, when supported by the device.

public EnergyUsage? EnergyUsage { get; }

Property Value

EnergyUsage

Fan

Gets the module-style fan wrapper.

public FanModule Fan { get; }

Property Value

FanModule

FanState

Gets the most recent normalized fan state, when supported by the device.

public FanState? FanState { get; }

Property Value

FanState

Features

Gets the current feature collection derived from the latest device state.

public IReadOnlyList<DeviceFeature> Features { get; }

Property Value

IReadOnlyList<DeviceFeature>

Firmware

Gets the module-style firmware wrapper.

public FirmwareModule Firmware { get; }

Property Value

FirmwareModule

FirmwareState

Gets the most recent normalized firmware state, when supported by the device.

public FirmwareState? FirmwareState { get; }

Property Value

FirmwareState

HomeKit

Gets the module-style HomeKit wrapper.

public HomeKitModule HomeKit { get; }

Property Value

HomeKitModule

HomeKitSetup

Gets the most recent HomeKit setup information, when supported by the device.

public HomeKitSetupInfo? HomeKitSetup { get; }

Property Value

HomeKitSetupInfo

Host

Gets the current device host.

public string Host { get; }

Property Value

string

IsOn

Gets a value indicating whether the device is currently on.

public bool? IsOn { get; }

Property Value

bool?

Led

Gets the module-style LED wrapper.

public LedModule Led { get; }

Property Value

LedModule

LedState

Gets the most recent LED state, when supported by the device.

public LedState? LedState { get; }

Property Value

LedState

Light

Gets the module-style light wrapper.

public LightModule Light { get; }

Property Value

LightModule

LightEffect

Gets the most recent normalized light effect state, when supported by the device.

public LightEffectState? LightEffect { get; }

Property Value

LightEffectState

LightPreset

Gets the module-style light preset wrapper.

public LightPresetModule LightPreset { get; }

Property Value

LightPresetModule

LightPresetState

Gets the most recent normalized light preset module state, when supported by the device.

public LightPresetState? LightPresetState { get; }

Property Value

LightPresetState

LightState

Gets the most recent normalized light state, when supported by the device.

public LightState? LightState { get; }

Property Value

LightState

LightStripEffect

Gets the module-style light strip effect wrapper.

public LightStripEffectModule LightStripEffect { get; }

Property Value

LightStripEffectModule

LightStripEffectState

Gets the most recent normalized light strip effect module state, when supported by the device.

public LightStripEffectState? LightStripEffectState { get; }

Property Value

LightStripEffectState

LightTransition

Gets the module-style light transition wrapper.

public LightTransitionModule LightTransition { get; }

Property Value

LightTransitionModule

LightTransitionState

Gets the most recent normalized light transition module state, when supported by the device.

public LightTransitionState? LightTransitionState { get; }

Property Value

LightTransitionState

Matter

Gets the module-style Matter wrapper.

public MatterModule Matter { get; }

Property Value

MatterModule

MatterSetup

Gets the most recent Matter setup information, when supported by the device.

public MatterSetupInfo? MatterSetup { get; }

Property Value

MatterSetupInfo

OnSince

Gets the derived timestamp for when the device was turned on, when reported.

public DateTimeOffset? OnSince { get; }

Property Value

DateTimeOffset?

OverheatProtection

Gets the module-style overheat protection wrapper.

public OverheatProtectionModule OverheatProtection { get; }

Property Value

OverheatProtectionModule

OverheatProtectionState

Gets the most recent normalized overheat protection state, when supported by the device.

public OverheatProtectionState? OverheatProtectionState { get; }

Property Value

OverheatProtectionState

PowerProtection

Gets the module-style power protection wrapper.

public PowerProtectionModule PowerProtection { get; }

Property Value

PowerProtectionModule

PowerProtectionState

Gets the most recent normalized power protection state, when supported by the device.

public PowerProtectionState? PowerProtectionState { get; }

Property Value

PowerProtectionState

Rssi

Gets the most recent host RSSI value in dBm when the device reports it.

public int? Rssi { get; }

Property Value

int?

RuleState

Gets the most recent normalized rule module state, when supported by the device.

public RuleModuleState? RuleState { get; }

Property Value

RuleModuleState

Rules

Gets the module-style rules wrapper.

public RuleModule Rules { get; }

Property Value

RuleModule

Speaker

Gets the module-style speaker wrapper.

public SpeakerModule Speaker { get; }

Property Value

SpeakerModule

SpeakerState

Gets the most recent normalized speaker state, when supported by the device.

public SpeakerState? SpeakerState { get; }

Property Value

SpeakerState

SupportsLightEffects

Gets a value indicating whether the device reports light-effect capability.

public bool SupportsLightEffects { get; }

Property Value

bool

System

Gets the module-style system wrapper.

public SystemModule System { get; }

Property Value

SystemModule

SystemInfo

Gets the most recent normalized system information, or null until UpdateAsync(CancellationToken) succeeds.

public DeviceSystemInfo? SystemInfo { get; }

Property Value

DeviceSystemInfo

Time

Gets the module-style time wrapper.

public TimeModule Time { get; }

Property Value

TimeModule

TimeState

Gets the most recent normalized device-local time state, when supported by the device.

public DeviceTimeState? TimeState { get; }

Property Value

DeviceTimeState

Usage

Gets the module-style usage wrapper.

public UsageModule Usage { get; }

Property Value

UsageModule

Methods

ClearLightEffectAsync(CancellationToken)

Disables the current lighting effect and refreshes state.

public Task ClearLightEffectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light effect state has been refreshed.

Dispose()

Releases transport resources owned by the device.

public void Dispose()

ExecuteCommandAsync(string, CancellationToken)

Executes a raw JSON command against the device.

public Task<string> ExecuteCommandAsync(string commandJson, CancellationToken cancellationToken = default)

Parameters

commandJson string

The command payload to send.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<string>

The raw JSON response payload from the device.

Exceptions

ArgumentException

Thrown when commandJson is empty or whitespace.

GetChild(string)

Returns a child device by identifier when present.

public ChildDeviceInfo? GetChild(string childDeviceId)

Parameters

childDeviceId string

The child device identifier.

Returns

ChildDeviceInfo

The matching child device, or null if not found.

GetChildDevice(string)

Returns a child-device wrapper by identifier when present.

public ChildDevice? GetChildDevice(string childDeviceId)

Parameters

childDeviceId string

The child device identifier.

Returns

ChildDevice

The matching child-device wrapper, or null if not found.

GetFeature(string)

Returns a feature by identifier when present.

public DeviceFeature? GetFeature(string featureId)

Parameters

featureId string

The feature identifier.

Returns

DeviceFeature

The matching feature, or null if not found.

GetScannedChildDevicesAsync(CancellationToken)

Gets the currently detected child devices from the smart hub scan state.

public Task<ChildSetupScanResult> GetScannedChildDevicesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<ChildSetupScanResult>

The detected child devices and supported categories reported by the hub.

Exceptions

InvalidOperationException

Thrown when the device does not support smart hub child setup operations.

PairScannedChildDevicesAsync(IReadOnlyList<DetectedChildDevice>, CancellationToken)

Pairs the specified detected child devices with the smart hub.

public Task<IReadOnlyList<DetectedChildDevice>> PairScannedChildDevicesAsync(IReadOnlyList<DetectedChildDevice> devices, CancellationToken cancellationToken = default)

Parameters

devices IReadOnlyList<DetectedChildDevice>

The detected child devices to pair.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<IReadOnlyList<DetectedChildDevice>>

The subset of requested devices that were confirmed as added after refresh.

Exceptions

InvalidOperationException

Thrown when the device does not support smart hub child setup operations.

ScanForChildDevicesAsync(int, CancellationToken)

Starts a smart hub child-device scan, waits for the requested interval, and returns the detected devices.

public Task<ChildSetupScanResult> ScanForChildDevicesAsync(int timeoutSeconds = 10, CancellationToken cancellationToken = default)

Parameters

timeoutSeconds int

The number of seconds to wait after beginning the scan before reading detected devices.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<ChildSetupScanResult>

The detected child devices and supported categories reported by the hub.

Exceptions

InvalidOperationException

Thrown when the device does not support smart hub child setup operations.

SetBrightnessAsync(int, CancellationToken)

Sets the brightness percentage and refreshes state.

public Task SetBrightnessAsync(int brightness, CancellationToken cancellationToken = default)

Parameters

brightness int

The brightness percentage from 0 through 100.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light state has been refreshed.

Exceptions

ArgumentOutOfRangeException

Thrown when brightness is outside the inclusive range of 0 through 100.

SetColorTemperatureAsync(int, CancellationToken)

Sets the color temperature in kelvin and refreshes state.

public Task SetColorTemperatureAsync(int colorTemperature, CancellationToken cancellationToken = default)

Parameters

colorTemperature int

The color temperature, in kelvin, to apply to the light.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light state has been refreshed.

Exceptions

ArgumentOutOfRangeException

Thrown when colorTemperature is zero or negative.

SetHsvAsync(int, int, int, CancellationToken)

Sets the hue, saturation, and value components and refreshes state.

public Task SetHsvAsync(int hue, int saturation, int value, CancellationToken cancellationToken = default)

Parameters

hue int

The hue component from 0 through 360.

saturation int

The saturation component from 0 through 100.

value int

The value or brightness component from 0 through 100.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light state has been refreshed.

Exceptions

ArgumentOutOfRangeException

Thrown when hue, saturation, or value falls outside its supported range.

SetLightEffectAsync(string, CancellationToken)

Enables a lighting effect by device-specific name or identifier and refreshes state.

public Task SetLightEffectAsync(string effect, CancellationToken cancellationToken = default)

Parameters

effect string

The device-specific light effect name or identifier.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light effect state has been refreshed.

Exceptions

ArgumentException

Thrown when effect is empty or whitespace.

TurnChildOffAsync(string, CancellationToken)

Turns a child device off and refreshes the parent device state.

public Task TurnChildOffAsync(string childDeviceId, CancellationToken cancellationToken = default)

Parameters

childDeviceId string

The child device identifier.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the child device and parent state have been refreshed.

TurnChildOnAsync(string, CancellationToken)

Turns a child device on and refreshes the parent device state.

public Task TurnChildOnAsync(string childDeviceId, CancellationToken cancellationToken = default)

Parameters

childDeviceId string

The child device identifier.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the child device and parent state have been refreshed.

TurnLightOffAsync(CancellationToken)

Turns the light off and refreshes state.

public Task TurnLightOffAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light state has been refreshed.

TurnLightOnAsync(CancellationToken)

Turns the light on and refreshes state.

public Task TurnLightOnAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the light state has been refreshed.

TurnOffAsync(CancellationToken)

Turns the device off and refreshes its state.

public Task TurnOffAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the device has been updated.

TurnOnAsync(CancellationToken)

Turns the device on and refreshes its state.

public Task TurnOnAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the device has been updated.

UnpairChildDeviceAsync(string, CancellationToken)

Removes a child device from the smart hub and refreshes state.

public Task UnpairChildDeviceAsync(string childDeviceId, CancellationToken cancellationToken = default)

Parameters

childDeviceId string

The child device identifier to remove.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the child device has been removed and state refreshed.

Exceptions

InvalidOperationException

Thrown when the device does not support smart hub child setup operations.

UpdateAsync(CancellationToken)

Refreshes SystemInfo by querying the device.

public Task UpdateAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task

A task that completes when the device state has been refreshed.

UpdateEnergyUsageAsync(CancellationToken)

Refreshes EnergyUsage when the device exposes emeter telemetry.

public Task<bool> UpdateEnergyUsageAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<bool>

true when energy usage data was returned; otherwise, false.

Edit this page