cdzombak/ecobee_influx_connector

Ecobee -> InfluxDB/MQTT 连接器

将Ecobee的运行时数据、传感器数据和天气数据发送到InfluxDB和/或MQTT。

概述和主要用途

该连接器旨在将Ecobee恒温器的运行时数据、传感器读数和天气信息集成到InfluxDB时序数据库和/或MQTT消息代理中，便于数据存储、分析和智能家居系统集成。

核心功能和特性

• 支持将Ecobee数据同步至InfluxDB
• 支持将Ecobee数据发布至MQTT broker
• 可配置的数据类别（运行时、传感器、天气）
• 基于JSON的灵活配置
• 支持Docker部署和系统服务运行

使用场景和适用范围

适用于需要收集、存储和分析Ecobee恒温器数据的用户，特别是：

• 家庭自动化爱好者
• 能源监控系统构建者
• 需要长期存储环境数据的用户
• 基于MQTT的智能家居系统集成者

快速开始

1. 在Ecobee账户上注册并启用开发者仪表板：[***]
2. 访问[***]"开发者"，创建一个应用
3. 创建类似于config.example.json的config.json文件，该文件应位于定义的work_dir目录中
4. 构建项目（参见构建部分）
5. 在交互式终端运行ecobee_influx_connector -list-thermostats -config $WORK_DIR/config.json，将生成一个PIN码。确保将$WORK_DIR替换为您的配置路径
6. 访问[***]"我的应用"，点击"添加应用"
7. 粘贴PIN码并授权应用
8. 返回ecobee_influx_connector命令行界面，按Enter键

之后将显示您Ecobee账户中的恒温器列表及其ID。

配置

配置通过JSON文件指定。基于仓库中的config.example.json模板创建文件并自定义：

• api_key：在步骤1和2中创建
• thermostat_id：可从步骤5获取，通常是设备序列号
• work_dir：存储客户端凭据、config.json和（尚未实现的）上次写入水印的目录
• 使用influx_*配置字段设置发送数据到InfluxDB：如果使用令牌进行桶认证，保持用户和密码配置字段为空
• 使用mqtt配置部分设置发送数据到MQTT broker：
  • enabled：设为true启用MQTT发布
  • server：MQTT broker主机名或IP地址
  • port：MQTT broker端口（通常1883为未加密，8883为TLS）
  • username和password：MQTT broker的可选凭据
  • topic_root：所有数据发布的根主题（例如"ecobee"）
  • timeout：MQTT发布操作的超时时间（秒，可选，默认：3）
• 使用write_*配置字段指定要使用的设备组件

注意：必须配置至少一种输出方式（InfluxDB或MQTT）。如果两者均未正确配置，连接器将报错退出。

通过Docker或Docker Compose运行

提供了Dockerfile。要构建Docker镜像，进入项目目录并运行docker build -t ecobee_influx_connector .

还提供了可通过环境变量配置的Docker镜像。https://hub.docker.com/r/cdzombak/ecobee_influx_connector%EF%BC%8C%E6%88%96%E9%80%9A%E8%BF%87%60docker pull docker.xuanyuan.run/cdzombak/ecobee_influx_connector`拉取。

使用Docker容器时，确保将config.json的路径作为卷挂载到/config路径。此位置还将用于存储刷新令牌和config.json。

重要提示

在构建持久化容器之前，应执行docker run --rm -it -v $HOME/ecobee:/config cdzombak/ecobee_influx_connector -config "/config/config.json" -list-thermostats以获取令牌缓存（/config/ecobee-cred-cache）。这将提供用于Ecobee API应用认证的密钥。认证后，将显示所有设备的thermostat_ids。

如果在执行上述操作前构建持久化容器，初始令牌请求将循环，难以获取缓存令牌。

Docker Compose

提供了示例docker-compose.yml文件。确保修改volumes部分，将您的/config文件夹映射到容器的/config文件夹。

示例：

yaml
volumes:
  - $DOCKERAPPPATH/ecobee_influx_connector:/config

Docker Run

示例：

如果使用从Dockerfile构建的镜像：

shell
docker run -d --name ecobeetest --restart=always -v ./config:/config -it docker.xuanyuan.run/ecobee_influx_connector

如果使用Docker Hub镜像：

shell
docker run -d --name ecobeetest --restart=always -v ./config:/config -it docker.xuanyuan.run/cdzombak/ecobee_influx_connector:latest

通过apt仓库在Debian上安装

如果尚未安装我的Debian仓库，请执行：

shell
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://dist.cdzombak.net/deb.key | sudo gpg --dearmor -o /etc/apt/keyrings/dist-cdzombak-net.gpg
sudo chmod 0644 /etc/apt/keyrings/dist-cdzombak-net.gpg
echo -e "deb [signed-by=/etc/apt/keyrings/dist-cdzombak-net.gpg] https://dist.cdzombak.net/deb/oss any oss\n" | sudo tee -a /etc/apt/sources.list.d/dist-cdzombak-net.list > /dev/null
sudo apt-get update

然后通过apt-get安装ecobee_influx_connector：

shell
sudo apt-get install ecobee-influx-connector

从源码构建

shell
make build

交叉编译（例如Linux/amd64）：

shell
env GOOS=linux GOARCH=amd64 go build -ldflags="-X main.version=$(./.version.sh)" -o ./ecobee_influx_connector .

在Linux上通过systemd运行

1. 构建ecobee_influx_connector二进制文件或按照上述说明安装
2. 将其复制到/usr/local/bin或您偏好的位置
3. 为连接器创建工作目录（例如$HOME/.ecobee_influx_connector）
4. 运行chmod 700 $YOUR_NEW_WORK_DIR（例如chmod 700 $HOME/.ecobee_influx_connector）
5. 按照配置说明创建配置JSON文件（例如$HOME/.ecobee_influx_connector/config.json）
6. 使用您的用户/组名称和配置文件路径自定义https://raw.githubusercontent.com/cdzombak/ecobee_influx_connector/main/ecobee-influx-connector.example.service
7. 将自定义的ecobee-influx-connector.service复制到/etc/systemd/system
8. 运行chown root:root /etc/systemd/system/ecobee-influx-connector.service
9. 运行systemctl daemon-reload && systemctl enable ecobee-influx-connector.service && systemctl start ecobee-influx-connector.service
10. 通过systemctl status ecobee-influx-connector.service检查服务状态

MQTT主题结构

启用MQTT时，连接器将数据发布到以下主题结构：

<topic_root>/<thermostat_id>/<category>/<measurement>

其中：

• <topic_root>是配置的根主题（例如"ecobee"）
• <thermostat_id>是配置中的恒温器ID
• <category>是数据类别（runtime、sensor、weather）
• <measurement>是要发布的特定指标

示例：如果主题根为"home/sensors"且恒温器ID为"***"，则室内温度将发布到：home/sensors/123456789/runtime/temperature_f

常见问题

连接器是否支持多个恒温器？

连接器不直接支持多个恒温器。建议运行多个连接器实例，每个实例需要自己的工作目录和配置文件，但可以为每个连接器实例使用相同的API密钥。

（如果使用"在Linux上通过systemd运行"的说明部署，可为每个连接器的服务文件指定唯一名称，如ecobee-influx-connector-1.service、ecobee-influx-connector-2.service等。）

许可证

Apache 2.0；参见仓库中的LICENSE文件。

作者

Chris Dzombak（GitHub：https://github.com/cdzombak%EF%BC%89%E3%80%82