API Reference

Discover

Device

Device Config

Modules and Features

Package for interfaces.

class kasa.interfaces.Alarm(device: Device, module: str)

Base interface to represent an alarm module.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property active: bool

Return true if alarm is active.

abstract property alarm_duration: Annotated[int, FeatureAttribute]

Return alarm duration.

abstract property alarm_sound: Annotated[str, FeatureAttribute]

Return current alarm sound.

abstract property alarm_sounds: list[str]

Return list of available alarm sounds.

abstract property alarm_volume: Annotated[int, FeatureAttribute]

Return alarm volume.

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstractmethod async play(*, duration: int | None = None, volume: int | None = None, sound: str | None = None) → dict

Play alarm.

The optional duration, volume, and sound to override the device settings. duration is in seconds. See alarm_sounds for the list of sounds available for the device.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_alarm_duration(duration: int) → Annotated[dict, FeatureAttribute]

Set alarm duration.

abstractmethod async set_alarm_sound(sound: str) → Annotated[dict, FeatureAttribute]

Set alarm sound.

See alarm_sounds for list of available sounds.

abstractmethod async set_alarm_volume(volume: int) → Annotated[dict, FeatureAttribute]

Set alarm volume.

abstractmethod async stop() → dict

Stop alarm.

class kasa.interfaces.ChildSetup(device: Device, module: str)

Interface for child setup on hubs.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstractmethod async pair(*, timeout: int = 10) → list[dict]

Scan for new devices and pair them.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstract property supported_categories: list[str]

Supported child device categories.

abstractmethod async unpair(device_id: str) → dict

Remove device from the hub.

class kasa.interfaces.Energy(device: Device, module: str)

Base interface to represent an Energy module.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

class ModuleFeature(*values)

Features supported by the device.

CONSUMPTION_TOTAL = 2

Device reports consumption_total

PERIODIC_STATS = 4

Device reports periodic stats via get_daily_stats() and get_monthly_stats()

VOLTAGE_CURRENT = 1

Device reports voltage and current

as_integer_ratio()

Return a pair of integers, whose ratio is equal to the original int.

The ratio is in lowest terms and has a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

bit_count()

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

bit_length()

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

conjugate()

Returns self, the complex conjugate of any int.

denominator

the denominator of a rational number in lowest terms

classmethod from_bytes(bytes, byteorder='big', *, signed=False)

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use sys.byteorder as the byte order value. Default is to use ‘big’.

signed

Indicates whether two’s complement is used to represent the integer.

imag

the imaginary part of a complex number

is_integer()

Returns True. Exists for duck type compatibility with float.is_integer.

numerator

the numerator of a rational number in lowest terms

real

the real part of a complex number

to_bytes(length=1, byteorder='big', *, signed=False)

Return an array of bytes representing an integer.

length

Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. Default is length 1.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use sys.byteorder as the byte order value. Default is to use ‘big’.

signed

Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property consumption_this_month: float | None

Return this month’s energy consumption in kWh.

abstract property consumption_today: float | None

Return today’s energy consumption in kWh.

abstract property consumption_total: float | None

Return total consumption since last reboot in kWh.

abstract property current: float | None

Return the current in A.

abstract property current_consumption: float | None

Get the current power consumption in Watt.

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

abstractmethod async erase_stats() → dict

Erase all stats.

abstractmethod async get_daily_stats(*, year: int | None = None, month: int | None = None, kwh: bool = True) → dict

Return daily stats for the given year & month.

The return value is a dictionary of {day: energy, …}.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

abstractmethod async get_monthly_stats(*, year: int | None = None, kwh: bool = True) → dict

Return monthly stats for the given year.

abstractmethod async get_status() → EmeterStatus

Return real-time statistics.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstract property status: EmeterStatus

Return current energy readings.

supports(module_feature: ModuleFeature) → bool

Return True if module supports the feature.

abstract property voltage: float | None

