Light strips¶

Note

Feel free to open a pull request to improve the documentation!

API documentation ¶

class kasa.SmartLightStrip(host: str, *, config: Optional[DeviceConfig] = None, protocol: Optional[BaseProtocol] = None)[source]¶

Representation of a TP-Link Smart light strip.

Light strips work similarly to bulbs, but use a different service for controlling, and expose some extra information (such as length and active effect). This class extends SmartBulb interface.

Examples:

>>> import asyncio
>>> strip = SmartLightStrip("127.0.0.1")
>>> asyncio.run(strip.update())
>>> print(strip.alias)
KL430 pantry lightstrip

Getting the length of the strip:

>>> strip.length
16

Currently active effect:

>>> strip.effect
{'brightness': 50, 'custom': 0, 'enable': 0, 'id': '', 'name': ''}

Note

The device supports some features that are not currently implemented, feel free to find out how to control them and create a PR!

See SmartBulb for more examples.

LIGHT_SERVICE = 'smartlife.iot.lightStrip'¶

SET_LIGHT_METHOD = 'set_light_state'¶

add_module(name: str, module: Module)¶: Register a module.

property alias: Optional[str]¶: Return device name (alias).

property brightness: int¶: Return the current brightness in percentage.

children: List['SmartDevice']¶

property color_temp: int¶: Return color temperature of the device in kelvin.

property config: DeviceConfig¶: Return the device configuration.

async static connect(*, host: Optional[str] = None, config: Optional[DeviceConfig] = None) → SmartDevice¶

Connect to a single device by the given hostname or device configuration.

This method avoids the UDP based discovery process and will connect directly to the device.

It is generally preferred to avoid discover_single() and use this function instead as it should perform better when the WiFi network is congested or the device is not responding to discovery requests.

Parameters:

host – Hostname of device to query
config – Connection parameters to ensure the correct protocol and connection options are used.

Return type:

SmartDevice

Returns:

Object for querying/controlling found device.

property credentials: Optional[Credentials]¶: The device credentials.

property credentials_hash: Optional[str]¶: The protocol specific hash of the credentials the device is using.

async current_consumption() → float¶: Get the current power consumption in Watt.

property device_id: str¶

Return unique ID for the device.

If not overridden, this is the MAC address of the device. Individual sockets on strips will override this.

property device_type: DeviceType¶: Return the device type.

async disconnect()¶: Disconnect and close any underlying connection resources.

property effect: Dict¶

Return effect state.

Example:

{‘brightness’: 50,: ‘custom’: 0, ‘enable’: 0, ‘id’: ‘’, ‘name’: ‘’}

property effect_list: Optional[List[str]]¶

Return built-in effects list.

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

property emeter_realtime: EmeterStatus¶: Return current energy readings.

property emeter_this_month: Optional[float]¶: Return this month’s energy consumption in kWh.

property emeter_today: Optional[float]¶: Return today’s energy consumption in kWh.

emeter_type = 'smartlife.iot.common.emeter'¶

async erase_emeter_stats() → Dict¶: Erase energy meter statistics.

property features: Set[str]¶: Return a set of features that the device supports.

async get_emeter_daily(year: Optional[int] = None, month: Optional[int] = None, kwh: bool = True) → Dict¶

Retrieve daily statistics for a given month.

Parameters:

year – year for which to retrieve statistics (default: this year)
month – month for which to retrieve statistics (default: this month)
kwh – return usage in kWh (default: True)

Returns:

mapping of day of month to value

async get_emeter_monthly(year: Optional[int] = None, kwh: bool = True) → Dict¶

Retrieve monthly statistics for a given year.

Parameters:

year – year for which to retrieve statistics (default: this year)
kwh – return usage in kWh (default: True)

Returns:

dict: mapping of month to value

async get_emeter_realtime() → EmeterStatus¶: Retrieve current energy readings.

async get_light_details() → Dict[str, int]¶

Return light details.

Example:

{'lamp_beam_angle': 290, 'min_voltage': 220, 'max_voltage': 240,
 'wattage': 5, 'incandescent_equivalent': 40, 'max_lumens': 450,
  'color_rendering_index': 80}

async get_light_state() → Dict[str, Dict]¶: Query the light state.

get_plug_by_index(index: int) → SmartDevice¶: Return child device for the given index.

get_plug_by_name(name: str) → SmartDevice¶: Return child device for the given name.

async get_sys_info() → Dict[str, Any]¶: Retrieve system information.

async get_time() → Optional[datetime]¶: Return current time from the device, if available.

async get_timezone() → Dict¶: Return timezone information.

async get_turn_on_behavior() → TurnOnBehaviors¶: Return the behavior for turning the bulb on.

property has_children: bool¶: Return true if the device has children devices.

property has_effects: bool¶: Return True if the device supports effects.

property has_emeter: bool¶: Return that the bulb has an emeter.

property host: str¶: The device host.

