Smart strips¶
Note
Feel free to open a pull request to improve the documentation!
Command-line usage¶
To command a single socket of a strip, you will need to specify it either by using --index
or by using --name
.
If not specified, the commands will act on the parent device: turning the strip off will turn off all sockets.
Example: Turn on the first socket (the indexing starts from zero):
$ kasa --type strip --host <host> on --index 0
Example: Turn off the socket by name:
$ kasa --type strip --host <host> off --name "Maybe Kitchen"
API documentation¶
- class kasa.SmartStrip(host: str, *, config: Optional[DeviceConfig] = None, protocol: Optional[BaseProtocol] = None)[source]¶
Representation of a TP-Link Smart Power Strip.
A strip consists of the parent device and its children. All methods of the parent act on all children, while the child devices share the common API with the
SmartPlug
class.To initialize, you have to await
update()
at least once. This will allow accessing the properties using the exposed properties.All changes to the device are done using awaitable methods, which will not change the cached values, but you must await
update()
separately.Errors reported by the device are raised as
SmartDeviceException
s, and should be handled by the user of the library.- Examples:
>>> import asyncio >>> strip = SmartStrip("127.0.0.1") >>> asyncio.run(strip.update()) >>> strip.alias TP-LINK_Power Strip_CF69
All methods act on the whole strip:
>>> for plug in strip.children: >>> print(f"{plug.alias}: {plug.is_on}") Plug 1: True Plug 2: False Plug 3: False >>> strip.is_on True >>> asyncio.run(strip.turn_off())
Accessing individual plugs can be done using the children property:
>>> len(strip.children) 3 >>> for plug in strip.children: >>> print(f"{plug.alias}: {plug.is_on}") Plug 1: False Plug 2: False Plug 3: False >>> asyncio.run(strip.children[1].turn_on()) >>> asyncio.run(strip.update()) >>> strip.is_on True
For more examples, see the
SmartDevice
class.- add_module(name: str, module: Module)¶
Register a module.
- property alias: Optional[str]¶
Return device name (alias).
- children: List['SmartDevice']¶
- 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:
- 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.
- 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 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 this month’s energy consumption in kWh.
- emeter_type = 'emeter'¶
- 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 [source]¶
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 [source]¶
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)
- 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.
- property has_children: bool¶
Return true if the device has children devices.
- property has_emeter: bool¶
Return True if device has an energy meter.
- property host: str¶
The device host.
- 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¶
Return True if the device supports color changes.
- property is_dimmable: bool¶
Return True if the device is dimmable.
- 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 if any of the outlets are 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¶
Return True if the device supports color temperature.
- property led: bool¶
Return the state of the led.
- 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 the maximum on-time of all outlets.
- property port: int¶
The device port.
- 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 set_alias(alias: str) None ¶
Set the device name (alias).
- async set_mac(mac)¶
Set the mac address.
- Parameters:
mac (str) – mac in hexadecimal with colons, e.g. 01:23:45:67:89:ab
- property state_information: Dict[str, Any]¶
Return strip-specific state information.
- Returns:
Strip information dict, keys in user-presentable form.
- 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 update(update_children: bool = True)[source]¶
Update some of the attributes.
Needed for methods that are decorated with requires_update.
- update_from_discover_info(info: Dict[str, Any]) None ¶
Update state from info from the discover call.
- 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.