介绍
# IKEA Dirigera Smart Home Control
通过 Dirigera 网关控制灯光、插座、场景和其他宜家智能家居设备。
## 前置条件
```python pip install dirigera ```
## 网关设置
### 查找网关 IP
检查路由器/DHCP 客户端列表中的 "Dirigera" 并记下其 IP 地址。
如果代理位于同一局域网内，请尝试 IP 发现脚本。它可以： 1. 扫描子网以查找可能的候选设备（无需 token）。 2. 如果有 token，验证确切的网关 IP。 3. 作为最后手段，对候选设备尝试 `generate-token`（交互式）。
```bash python scripts/find_dirigera_ip.py # or python scripts/find_dirigera_ip.py --subnet 192.168.1.0/24 # verify with token (if you have it) python scripts/find_dirigera_ip.py --token <dirigera-token> # last resort: try generate-token against candidates python scripts/find_dirigera_ip.py --try-generate-token ```
### 生成 Token
**重要**：Token 生成需要**物理用户操作**。请遵循此工作流程：
#### 步骤 1：启动 Token 生成脚本
在后台运行包装脚本。它将自动等待按钮按下：
```bash python scripts/generate_token_wrapper.py <dirigera-ip-address> & ```
Token 默认将保存到 `dirigera_token.txt`。要指定自定义位置：
```bash python scripts/generate_token_wrapper.py <dirigera-ip-address> --output /path/to/token.txt & ```
#### 步骤 2：**结束您的对话轮次并通知用户**
**关键**：启动脚本后，您必须： 1. **立即结束您的对话轮次** - 不要等待或继续处理 2. 告诉用户：“我已启动 token 生成过程。请现在按下 Dirigera 网关底部的操作按钮。完成后请告诉我。”
#### 步骤 3：等待用户确认
用户将： 1. 物理按下其 Dirigera 网关上的按钮 2. 回复确认他们已按下（例如，“完成”或“已按下”）
脚本将自动检测按钮按下并将 token 保存到文件。
#### 步骤 4：检索已保存的 Token
用户确认后，从文件读取 token：
```python from pathlib import Path token = Path("dirigera_token.txt").read_text().strip() ```
或从自定义位置：
```bash TOKEN=$(cat /path/to/token.txt) ```
然后使用 token 进行连接：
```python import dirigera hub = dirigera.Hub(token=token, ip_address="<dirigera-ip>") ```
#### 替代方案：手动命令
供手动使用（不推荐用于代理）：
```bash generate-token <dirigera-ip-address> ```
这需要交互式终端访问，且不会自动保存输出。
### 故障排除
如果您找不到网关 IP 地址：
1. 检查路由器/DHCP 列表并查找 "Dirigera"。 2. 如果名称缺失，请将网关标签上的 MAC 地址与新的设备条目进行匹配。 3. 确保网关和客户端在同一网络上。 4. 如果您有候选 IP，请对其运行 `generate-token` 直到成功。 5. 如果您已有 token，请运行 `python scripts/find_dirigera_ip.py --token <dirigera-token>`。 6. 如果其他所有方法都失败，请运行 `python scripts/find_dirigera_ip.py --try-generate-token` 并按照提示操作。
## 网关连接
```python import dirigera
hub = dirigera.Hub( token="token", ip_address="ip_address" ) ```
## 关键：属性访问
**设备状态位于 `.attributes` 中，而非顶层。**
```python # CORRECT light.attributes.is_on light.attributes.light_level
# WRONG - raises AttributeError light.is_on light.light_level ```
顶层：`device.id`、`device.is_reachable`、`device.room` 状态：`device.attributes.is_on`、`device.attributes.light_level`
## 快速命令
### 发现 ```python lights = hub.get_lights() outlets = hub.get_outlets() controllers = hub.get_controllers() scenes = hub.get_scenes() ```
### 灯光控制 ```python light = hub.get_light_by_name(lamp_name="bedroom light")
# Check reachability first if light.is_reachable: light.set_light(lamp_on=True) light.set_light_level(light_level=75) light.set_color_temperature(color_temp=2700) # Warm white
# Reload after changes light.reload() ```
### 插座控制 ```python outlet = hub.get_outlet_by_name(outlet_name="living room") outlet.set_on(outlet_on=True) outlet.reload() ```
### 场景触发 ```python scene = hub.get_scene_by_name(scene_name="Sove tid") scene.trigger() ```
### 检查功能 ```python # Verify device supports feature before using if 'colorTemperature' in light.capabilities.can_receive: light.set_color_temperature(color_temp=3000) ```
## 常见模式
请参阅 [references/patterns.md](references/patterns.md) 了解基于房间的控制、批量操作、状态报告和电池监控。
## 辅助脚本
使用 `scripts/helpers.py` 进行常见操作：按房间获取灯光、检查电池电量、查找无法访问的设备。
## 完整参考
请参阅 [references/api.md](references/api.md) 了解： - 完整属性参考 - 所有控制方法 - 设备功能 - 色温/色相值 - 故障排除
## 最佳实践
1. 控制前始终检查 `device.is_reachable` 2. 控制命令后调用 `device.reload()` 3. 使用 `.attributes` 进行所有状态访问 4. 在快速连续的命令之间添加 0.5 秒的延迟 5. 使用功能前检查设备能力