property hsv: HSV¶

Return the current HSV state of the bulb.

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

property hw_info: Dict¶

Return hardware information.

This returns just a selection of sysinfo keys that are related to hardware.

property internal_state: Any¶

Return the internal state of the instance.

The returned object contains the raw results from the last update call. This should only be used for debugging purposes.

property is_bulb: bool¶: Return True if the device is a bulb.

property is_color: bool¶: Whether the bulb supports color changes.

property is_dimmable: bool¶: Whether the bulb supports brightness changes.

property is_dimmer: bool¶: Return True if the device is a dimmer.

property is_light_strip: bool¶: Return True if the device is a led strip.

property is_off: bool¶: Return True if device is off.

property is_on: bool¶: Return whether the device is on.

property is_plug: bool¶: Return True if the device is a plug.

property is_strip: bool¶: Return True if the device is a strip.

property is_strip_socket: bool¶: Return True if the device is a strip socket.

property is_variable_color_temp: bool¶: Whether the bulb supports color temperature changes.

property length: int¶: Return length of the strip.

property light_state: Dict[str, str]¶: Query the light state.

property location: Dict¶: Return geographical location.

property mac: str¶

Return mac address.

Returns:: mac address in hexadecimal with colons, e.g. 01:23:45:67:89:ab

property max_device_response_size: int¶: Returns the maximum response size the device can safely construct.

property model: str¶: Return device model.

modules: Dict[str, Any]¶

property on_since: Optional[datetime]¶: Return pretty-printed on-time, or None if not available.

property port: int¶: The device port.

property presets: List[SmartBulbPreset]¶: Return a list of available bulb setting presets.

protocol: BaseProtocol¶

async reboot(delay: int = 1) → None¶

Reboot the device.

Note that giving a delay of zero causes this to block, as the device reboots immediately without responding to the call.

property rssi: Optional[int]¶: Return WiFi signal strength (rssi).

async save_preset(preset: SmartBulbPreset)¶

Save a setting preset.

You can either construct a preset object manually, or pass an existing one obtained using presets().

async set_alias(alias: str) → None¶

Set the device name (alias).

Overridden to use a different module name.

async set_brightness(brightness: int, *, transition: Optional[int] = None) → Dict¶

Set the brightness in percentage.

Parameters:

brightness (int) – brightness in percent
transition (int) – transition in milliseconds.

async set_color_temp(temp: int, *, brightness=None, transition: Optional[int] = None) → Dict¶

Set the color temperature of the device in kelvin.

Parameters:

temp (int) – The new color temperature, in Kelvin
transition (int) – transition in milliseconds.

async set_custom_effect(effect_dict: Dict) → None[source]¶

Set a custom effect on the device.

Parameters:: effect_dict (str) – The custom effect dict to set

async set_effect(effect: str, *, brightness: Optional[int] = None, transition: Optional[int] = None) → None[source]¶

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

async set_hsv(hue: int, saturation: int, value: Optional[int] = None, *, transition: Optional[int] = None) → Dict¶

Set new HSV.

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.

async set_light_state(state: Dict, *, transition: Optional[int] = None) → Dict¶: Set the light state.

async set_mac(mac)¶

Set the mac address.

Parameters:: mac (str) – mac in hexadecimal with colons, e.g. 01:23:45:67:89:ab

async set_turn_on_behavior(behavior: TurnOnBehaviors)¶

Set the behavior for turning the bulb on.

If you do not want to manually construct the behavior object, you should use get_turn_on_behavior() to get the current settings.

property state_information: Dict[str, Any]¶: Return strip specific state information.

property supported_modules: List[str]¶: Return a set of modules supported by the device.

property sys_info: Dict[str, Any]¶

Return system information.

Do not call this function from within the SmartDevice class itself as @requires_update will be affected for other properties.

property time: datetime¶: Return current time from the device.

property timezone: Dict¶: Return the current timezone.

async turn_off(*, transition: Optional[int] = None, **kwargs) → Dict¶

Turn the bulb off.

Parameters:: transition (int) – transition in milliseconds.

async turn_on(*, transition: Optional[int] = None, **kwargs) → Dict¶

Turn the bulb on.

Parameters:: transition (int) – transition in milliseconds.

async update(update_children: bool = True)¶

Query the device to update the data.

Needed for properties that are decorated with requires_update.

update_from_discover_info(info: Dict[str, Any]) → None¶: Update state from info from the discover call.

property valid_temperature_range: ColorTempRange¶

Return the device-specific white temperature range (in Kelvin).

Returns:: White temperature range in Kelvin (minimum, maximum)

async wifi_join(ssid: str, password: str, keytype: str = '3')¶

Join the given wifi network.

If joining the network fails, the device will return to AP mode after a while.

async wifi_scan() → List[WifiNetwork]¶: Scan for available wifi networks.

Light strips¶

API documentation¶

API documentation ¶