python-kasa

python-kasa 是一个用于控制TPLink智能家居设备（插头、墙壁开关、电源插座和灯泡）的Python库。

这是一个自愿的、由社区驱动的努力，与TPLink无关、不受赞助或认可。

欢迎以任何形式做出贡献（添加缺失的功能、报告问题、修复或分类现有问题、改进文档或捐赠设备）！

开始使用

您可以使用pip安装最新版本

pip install python-kasa

或者，您可以克隆此存储库并使用uv安装开发版本

git clone https://github.com/python-kasa/python-kasa.git
cd python-kasa/
uv sync --all-extras
uv run kasa

如果您尚未配置设备，可以使用cli工具进行配置。

设备发现

运行kasa discover会向默认广播地址（255.255.255.255）发送发现数据包以发现支持的设备。如果您的设备需要认证才能控制，您需要使用--username和--password选项或定义KASA_USERNAME和KASA_PASSWORD环境变量来传递凭证。

[!NOTE] 如果您的系统有多个网络接口，您可以使用--target选项指定广播地址。

discover命令将自动在所有发现的设备上执行state命令

$ kasa discover
Discovering devices on 255.255.255.255 for 3 seconds

== Bulb McBulby - L530 ==
Host: 192.0.2.123
Port: 80
Device state: False
Time:         2024-06-22 15:42:15+02:00 (tz: {'timezone': 'CEST'}
Hardware:     3.0
Software:     1.1.6 Build 240130 Rel.173828
MAC (rssi):   5C:E9:31:aa:bb:cc (-50)
== Primary features ==
State (state): False
Brightness (brightness): 11 (range: 0-100)
Color temperature (color_temperature): 0 (range: 2500-6500)
Light effect (light_effect): *Off* Party Relax

== Information ==
Signal Level (signal_level): 2
Overheated (overheated): False
Cloud connection (cloud_connection): False
Update available (update_available): None
Device time (device_time): 2024-06-22 15:42:15+02:00

== Configuration ==
HSV (hsv): HSV(hue=35, saturation=70, value=11)
Auto update enabled (auto_update_enabled): False
Light preset (light_preset): *Not set* Light preset 1 Light preset 2 Light preset 3 Light preset 4 Light preset 5 Light preset 6 Light preset 7
Smooth transition on (smooth_transition_on): 2 (range: 0-60)
Smooth transition off (smooth_transition_off): 20 (range: 0-60)

== Debug ==
Device ID (device_id): soneuniqueidentifier
RSSI (rssi): -50 dBm
SSID (ssid): HomeNet
Current firmware version (current_firmware_version): 1.1.6 Build 240130 Rel.173828
Available firmware version (available_firmware_version): None

命令行使用

所有设备都支持多种常用命令（如on、off和state）。控制设备的语法是kasa --host <host> <command>

$ kasa --host 192.0.2.123 on

使用kasa --help（或参考文档）以获取所有可用命令和选项的列表。一些可用选项的示例包括JSON输出（--json）、更详细的输出（--verbose）和定义超时（--timeout和--discovery-timeout）。请参阅文档以获取更多详细信息。

[!NOTE] 每个单独的命令也可能有额外的选项，这些选项在带有--help选项的调用时显示。

功能接口

所有设备也可以通过基于功能的一般接口进行控制。可用的功能因设备而异，可以使用kasa feature命令访问

$ kasa --host 192.0.2.123 feature
== Primary features ==
State (state): False
Brightness (brightness): 11 (range: 0-100)
Color temperature (color_temperature): 0 (range: 2500-6500)
Light effect (light_effect): *Off* Party Relax

== Information ==
Signal Level (signal_level): 2
Overheated (overheated): False
Cloud connection (cloud_connection): False
Update available (update_available): None
Device time (device_time): 2024-06-22 15:39:44+02:00

== Configuration ==
HSV (hsv): HSV(hue=35, saturation=70, value=11)
Auto update enabled (auto_update_enabled): False
Light preset (light_preset): *Not set* Light preset 1 Light preset 2 Light preset 3 Light preset 4 Light preset 5 Light preset 6 Light preset 7
Smooth transition on (smooth_transition_on): 2 (range: 0-60)
Smooth transition off (smooth_transition_off): 20 (range: 0-60)

== Debug ==
Device ID (device_id): soneuniqueidentifier
RSSI (rssi): -50 dBm
SSID (ssid): HomeNet
Current firmware version (current_firmware_version): 1.1.6 Build 240130 Rel.173828
Available firmware version (available_firmware_version): None

一些功能提供可更改的配置

kasa --host 192.0.2.123 feature color_temperature 2500
Changing color_temperature from 0 to 2500
New state: 2500

[!NOTE] 当控制与集线器连接的设备时，您需要作为选项传递连接设备的设备ID：kasa --host 192.0.2.200 feature --child someuniqueidentifier target_temperature 21

库使用

import asyncio
from kasa import Discover

async def main():
    dev = await Discover.discover_single("192.0.2.123", username="un@example.com", password="pw")
    await dev.turn_on()
    await dev.update()

if __name__ == "__main__":
    asyncio.run(main())

如果您想在您的项目中使用此库，文档中的教程是一个不错的起点。

您可以在API文档如何指南中找到几个代码示例。

有关库设计和设备工作方式的信息可以在主题部分中找到。

贡献

非常欢迎贡献！最简单的方式是为自动化测试套件创建固定文件，如果您的设备硬件和固件版本尚未列为受支持，请参考我们的贡献指南。

支持的设备

以下设备已测试并确认可以正常工作。如果您的设备未列出但可以正常工作，请考虑贡献一个固定文件。

支持的Kasa设备

• 插座：EP10、EP25^*、HS100^**、HS103、HS105、HS110、KP100、KP105、KP115、KP125、KP125M^*、KP401
• 电源插座：EP40、HS107、HS300、KP200、KP303、KP400
• 墙壁开关：ES20M、HS200、HS210、HS220^**、KP405、KS200M、KS205^*、KS220M、KS225^*、KS230、KS240^*
• 灯泡：KL110、KL120、KL125、KL130、KL135、KL50、KL60、LB110
• 灯带：KL400L5、KL420L5、KL430
• 集线器：KH100^*
• 集线器连接设备^***：KE100^*

支持的Tapo^*设备

• 插座：P100、P110、P115、P125M、P135、TP15
• 电源插座：P300、TP25
• 墙壁开关：S500D, S505, S505D
• 灯泡：L510B, L510E, L530E
• 灯条：L900-10, L900-5, L920-5, L930-5
• 集线器：H100
• 与集线器连接的设备^***：T100, T110, T300, T310, T315

^*   模型需要认证
^**  新版本需要认证
^*** 设备可能可以在 TAPO/KASA 品牌的集线器上工作

有关测试的硬件和软件版本的详细信息，请参阅我们的文档中的支持设备。

资源

开发者资源

• softScheck 的 github 包含大量信息和 wireshark 解析器
• TP-Link 智能家居设备模拟器
• 非官方 API 文档
• 另一份非官方 API 文档
• pyHS100 提供同步接口，是此库的前任维护者。

库用户

• Home Assistant
• 使用 python-kasa 通过 MQTT 访问 TP-Link 设备

其他相关项目

• PyTapo - 用于与 Tapo 相机通信的 Python 库
• Tapo P100 (Tapo 插座，Tapo 灯泡)
  • Home Assistant 集成
• plugp100，另一个 tapo 库
  • Home Assistant 集成
• rust 和 python 对 tapo 设备的实现