Get the current voltage in V.

class kasa.interfaces.Fan(device: Device, module: str)

Interface for a Fan.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

abstract property fan_speed_level: Annotated[int, FeatureAttribute]

Return fan speed level.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_fan_speed_level(level: int) → Annotated[dict, FeatureAttribute]

Set fan speed level.

class kasa.interfaces.Led(device: Device, module: str)

Base interface to represent a LED module.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstract property led: bool

Return current led status.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_led(enable: bool) → dict

Set led.

class kasa.interfaces.Light(device: Device, module: str)

Base class for TP-Link Light.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property brightness: Annotated[int, FeatureAttribute]

Return the current brightness in percentage.

abstract property color_temp: Annotated[int, FeatureAttribute]

Whether the bulb supports color temperature changes.

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstract property hsv: Annotated[HSV, FeatureAttribute]

Return the current HSV state of the bulb.

Returns:

hue, saturation and value (degrees, %, %)

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_brightness(brightness: int, *, transition: int | None = None) → Annotated[dict, FeatureAttribute]

Set the brightness in percentage.

Note, transition is not supported and will be ignored.

Parameters:

• brightness (int) – brightness in percent

• transition (int) – transition in milliseconds.

abstractmethod async set_color_temp(temp: int, *, brightness: int | None = None, transition: int | None = None) → Annotated[dict, FeatureAttribute]

Set the color temperature of the device in kelvin.

Note, transition is not supported and will be ignored.

Parameters:

• temp (int) – The new color temperature, in Kelvin

• transition (int) – transition in milliseconds.

abstractmethod async set_hsv(hue: int, saturation: int, value: int | None = None, *, transition: int | None = None) → Annotated[dict, FeatureAttribute]

Set new HSV.

Note, transition is not supported and will be ignored.

Parameters:

• hue (int) – hue in degrees

• saturation (int) – saturation in percentage [0,100]

• value (int) – value in percentage [0, 100]

• transition (int) – transition in milliseconds.

abstractmethod async set_state(state: LightState) → dict

Set the light state.

abstract property state: LightState

Return the current light state.

class kasa.interfaces.LightEffect(device: Device, module: str)

Interface to represent a light effect module.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

LIGHT_EFFECTS_OFF = 'Off'

LIGHT_EFFECTS_UNNAMED_CUSTOM = 'Custom'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

abstract property effect: str

Return effect name.

abstract property effect_list: list[str]

Return built-in effects list.

Example:

[‘Aurora’, ‘Bubbling Cauldron’, …]

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

abstract property has_custom_effects: bool

Return True if the device supports setting custom effects.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_custom_effect(effect_dict: dict) → dict

Set a custom effect on the device.

Parameters:

effect_dict (str) – The custom effect dict to set

abstractmethod async set_effect(effect: str, *, brightness: int | None = None, transition: int | None = None) → dict

Set an effect on the device.

If brightness or transition is defined, its value will be used instead of the effect-specific default.

See effect_list() for available effects, or use set_custom_effect() for custom effects.

Parameters:

• effect (str) – The effect to set

• brightness (int) – The wanted brightness

• transition (int) – The wanted transition time

class kasa.interfaces.LightPreset(device: Device, module: str)

Base interface for light preset module.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PRESET_NOT_SET = 'Not set'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstract property has_save_preset: bool

Return True if the device supports updating presets.

abstract property preset: str

Return current preset name.

abstract property preset_list: list[str]

Return list of preset names.

Example:

[‘Off’, ‘Preset 1’, ‘Preset 2’, …]

abstract property preset_states_list: Sequence[LightState]

Return list of preset states.

Example:

[‘Off’, ‘Preset 1’, ‘Preset 2’, …]

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async save_preset(preset_name: str, preset_info: LightState) → dict

Update the preset with preset_name with the new preset_info.

abstractmethod async set_preset(preset_name: str) → dict

Set a light preset for the device.

