control-ikea-lightbulb

控制 IKEA/TP-Link Kasa 智能灯泡（设置开/关、亮度和颜色）。当您想要通过 LAN 上的 IP 以编程方式控制本地智能灯泡时使用。

# control-ikea-lightbulb

This skill provides a lightweight Python script to control a local smart bulb (supports TP-Link Kasa-compatible bulbs via python-kasa). It is intended for local LAN devices that do not require cloud credentials; control is by IP address.

When to use this skill
- When you want to turn a bulb on or off
- When you want to set brightness (0-100)
- When you want to set color (HSV)
- When you have the bulb's local IP and it's accessible from this machine

Contents
- scripts/control_kasa_light.py — main runnable script (Python 3.9+)
- scripts/light_show.py — small light-show controller for sequences (uses python-kasa). Changes include:
  - Default white uses a high color temperature (9000K) to make white appear "whiter"; pass --white-temp to override.
  - Bug fixes: the off-flash between blue→red now ignores transitions to white (saturation==0) to avoid white<->blue ping-pong, and white-temp is only applied to white steps (fixes red being skipped during off-flash). White steps also set brightness even without --double-write.
- scripts/run_test_light_show.sh — helper to run light_show via uv

Notes
- This repo is set up for uv (no manual environment activation). Dependencies live in `pyproject.toml` and wrappers prefer `uv run`.
  Example:
  uv run --project ./skills/control-ikea-lightbulb python ./skills/control-ikea-lightbulb/scripts/control_kasa_light.py --ip 192.168.4.69 --on --hsv 0 100 80 --brightness 80
- Install uv:
  - `brew install uv` (macOS)
  - `pipx install uv` (cross-platform)
- The provided wrapper script requires uv:
  ./skills/control-ikea-lightbulb/scripts/run_control_kasa.sh --ip 192.168.4.69 --on --hsv 0 100 80 --brightness 80
- The test helper also prefers uv:
  ./skills/control-ikea-lightbulb/scripts/run_test_light_show.sh --ip 192.168.4.69 --duration 6 --transition 1 --off-flash --verbose
- If your device is actually an IKEA TRADFRI device (not Kasa), this script is a starting point; tell me and I will add TRADFRI support.
- No cloud credentials are required; control happens over LAN to the device's IP.

Quick start
1. Install uv (macOS):
   `brew install uv`
2. Turn the bulb on (replace the IP):
   `./skills/control-ikea-lightbulb/scripts/run_control_kasa.sh --ip 192.168.4.69 --on`
3. Set color and brightness:
   `./skills/control-ikea-lightbulb/scripts/run_control_kasa.sh --ip 192.168.4.69 --hsv 0 100 80 --brightness 80`

Git note
- No local environment artifacts are tracked; use uv.

Note about Python requirements and recent change
- The skill previously declared python-kasa>=0.13.0 which caused dependency resolution failures on this machine. To make the skill runnable locally the project's pyproject.toml was adjusted to:
  - requires-python = ">=3.11, <4.0"
  - python-kasa>=0.10.2
- This allows the resolver to pick a compatible python-kasa on machines with Python 3.11+. If you prefer a different constraint (or want me to revert this change), tell me and I will update the pyproject.toml and README accordingly.

---

## 中文说明

# control-ikea-lightbulb

此技能提供一个轻量级的 Python 脚本来控制本地智能灯泡（通过 python-kasa 支持兼容 TP-Link Kasa 的灯泡）。它适用于不需要云凭据的本地 LAN 设备；通过 IP 地址进行控制。

何时使用此技能
- 当你想要打开或关闭灯泡时
- 当你想要设置亮度（0-100）时
- 当你想要设置颜色（HSV）时
- 当你有灯泡的本地 IP 且可从本机访问时

内容
- scripts/control_kasa_light.py — 主要的可运行脚本（Python 3.9+）
- scripts/light_show.py — 用于序列的小型灯光秀控制器（使用 python-kasa）。更改包括：
  - 默认白色使用高色温（9000K）使白色看起来"更白"；传入 --white-temp 以覆盖。
  - Bug 修复：blue→red 之间的关闭闪烁现在会忽略到白色的过渡（saturation==0），以避免白色<->蓝色的来回切换，并且 white-temp 仅应用于白色步骤（修复了在关闭闪烁期间红色被跳过的问题）。即使没有 --double-write，白色步骤也会设置亮度。
- scripts/run_test_light_show.sh — 通过 uv 运行 light_show 的辅助脚本

说明
- 此仓库为 uv 设置（无需手动激活环境）。依赖位于 `pyproject.toml` 中，封装脚本优先使用 `uv run`。
  示例：
  uv run --project ./skills/control-ikea-lightbulb python ./skills/control-ikea-lightbulb/scripts/control_kasa_light.py --ip 192.168.4.69 --on --hsv 0 100 80 --brightness 80
- 安装 uv：
  - `brew install uv`（macOS）
  - `pipx install uv`（跨平台）
- 提供的封装脚本需要 uv：
  ./skills/control-ikea-lightbulb/scripts/run_control_kasa.sh --ip 192.168.4.69 --on --hsv 0 100 80 --brightness 80
- 测试辅助脚本也优先使用 uv：
  ./skills/control-ikea-lightbulb/scripts/run_test_light_show.sh --ip 192.168.4.69 --duration 6 --transition 1 --off-flash --verbose
- 如果你的设备实际上是 IKEA TRADFRI 设备（而非 Kasa），此脚本是一个起点；告诉我，我会添加 TRADFRI 支持。
- 不需要云凭据；控制通过 LAN 发送到设备的 IP。

快速开始
1. 安装 uv（macOS）：
   `brew install uv`
2. 打开灯泡（替换 IP）：
   `./skills/control-ikea-lightbulb/scripts/run_control_kasa.sh --ip 192.168.4.69 --on`
3. 设置颜色和亮度：
   `./skills/control-ikea-lightbulb/scripts/run_control_kasa.sh --ip 192.168.4.69 --hsv 0 100 80 --brightness 80`

Git 说明
- 不跟踪本地环境产物；使用 uv。

关于 Python 要求和近期更改的说明
- 该技能之前声明了 python-kasa>=0.13.0，这在本机上导致了依赖解析失败。为使技能能在本地运行，项目的 pyproject.toml 被调整为：
  - requires-python = ">=3.11, <4.0"
  - python-kasa>=0.10.2
- 这使得解析器能在装有 Python 3.11+ 的机器上选择兼容的 python-kasa。如果你偏好不同的约束（或希望我撤销此更改），告诉我，我会相应更新 pyproject.toml 和 README。