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