class kasa.interfaces.LightState(light_on: bool | None = None, brightness: int | None = None, hue: int | None = None, saturation: int | None = None, color_temp: int | None = None, transition: int | None = None)

Class for smart light preset info.

brightness: int | None = None

color_temp: int | None = None

hue: int | None = None

light_on: bool | None = None

saturation: int | None = None

transition: int | None = None

class kasa.interfaces.Thermostat(device: Device, module: str)

Base class for TP-Link Thermostat.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstract property mode: ThermostatState

Return thermostat state.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_state(enabled: bool) → dict

Set thermostat state.

abstractmethod async set_target_temperature(target: float) → Annotated[dict, FeatureAttribute]

Set target temperature.

abstractmethod async set_temperature_unit(unit: Literal['celsius', 'fahrenheit']) → dict

Set the device temperature unit.

abstract property state: bool

Return thermostat state.

abstract property target_temperature: Annotated[float, FeatureAttribute]

Return target temperature.

abstract property temperature: Annotated[float, FeatureAttribute]

Return current humidity in percentage.

abstract property temperature_unit: Literal['celsius', 'fahrenheit']

Return current temperature unit.

class kasa.interfaces.ThermostatState(*values)

Thermostat state.

Calibrating = 'progress_calibration'

Heating = 'heating'

Idle = 'idle'

Off = 'off'

Unknown = 'unknown'

class kasa.interfaces.Time(device: Device, module: str)

Base class for tplink time module.

Alarm = 'Alarm'

AutoOff = 'AutoOff'

BatterySensor = 'BatterySensor'

Brightness = 'Brightness'

Camera = 'Camera'

ChildDevice = 'ChildDevice'

ChildLock = 'ChildLock'

ChildProtection = 'ChildProtection'

ChildSetup = 'ChildSetup'

Clean = 'Clean'

CleanRecords = 'CleanRecords'

Cloud = 'Cloud'

Color = 'Color'

ColorTemperature = 'ColorTemperature'

Consumables = 'Consumables'

ContactSensor = 'ContactSensor'

DeviceModule = 'DeviceModule'

Dustbin = 'Dustbin'

Energy = 'Energy'

Fan = 'Fan'

Firmware = 'Firmware'

FrostProtection = 'FrostProtection'

HomeKit = 'HomeKit'

HumiditySensor = 'HumiditySensor'

IotAmbientLight = 'ambient'

IotAntitheft = 'anti_theft'

IotCloud = 'cloud'

IotCountdown = 'countdown'

IotDimmer = 'dimmer'

IotLightEffect = 'LightEffect'

IotMotion = 'motion'

IotSchedule = 'schedule'

IotUsage = 'usage'

Led = 'Led'

LensMask = 'LensMask'

Light = 'Light'

LightEffect = 'LightEffect'

LightPreset = 'LightPreset'

LightTransition = 'LightTransition'

Matter = 'Matter'

Mop = 'Mop'

MotionSensor = 'MotionSensor'

PowerProtection = 'PowerProtection'

ReportMode = 'ReportMode'

SmartLightEffect = 'LightEffect'

Speaker = 'Speaker'

TemperatureControl = 'TemperatureControl'

TemperatureSensor = 'TemperatureSensor'

Thermostat = 'Thermostat'

Time = 'Time'

TriggerLogs = 'TriggerLogs'

WaterleakSensor = 'WaterleakSensor'

abstract property data: dict

Return the module specific raw data from the last update.

property device: Device

Return the device exposing the module.

get_feature(attribute: str | property | Callable) → Feature | None

Get Feature for a module attribute or None if not supported.

has_feature(attribute: str | property | Callable) → bool

Return True if the module attribute feature is supported.

abstractmethod query() → dict

Query to execute during the update cycle.

The inheriting modules implement this to include their wanted queries to the query that gets executed when Device.update() gets called.

