ingmarstein/velux-nibe

Velux-Nibe

镜像概述和主要用途

NIBE Uplink允许将热泵连接到智能家居系统以实现更智能的供暖控制，但兼容系统列表有限。本项目通过集成VELUX ACTIVE传感器（可能用于控制窗户和遮阳帘），扩展了NIBE Uplink的兼容设备，使其可用作智能恒温器，优化室内气候控制。

核心功能和特性

• 将VELUX ACTIVE传感器数据集成到NIBE Uplink系统
• 通过NIBE Uplink API与热泵通信，提交当前温度和目标温度
• 支持配置轮询间隔和目标温度参数
• 生成并持久化存储OAuth2访问令牌，实现持续认证

使用场景和适用范围

适用于拥有NIBE热泵且已部署VELUX ACTIVE传感器的用户，希望通过现有智能家居设备实现对热泵的智能调节，优化室内温度控制和能源使用效率。

使用方法和配置说明

1. 获取NIBE API凭证

工具通过NIBE Uplink API与热泵通信，需先创建API凭证：

• 使用现有NIBE账户登录[***]
• 回调URL可使用https://www.marshflattsfarm.org.uk/nibeuplink/oauth2callback/index.php，或自行托管类似脚本
• 应用名称可任意设置（将显示为智能恒温器来源）
• 记录NIBE系统ID（登录NIBE Uplink后，URL中https://www.nibeuplink.com/System/${ID}/Status/Overview的${ID}部分）

2. 首次运行（生成访问令牌）

使用VELUX ACTIVE凭证和NIBE API凭证首次运行工具，生成访问令牌（仅需执行一次）：

bash
go get github.com/IngmarStein/velux-nibe
./velux-nibe -velux-user xxx -velux-password xxx -nibe-system xxx -nibe-client-id xxx -nibe-client-secret xxx -nibe-callback xxx

按提示在浏览器中打开URL并完成验证码验证（确保state参数为state-token），输入结果代码。成功后，OAuth2访问令牌将保存至nibe-token.json。

3. 运行velux-nibe

原生运行

bash
go get github.com/IngmarStein/velux-nibe
VELUX_USERNAME=xxx VELUX_PASSWORD=xxx NIBE_CLIENT_ID=xxx NIBE_CLIENT_SECRET=xxx NIBE_CALLBACK_URL=xxx NIBE_SYSTEM_ID=xxx NIBE_TOKEN=nibe-token.json velux-nibe -targetTemp 210 -interval 60

Docker容器运行

bash
docker run -v nibe-token.json:/nibe-token.json \
  --env VELUX_USERNAME=xxx \
  --env VELUX_PASSWORD=xxx \
  --env NIBE_CLIENT_ID=xxx \
  --env NIBE_CLIENT_SECRET=xxx \
  --env NIBE_CALLBACK_URL=xxx \
  --env NIBE_SYSTEM_ID=xxx \
  ingmarstein/velux-nibe -targetTemp 210 -interval 60

也可使用项目提供的docker-compose.yml文件通过Docker Compose部署。

4. 启用智能家居模式

工具运行后，将按设定间隔轮询VELUX传感器并向NIBE Uplink提交温度数据。可在NIBE Uplink门户的"我的系统 > 系统 > 智能家居 > 恒温器"中验证数据。确认正常后，在"我的系统 > 系统 > 管理 > 热泵 > 附加功能 > 智能家居"中启用"智能家居"模式，使热泵使用传感器数据优化运行。

环境变量说明

• VELUX_USERNAME: VELUX ACTIVE账户用户名
• VELUX_PASSWORD: VELUX ACTIVE账户密码
• NIBE_CLIENT_ID: NIBE API应用的客户端ID
• NIBE_CLIENT_SECRET: NIBE API应用的客户端密钥
• NIBE_CALLBACK_URL: 创建NIBE API应用时设置的回调URL
• NIBE_SYSTEM_ID: NIBE系统ID
• NIBE_TOKEN: 访问令牌文件路径（默认nibe-token.json）

命令行参数

• -targetTemp: 目标温度（单位：0.1°C，如210表示21.0°C）
• -interval: 轮询间隔（单位：秒）