名称： dirigera-control
描述： 控制宜家 Dirigera 智能家居设备（灯光、插座、场景、控制器）。当用户要求控制智能家居设备、检查设备状态、开关灯、调节亮度/颜色、控制插座、触发场景、检查电池电量或进行宜家智能家居自动化时使用。当用户需要帮助查找 Dirigera 集线器 IP 地址或生成 API 令牌时也可使用。可通过 VPS 上的 Cloudflare 隧道访问。

宜家 Dirigera 智能家居控制

通过 Dirigera 集线器控制灯光、插座、场景和其他宜家智能家居设备。

前提条件

pip install dirigera

集线器设置

查找集线器 IP

检查路由器/DHCP 客户端列表中的 "Dirigera" 设备，并记下其 IP 地址。

如果代理在同一局域网内，可以尝试 IP 发现脚本。该脚本可以：
1. 扫描子网以寻找可能的候选 IP（无需令牌）。
2. 如果已有令牌，则验证确切的集线器 IP。
3. 作为最后手段，对候选 IP 尝试 generate-token 命令（交互式）。

python scripts/find_dirigera_ip.py
# 或
python scripts/find_dirigera_ip.py --subnet 192.168.1.0/24
# 使用令牌验证（如果你有令牌）
python scripts/find_dirigera_ip.py --token <dirigera-token>
# 最后手段：对候选 IP 尝试生成令牌
python scripts/find_dirigera_ip.py --try-generate-token

生成令牌

重要：生成令牌需要用户进行物理操作。请遵循以下工作流程：

步骤 1：启动令牌生成脚本

在后台运行包装脚本。它将自动等待按钮按下：

python scripts/generate_token_wrapper.py <dirigera-ip-address> &

默认情况下，令牌将保存到 dirigera_token.txt。要指定自定义位置：

python scripts/generate_token_wrapper.py <dirigera-ip-address> --output /path/to/token.txt &

步骤 2：结束你的回合并通知用户

关键：启动脚本后，你必须：
1. 立即结束你的回合 - 不要等待或继续处理
2. 告诉用户："我已启动令牌生成过程。请现在按下您 Dirigera 集线器底部的操作按钮。按下后请告诉我。"

步骤 3：等待用户确认

用户将：
1. 物理按下其 Dirigera 集线器上的按钮
2. 回复你确认已按下（例如，"完成" 或 "已按下"）

脚本将自动检测按钮按下并将令牌保存到文件。

步骤 4：检索保存的令牌

用户确认后，从文件中读取令牌：

from pathlib import Path
token = Path("dirigera_token.txt").read_text().strip()

或从自定义位置读取：

TOKEN=$(cat /path/to/token.txt)

然后使用令牌进行连接：

import dirigera
hub = dirigera.Hub(token=token, ip_address="<dirigera-ip>")

替代方案：手动命令

用于手动使用（不推荐用于代理）：

generate-token <dirigera-ip-address>

这需要交互式终端访问，且不会自动保存输出。

故障排除

如果找不到集线器 IP 地址：

1. 检查路由器/DHCP 列表，查找 "Dirigera"。
2. 如果名称缺失，请将集线器上的 MAC 地址标签与新设备条目进行匹配。
3. 确保集线器和客户端在同一网络。
4. 如果你有候选 IP，对它们运行 generate-token 直到一个成功。
5. 如果你已有令牌，运行 python scripts/find_dirigera_ip.py --token <dirigera-token>。
6. 如果其他方法都失败，运行 python scripts/find_dirigera_ip.py --try-generate-token 并按照提示操作。

集线器连接

import dirigera

hub = dirigera.Hub(
    token="token",
    ip_address="ip_address"
)

关键：属性访问

设备状态在 .attributes 中，不在顶层。

# 正确
light.attributes.is_on
light.attributes.light_level

# 错误 - 会引发 AttributeError
light.is_on
light.light_level

顶层属性：device.id, device.is_reachable, device.room
状态属性：device.attributes.is_on, device.attributes.light_level

快速命令

设备发现

lights = hub.get_lights()
outlets = hub.get_outlets()
controllers = hub.get_controllers()
scenes = hub.get_scenes()

灯光控制

light = hub.get_light_by_name(lamp_name="bedroom light")

# 首先检查可达性
if light.is_reachable:
    light.set_light(lamp_on=True)
    light.set_light_level(light_level=75)
    light.set_color_temperature(color_temp=2700)  # 暖白光

# 更改后重新加载状态
light.reload()

插座控制

outlet = hub.get_outlet_by_name(outlet_name="living room")
outlet.set_on(outlet_on=True)
outlet.reload()

场景触发

scene = hub.get_scene_by_name(scene_name="Sove tid")
scene.trigger()

检查设备能力

# 在使用功能前验证设备是否支持
if 'colorTemperature' in light.capabilities.can_receive:
    light.set_color_temperature(color_temp=3000)

常用模式

查看 references/patterns.md 了解基于房间的控制、批量操作、状态报告和电池监控。

辅助脚本

使用 scripts/helpers.py 进行常见操作：按房间获取灯光、检查电池电量、查找不可达设备。

完整参考

查看 references/api.md 获取：
- 完整的属性参考
- 所有控制方法
- 设备能力
- 色温/色调值
- 故障排除

最佳实践

1. 控制前始终检查 device.is_reachable
2. 控制命令后调用 device.reload()
3. 所有状态访问都使用 .attributes
4. 在快速命令之间添加 0.5 秒延迟
5. 使用功能前检查设备能力