abstractmethod async set_time(dt: datetime) → dict

Set the device time.

abstract property time: datetime

Return timezone aware current device time.

abstract property timezone: tzinfo

Return current timezone.

Protocols and transports

Package containing all supported protocols.

class kasa.protocols.BaseProtocol(*, transport: BaseTransport)

Base class for all TP-Link Smart Home communication.

abstractmethod async close() → None

Close the protocol. Abstract method to be overriden.

property config: DeviceConfig

Return the connection parameters the device is using.

abstractmethod async query(request: str | dict, retry_count: int = 3) → dict

Query the device for the protocol. Abstract method to be overriden.

class kasa.protocols.IotProtocol(*, transport: BaseTransport)

Class for the legacy TPLink IOT KASA Protocol.

BACKOFF_SECONDS_AFTER_TIMEOUT = 1

async close() → None

Close the underlying transport.

async query(request: str | dict, retry_count: int = 3) → dict

Query the device retrying for retry_count on failure.

class kasa.protocols.SmartCamProtocol(*, transport: BaseTransport)

Class for SmartCam Protocol.

async close() → None

Close the underlying transport.

class kasa.protocols.SmartProtocol(*, transport: BaseTransport)

Class for the new TPLink SMART protocol.

BACKOFF_SECONDS_AFTER_TIMEOUT = 1

DEFAULT_MULTI_REQUEST_BATCH_SIZE = 5

async close() → None

Close the underlying transport.

get_smart_request(method: str, params: dict | None = None) → str

Get a request message as a string.

async query(request: str | dict, retry_count: int = 3) → dict

Query the device retrying for retry_count on failure.

Package containing all supported transports.

class kasa.transports.AesEncyptionSession(key: bytes, iv: bytes)

Class for an AES encryption session.

static create_from_keypair(handshake_key: str, keypair: KeyPair) → AesEncyptionSession

Create the encryption session.

decrypt(data: str | bytes) → str

Decrypt the message.

encrypt(data: bytes) → bytes

Encrypt the message.

class kasa.transports.AesTransport(*, config: DeviceConfig)

Implementation of the AES encryption protocol.

AES is the name used in device discovery for TP-Link’s TAPO encryption protocol, sometimes used by newer firmware versions on kasa devices.

COMMON_HEADERS = {'Accept': 'application/json', 'Content-Type': 'application/json', 'requestByApp': 'true'}

CONTENT_LENGTH = 'Content-Length'

DEFAULT_PORT: int = 80

KEY_PAIR_CONTENT_LENGTH = 314

SESSION_COOKIE_NAME = 'TP_SESSIONID'

TIMEOUT_COOKIE_NAME = 'TIMEOUT'

async close() → None

Close the http client and reset internal state.

property credentials_hash: str | None

The hashed credentials used by the transport.

property default_port: int

Default port for the transport.

static hash_credentials(login_v2: bool, credentials: Credentials) → tuple[str, str]

Hash the credentials.

async perform_handshake() → None

Perform the handshake.

async perform_login() → None

Login to the device.

async reset() → None

Reset internal handshake and login state.

async send(request: str) → dict[str, Any]

Send the request.

async send_secure_passthrough(request: str) → dict[str, Any]

Send encrypted message as passthrough.

async try_login(login_params: dict[str, Any]) → None

Try to login with supplied login_params.

class kasa.transports.BaseTransport(*, config: DeviceConfig)

Base class for all TP-Link protocol transports.

DEFAULT_TIMEOUT = 5

abstractmethod async close() → None

Close the transport. Abstract method to be overriden.

abstract property credentials_hash: str | None

The hashed credentials used by the transport.

abstract property default_port: int

The default port for the transport.

abstractmethod async reset() → None

Reset internal state.

abstractmethod async send(request: str) → dict

Send a message to the device and return a response.

class kasa.transports.KlapTransport(*, config: DeviceConfig)

Implementation of the KLAP encryption protocol.

