Dimmers

Note

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

API documentation

class kasa.SmartDimmer(host: str, *, port: Optional[int] = None, credentials: Optional[kasa.credentials.Credentials] = None, timeout: Optional[int] = None)

Representation of a TP-Link Smart Dimmer.

Dimmers work similarly to plugs, but provide also support for adjusting the brightness. This class extends SmartPlug interface.

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 SmartDeviceExceptions, and should be handled by the user of the library.

Examples: >>> import asyncio >>> dimmer = SmartDimmer(“192.168.1.105”) >>> asyncio.run(dimmer.turn_on()) >>> dimmer.brightness 25

>>> asyncio.run(dimmer.set_brightness(50))
>>> asyncio.run(dimmer.update())
>>> dimmer.brightness
50

Refer to SmartPlug for the full API.

DIMMER_SERVICE = 'smartlife.iot.dimmer'

add_module(name: str, module: kasa.modules.module.Module)

Register a module.

property alias: str

Return device name (alias).

property brightness: int

Return current brightness on dimmers.

Will return a range between 0 - 100.

children: List['SmartDevice']

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: kasa.smartdevice.DeviceType

Return the device type.

property emeter_realtime: kasa.emeterstatus.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 = '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_behaviors()

Return button behavior settings.

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() → kasa.emeterstatus.EmeterStatus

Retrieve current energy readings.

get_plug_by_index(index: int) → kasa.smartdevice.SmartDevice

Return child device for the given index.

get_plug_by_name(name: str) → kasa.smartdevice.SmartDevice

Return child device for the given name.

async get_sys_info() → Dict[str, Any]

Retrieve system information.

async get_time() → Optional[datetime.datetime]

Return current time from the device, if available.

async get_timezone() → Dict

Return timezone information.

property has_emeter: bool

Return True if device has an energy meter.

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

Whether the switch 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 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

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.datetime]

Return pretty-printed on-time, or None if not available.

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_brightness(brightness: int, *, transition: Optional[int] = None)

Set the new dimmer brightness level in percentage.

Parameters

transition (int) – transition duration in milliseconds. Using a transition will cause the dimmer to turn on.

async set_button_action(action_type: kasa.smartdimmer.ActionType, action: kasa.smartdimmer.ButtonAction, index: Optional[int] = None)

Set action to perform on button click/hold.

Parameters

• ActionType (action_type) – whether to control double click or hold action.

• ButtonAction (action) – what should the button do (nothing, instant, gentle, change preset)

• int (index) – in case of preset change, the preset to select

async set_dimmer_transition(brightness: int, transition: int)

Turn the bulb on to brightness percentage over transition milliseconds.

A brightness value of 0 will turn off the dimmer.

async set_fade_time(fade_type: kasa.smartdimmer.FadeType, time: int)

Set time for fade in / fade out.

async set_led(state: bool)

Set the state of the led (night mode).

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

property time: datetime.datetime

Return current time from the device.

property timezone: Dict

Return the current timezone.

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

Turn the bulb off.

Parameters

transition (int) – transition duration in milliseconds.

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

Turn the bulb on.

Parameters

transition (int) – transition duration 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.

async wifi_join(ssid, password, keytype=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[kasa.smartdevice.WifiNetwork]

Scan for available wifi networks.