sfudeus/homematic_exporter

homematic_exporter

概述

homematic_exporter是一个用Python 3编写的工具，用于从Homematic设备导出数据，供Prometheus采集。该工具监听可自定义的端口，以Prometheus格式暴露指标，数据通过XML-RPC周期性从CCU3获取，采集间隔可配置。

homematic_exporter最初为HomematicIP设计，但已验证可用于BidCoS-RF设备（如HM-CC-RT-DN和HM-WDS40-TH-I-2），只需使用相应端口（HomematicIP用2010，BidCoS-RF用2001）。

核心功能与特性

• 多运行模式：支持调试模式（仅 dump 设备列表或单个设备参数）和持续采集模式（持续获取数据并通过HTTP暴露）
• 灵活配置：可自定义CCU端口、采集间隔、暴露端口及设备映射文件
• 丰富指标：指标前缀统一为homematic_，包含CCU实例、设备地址、设备类型等标签
• 设备映射：支持通过配置文件将设备地址映射为自定义名称，便于Grafana等工具使用
• 多设备支持：兼容多种HomematicIP和BidCoS-RF设备（详见限制部分）

使用场景与适用范围

适用于Homematic智能家居用户，特别是使用CCU3作为控制中心，需要通过Prometheus监控设备状态（如温度、湿度、开关状态、能耗等）并结合Grafana进行可视化和告警的场景。

使用方法与配置说明

运行模式

工具支持以下运行模式：

• --dump_devices：仅导出设备列表后退出（调试用）
• --dump_parameters <deviceAddress>：导出指定设备参数后退出（调试用）
• 无特殊参数：持续采集数据并通过HTTP暴露指标（需指定ccu_host）

命令行参数

Docker运行示例

基本运行（持续采集模式）

bash
docker run -d --name homematic_exporter \
  -p 9273:9273 \  # 假设--port指定为9273
  sfudeus/homematic_exporter \
  --ccu_host ccu3.local \
  --ccu_port 2010 \  # HomematicIP设备
  --interval 60 \  # 60秒采集一次
  --port 9273

调试模式（导出设备列表）

bash
docker run --rm sfudeus/homematic_exporter \
  --ccu_host ccu3.local \
  --dump_devices

调试模式（导出指定设备参数）

bash
docker run --rm sfudeus/homematic_exporter \
  --ccu_host ccu3.local \
  --dump_parameters 000123456789

指标说明

命名规则

所有指标以homematic_为前缀，剩余名称基于设备描述符中的参数名。

标签信息

指标包含以下标签：

• ccu：CCU实例标识
• device_address：设备地址
• device_type：设备类型
• parent_device_type：父设备类型

设备名称映射

通过--mapping_file可添加设备地址到自定义名称的映射，映射后的名称可作为标签在Grafana等工具中使用。

限制

目前仅支持以下设备类型（可通过配置文件扩展）：

• 气象站（HmIP-SWO-PL）
• 温湿度传感器（带/不带显示屏）（HmIP-STH、HmIP-STHD）
• 可插拔开关/电表（HMIP-PSM）
• 嵌入式开关/电表（HmIP-FSM）
• 水传感器（HmIP-SWD）
• 门窗传感器（HMIP-SWDO，感谢@kremers）
• BidCoS-RF暖气片温控器（HM-CC-RT-DN，感谢@NilsGriebner）
• BidCoS-RF温湿度传感器（HM-WDS40-TH-I-2，感谢@NilsGriebner）

如需支持更多设备，可通过配置文件扩展，或提交issue请求支持。***设备可帮助扩展支持范围（***链接）。

构建方法

多架构构建

支持x86、arm架构，可使用docker buildx构建：

bash
docker buildx build --platform linux/amd64,linux/arm/v7 -t sfudeus/homematic_exporter:latest .

或使用build.sh脚本。

Docker镜像获取

Docker Hub提供最新镜像（支持amd64和arm）：sfudeus/homematic_exporter:latest，同时带有构建日期标签作为稳定引用。