KLAP is the name used in device discovery for TP-Link’s new encryption protocol, used by newer firmware versions.

CIPHERS = 'AES256-GCM-SHA384:AES256-SHA256:AES128-GCM-SHA256:AES128-SHA256:AES256-SHA'

DEFAULT_HTTPS_PORT: int = 4433

DEFAULT_PORT: int = 80

SESSION_COOKIE_NAME = 'TP_SESSIONID'

TIMEOUT_COOKIE_NAME = 'TIMEOUT'

async close() → None

Close the http client and reset internal state.

property credentials_hash: str | None

The hashed credentials used by the transport.

property default_port: int

Default port for the transport.

static generate_auth_hash(creds: Credentials) → bytes

Generate an md5 auth hash for the protocol on the supplied credentials.

static generate_owner_hash(creds: Credentials) → bytes

Return the MD5 hash of the username in this object.

static handshake1_seed_auth_hash(local_seed: bytes, remote_seed: bytes, auth_hash: bytes) → bytes

Generate an md5 auth hash for the protocol on the supplied credentials.

static handshake2_seed_auth_hash(local_seed: bytes, remote_seed: bytes, auth_hash: bytes) → bytes

Generate an md5 auth hash for the protocol on the supplied credentials.

async perform_handshake() → None

Perform handshake1 and handshake2.

Sets the encryption_session if successful.

async perform_handshake1() → tuple[bytes, bytes, bytes]

Perform handshake1.

async perform_handshake2(local_seed: bytes, remote_seed: bytes, auth_hash: bytes) → KlapEncryptionSession

Perform handshake2.

async reset() → None

Reset internal handshake state.

async send(request: str) → Generator[Future, None, dict[str, str]]

Send the request.

class kasa.transports.KlapTransportV2(*, config: DeviceConfig)

Implementation of the KLAP encryption protocol with v2 hanshake hashes.

static generate_auth_hash(creds: Credentials) → bytes

Generate an md5 auth hash for the protocol on the supplied credentials.

static handshake1_seed_auth_hash(local_seed: bytes, remote_seed: bytes, auth_hash: bytes) → bytes

Generate an md5 auth hash for the protocol on the supplied credentials.

static handshake2_seed_auth_hash(local_seed: bytes, remote_seed: bytes, auth_hash: bytes) → bytes

Generate an md5 auth hash for the protocol on the supplied credentials.

class kasa.transports.LinkieTransportV2(*, config: DeviceConfig)

Implementation of the Linkie encryption protocol.

Linkie is used as the endpoint for TP-Link’s camera encryption protocol, used by newer firmware versions.

CIPHERS = 'AES256-GCM-SHA384:AES256-SHA256:AES128-GCM-SHA256:AES128-SHA256:AES256-SHA'

DEFAULT_PORT: int = 10443

async close() → None

Close the http client and reset internal state.

property credentials_hash: str | None

The hashed credentials used by the transport.

property default_port: int

Default port for the transport.

async reset() → None

Reset the transport.

NOOP for this transport.

async send(request: str) → dict

Send a message to the device and return a response.

class kasa.transports.SslAesTransport(*, config: DeviceConfig)

Implementation of the AES encryption protocol.

AES is the name used in device discovery for TP-Link’s TAPO encryption protocol, sometimes used by newer firmware versions on kasa devices.

CIPHERS = 'AES256-GCM-SHA384:AES256-SHA256:AES128-GCM-SHA256:AES128-SHA256:AES256-SHA'

COMMON_HEADERS = {'Accept': 'application/json', 'Accept-Encoding': 'gzip, deflate', 'Content-Type': 'application/json; charset=UTF-8', 'User-Agent': 'Tapo CameraClient Android', 'requestByApp': 'true'}

DEFAULT_PORT: int = 443

DEFAULT_TIMEOUT = 10

async close() → None

Close the http client and reset internal state.

