dirigera-control

核心用法

Dirigera Control 是一款面向 IKEA 智能家居生态的自动化控制技能，通过 Python 的 dirigera 库与 Dirigera Hub 进行本地网络通信。用户可完成设备发现（灯光、插座、控制器、场景）、状态查询、开关控制、亮度/色温调节、场景触发等操作。Token 生成采用物理按钮确认机制，确保授权安全。

显著优点

1. 本地化控制：所有通信均在本地局域网完成，无云端依赖，响应速度快且隐私性强。
2. 物理安全确认：Token 生成必须用户亲自按压 Hub 底部按钮，杜绝远程未授权访问。
3. 完善的输入验证：IP 地址、子网、端口均有严格校验，防止配置错误导致的安全问题。
4. 清晰的设备抽象：通过 .attributes 统一访问设备状态，配合 is_reachable 检查避免操作不可达设备。
5. 丰富的辅助工具：提供 IP 自动发现、Token 生成包装器、电池监控等实用脚本。

潜在缺点与局限性

1. 网络限制：依赖本地局域网，跨网络控制需额外配置 Cloudflare Tunnel 等反向代理。
2. T3 来源风险：作者为个人开发者，虽代码已审计，但长期维护与更新存在不确定性。
3. HTTPS 自签名证书：Token 生成时强制 verify=False，虽为必要配置，但理论上存在中间人攻击风险（需配合物理按钮确认缓解）。
4. 设备生态封闭：仅支持 IKEA Dirigera 生态，无法直接控制其他品牌 Zigbee 设备。
5. 并发性能：建议命令间隔 0.5 秒，高频批量操作可能受限。

适合的目标群体

• IKEA 智能家居用户，希望通过 AI 助手实现语音/自动化控制
• 家庭自动化爱好者，需要批量管理灯光、插座、场景
• 开发者构建本地智能家居中控系统
• 注重隐私、偏好本地控制而非云端方案的用户

使用风险

• Token 泄露风险：保存的 Token 文件需妥善保管，避免未授权访问
• 网络隔离失效：若 Hub 暴露至公网，可能遭受扫描攻击（建议严格限制内网访问）
• 依赖维护：dirigera 库为社区维护，IKEA 官方 API 变更可能导致兼容性问题
• 子进程调用：IP 发现脚本执行 arp -a 和 generate-token，虽为硬编码命令，但在受限环境中可能受限

核心用法

dirigera-control 是一款面向 IKEA Dirigera 智能家居生态的本地化控制工具，基于 Python dirigera 库构建，通过 HTTPS 与本地 Hub 通信实现设备管理。

主要功能模块：

• 设备发现与控制：支持灯光（开关/亮度/色温）、智能插座、场景触发、控制器状态查询
• Hub 连接管理：提供 IP 自动发现脚本、OAuth Token 生成流程（需物理按键确认）
• 状态监控：设备在线状态检查、电池电量监测、批量状态报告

关键使用模式：

# 设备状态访问需通过 .attributes 层级
light.attributes.is_on      # ✓ 正确
light.is_on                 # ✗ 错误 - 触发 AttributeError

# 标准控制流程
if device.is_reachable:
    device.set_light(lamp_on=True, light_level=75)
    device.reload()  # 强制刷新状态

认证流程特殊性： Token 生成必须配合物理交互——用户需按下 Hub 底部 ACTION 按钮完成 OAuth PKCE 授权，这一设计有效阻止了远程未授权访问。

显著优点

1. 纯本地架构：所有通信限于局域网，无外网依赖，数据不出境
2. 官方协议兼容：基于 IKEA 公开 API，非逆向工程，稳定性有保障
3. 防御性编程：内置 is_reachable 检查、capabilities 验证、批量操作延迟（0.5s）等机制
4. 自动化友好：提供 find_dirigera_ip.py 网络扫描、generate_token_wrapper.py 后台等待等脚本，降低部署门槛

潜在缺点与局限性

| 问题 | 说明 |

|------|------|

SSL 验证禁用 | 因 Hub 使用自签名证书，全流量 verify=False，存在中间人攻击理论风险 |

| **Token 明文存储** | 默认保存至 `dirigera_token.txt`，无文件权限强制约束 |

| **T3 来源可信度** | 个人开发者维护（falderebet），无企业/基金会背书 |

| **网络扫描触发 IDS** | IP 发现脚本会扫描 /24 子网 8443 端口，企业环境可能告警 |

| **功能边界** | 仅支持 Dirigera 生态，不兼容 Trådfri 旧网关或其他品牌 |

适合人群

• 已有 IKEA 智能家居用户：拥有 Dirigera Hub 及配套灯具/插座/控制器
• 本地化隐私优先者：拒绝云端方案，要求数据完全本地可控
• 技术爱好者/自托管玩家：具备基础 Python 环境配置能力，能处理 Token 生成等交互流程
• Home Assistant 补充用户：作为官方集成的替代或扩展方案

常规风险

• 供应链风险：依赖 dirigera PyPI 包，需关注上游安全更新
• 网络隔离失效风险：若 Hub 被暴露至公网（如 Cloudflare tunnel 配置不当），verify=False 将构成严重漏洞
• Token 泄露风险：明文 Token 文件若被备份工具同步或权限配置错误，可导致未授权设备控制
• 物理安全依赖：Hub 按钮授权虽提升安全性，但也意味着远程自动化部署需预先生成 Token 并安全存储