Getting Started

Getting Started

Installation

From PyPI

pip install tplink-cloud-api

From Source

git clone https://github.com/piekstra/tplink-cloud-api.git
cd tplink-cloud-api
pip install .

Quick Start

Basic Usage

import asyncio
from tplinkcloud import TPLinkDeviceManager

async def main():
    # Login and fetch devices
    device_manager = await TPLinkDeviceManager(
        username='your_kasa_email@example.com',
        password='your_password'
    )

    # List all devices
    devices = await device_manager.get_devices()
    for device in devices:
        print(f"{device.model_type.name}: {device.get_alias()}")

    # Control a device
    device = await device_manager.find_device("My Smart Plug")
    if device:
        await device.power_on()   # Turn on
        await device.power_off()  # Turn off
        await device.toggle()     # Toggle current state

asyncio.run(main())

Find Devices by Name

# Exact match
device = await device_manager.find_device("Living Room Light")

# Partial match (case-insensitive)
devices = await device_manager.find_devices("light")
for device in devices:
    print(device.get_alias())

Energy Monitoring (HS110, HS300, KP115, KP125)

import json

device = await device_manager.find_device("My Smart Plug")
power_usage = await device.get_power_usage_realtime()
print(json.dumps(power_usage, indent=2, default=lambda x: x.__dict__))

Schedule Rules

from tplinkcloud import TPLinkDeviceScheduleRuleBuilder

device = await device_manager.find_device("My Smart Plug")

# Get existing rules
schedule = await device.get_schedule_rules()

# Add a new rule (turn on at sunset on weekends)
new_rule = TPLinkDeviceScheduleRuleBuilder() \
    .with_action(turn_on=True) \
    .with_name('Weekend Sunset') \
    .with_enable_status(True) \
    .with_sunset_start() \
    .with_repeat_on_days([0, 0, 0, 0, 0, 1, 1]) \
    .build()
await device.add_schedule_rule(new_rule.to_json())

Using a Pre-existing Token

If you already have a token (e.g., from a previous session):

device_manager = TPLinkDeviceManager()
device_manager.set_auth_token('your_token_here')
devices = await device_manager.get_devices()

Configuration Options

device_manager = TPLinkDeviceManager(
    username='email@example.com',
    password='password',
    prefetch=True,              # Fetch devices on init (default: True)
    cache_devices=True,         # Cache device list (default: True)
    tplink_cloud_api_host=None, # Custom API host (default: TP-Link cloud)
    verbose=False,              # Print debug output (default: False)
    term_id=None                # Terminal UUID (default: auto-generated)
)

Requirements

• Python 3.10+
• A TP-Link / Kasa account (create one in the Kasa app)
• Devices registered to your account via the Kasa app

Troubleshooting

"App version too old" (-23003)

This error occurs when using the V1 API with accounts that have 2FA enabled. Upgrade to v5.0+ which supports the V2 API.

SSL Errors

The V2 API uses TP-Link's private CA. The library bundles the CA chain automatically. If you encounter SSL errors, ensure you're on the latest version.

Token Expired

Tokens expire after some time. v5.0+ supports automatic token refresh. For v4.x, create a new TPLinkDeviceManager instance to re-login.

Device Not Found

Ensure the device is:

1. Registered to your Kasa account
2. Connected to WiFi
3. Using the exact alias from the Kasa app (case-sensitive for find_device)