property credentials_hash: str | None

The hashed credentials used by the transport.

property default_port: int

Default port for the transport.

static generate_confirm_hash(local_nonce: str, server_nonce: str, pwd_hash: str) → str

Generate an auth hash for the protocol on the supplied credentials.

static generate_digest_password(local_nonce: str, server_nonce: str, pwd_hash: str) → str

Generate an auth hash for the protocol on the supplied credentials.

static generate_encryption_token(token_type: str, local_nonce: str, server_nonce: str, pwd_hash: str) → bytes

Generate encryption token.

static generate_tag(request: str, local_nonce: str, pwd_hash: str, seq: int) → str

Generate the tag header from the request for the header.

async perform_handshake() → None

Perform the handshake.

async perform_handshake1() → tuple[str, str, str] | None

Perform the handshake1.

async perform_handshake2(local_nonce: str, server_nonce: str, pwd_hash: str) → None

Perform the handshake.

async reset() → None

Reset internal handshake state.

async send(request: str) → dict[str, Any]

Send the request.

async send_secure_passthrough(request: str) → dict[str, Any]

Send encrypted message as passthrough.

async send_unencrypted(request: str) → dict[str, Any]

Send encrypted message as passthrough.

async try_perform_less_secure_login(username: str, password: str) → bool

Perform the md5 login.

async try_send_handshake1(username: str, local_nonce: str) → dict

Perform the handshake.

class kasa.transports.SslTransport(*, config: DeviceConfig)

Implementation of the cleartext transport protocol.

This transport uses HTTPS without any further payload encryption.

BACKOFF_SECONDS_AFTER_LOGIN_ERROR = 1

COMMON_HEADERS = {'Content-Type': 'application/json'}

DEFAULT_PORT: int = 4433

async close() → None

Close the http client and reset internal state.

property credentials_hash: str

The hashed credentials used by the transport.

property default_port: int

Default port for the transport.

static hash_credentials(credentials: Credentials) → tuple[str, str]

Hash the credentials.

async perform_login() → None

Login to the device.

async reset() → None

Reset internal login state.

async send(request: str) → dict[str, Any]

Send the request.

async send_request(request: str) → dict[str, Any]

Send request.

async try_login(login_params: dict[str, Any]) → None

Try to login with supplied login_params.

class kasa.transports.XorEncryption

XorEncryption class.

INITIALIZATION_VECTOR = 171

static decrypt(ciphertext: bytes) → str

Decrypt a response of a TP-Link Smart Home Device.

Parameters:

ciphertext – encrypted response data

Returns:

plaintext response

static encrypt(request: str) → bytes

Encrypt a request for a TP-Link Smart Home Device.

Parameters:

request – plaintext request data

Returns:

ciphertext to be send over wire, in bytes

class kasa.transports.XorTransport(*, config: DeviceConfig)

XorTransport class.

BLOCK_SIZE = 4

DEFAULT_PORT: int = 9999

async close() → None

Close the connection.

close_without_wait() → None

Close the connection without waiting for the connection to close.

property credentials_hash: str | None

The hashed credentials used by the transport.

property default_port: int

Default port for the transport.

loop: AbstractEventLoop | None

reader: StreamReader | None

async reset() → None

Reset the transport.

The transport cannot be reset so we must close instead.

async send(request: str) → dict

Send a message to the device and return a response.

writer: StreamWriter | None

Errors and exceptions

class kasa.exceptions.KasaException

Base exception for library errors.

class kasa.exceptions.DeviceError(*args: Any, **kwargs: Any)

Base exception for device errors.

class kasa.exceptions.AuthenticationError(*args: Any, **kwargs: Any)

Base exception for device authentication errors.

class kasa.exceptions.UnsupportedDeviceError(*args: Any, **kwargs: Any)

Exception for trying to connect to unsupported devices.

class kasa.exceptions.TimeoutError

Timeout exception for device errors.