在 Home Assistant (HA) 中，Utility Meter（公共事业仪表）是一个用于累计计量的辅助集成组件。它的核心作用是将一个随时间变化的数值（如电量消耗、燃气流量、用水量）按照指定周期（小时、日、月、年）进行累加、重置并存储历史数据，最终生成类似于电表、水表的读数。

简单来说：如果你的传感器提供的是瞬时功率（W，瓦），Utility Meter 能帮你算出总用电量（kWh，千瓦时）；如果你的传感器提供的是水流的瞬时流量（L/min，升/分钟），它能帮你算出总用水量（m³，立方米）。

1. 核心概念与工作原理

  • 源实体 (Source Entity)：需要被累加的传感器实体，通常是瞬时速率（W、L/min、m³/h）或已经累加但需要周期性重置的值。
  • 周期 (Cycle)：重置计数的间隔。可选：hourly、daily、weekly、monthly、yearly。
  • 计量类型 (Meter Type)：
    • accumulating：适用于表计本身读数一直在增长的设备（如智能电表读数）。Utility Meter 会计算差值（本期读数 - 上期读数）。
    • incremental：适用于传感器每次上报的是增量值（如 5 kWh）。直接累加这个值。
    • gauge：直接将当前值作为统计值，不累加，不推荐用于能耗统计。
  • 计量偏移 (Meter Offset)：定义周期的起点。例如，想让“月”周期从每月 5 号开始，而不是 1 号。

2. 典型使用场景

场景 源实体 (Source) Utility Meter 输出 典型周期
家庭总用电 智能电表读数 (kWh, accumulating) 今日用电量、本月用电量 日、月、年
太阳能发电 逆变器发电量 (kWh, incremental) 今日发电量、本月发电量 日、月
燃气消耗 燃气流量计 (m³/h) 或 累加表 本月燃气用量 月
电动汽车充电 充电桩功率传感器 (W) 每次充电电量 按需手动重置
区域空调能耗 空调功率传感器 (W) 客厅今日空调用电 日

3. 如何配置 Utility Meter

有两种主要配置方法：

方法一：通过 UI 配置（推荐新手）

  1. 进入 设置 → 设备与服务 → 辅助元素。
  2. 点击右下角 添加辅助元素 → 选择 累计计量表 (Utility Meter)。
  3. 填写参数：
    • 名称：Electricity Daily，Water Monthly 等。
    • 计量对象 (Meter Type)：选择 accumulating（如果你的电表直接给读数）。
    • 源实体 (Source Entity)：选择你的传感器实体（如 sensor.electricity_meter_reading）。
    • 重置周期 (Reset Cycle)：选择 monthly。
    • 周期性偏移 (Periodic offset)：一般保持默认（月周期从每月 1 号开始）。
  4. 点击 创建。系统会自动生成一个新的 sensor.xxx 实体。

方法二：通过 configuration.yaml 配置（更灵活）

utility_meter:
  # 示例：日用电量
  daily_electricity:
    source: sensor.electricity_meter_reading  # 源实体
    cycle: daily                             # 日周期
    meter_type: accumulating                 # 累加型表计
  
  # 示例：月用电量（基于日累计表）
  monthly_electricity:
    source: sensor.daily_electricity         # 可以嵌套，将日表作为源
    cycle: monthly
    meter_type: incremental                  # 因为源已重置，这里是增量型
  
  # 示例：带偏移的月用水量（从每月15号开始新周期）
  monthly_water_offset:
    source: sensor.water_meter
    cycle: monthly
    offset: 14                               # 15号开始（0-based索引？实际测试：offset: 14 表示周期从每月15日0点开始）
    meter_type: accumulating

配置后需要重启 HA 或重载核心配置。

4. 在能源仪表板中使用

Utility Meter 最常见的使用场景是作为 HA 官方能源仪表板 (Energy Dashboard) 的数据源。

  1. 进入 设置 → 仪表板 → 能源。
  2. 在 能源配置 中，选择 用电量 → 添加耗能设备。
  3. 在“使用实体”中选择你创建的 Utility Meter 实体（如 sensor.daily_electricity）。
  4. 关键点：你需要将 Utility Meter 的源实体（智能电表读数）也添加为电网输入的实体。HA 会自动利用 Utility Meter 进行周期统计和显示。

5. 重要注意事项与最佳实践

  • 状态类属性 (State Class)：源实体的 state_class 属性至关重要。
    • 对于 accumulating 类型，源实体应具有 state_class: total_increasing。
    • 对于 incremental 类型，源实体应具有 state_class: total。
    • 否则 Utility Meter 可能无法正确计算或历史数据异常。
  • 数据缺失问题：如果源实体上报数据频率很低（如每10分钟一次），Utility Meter 在重置瞬间可能错过最后几个增量，导致统计偏小。建议源数据上报间隔不超过5分钟。
  • 重置时刻的行为：在周期重置的那一瞬间（如每月1日0:00），Utility Meter 的数值会变为 0（incremental 类型）或显示新的差值起点。旧的周期值会自动存储为历史属性，可通过 recorder 查看或调用服务获取上周期读数。
  • 手动重置：你可以通过服务调用 utility_meter.calibrate 手动设置 Utility Meter 的值，或调用 utility_meter.reset 手动重置周期。

6. 实际示例：统计空调夜间用电

目标：统计每天晚上 22:00 到次日 06:00 的空调耗电量。

步骤：

  1. 拥有一个空调功率传感器 sensor.ac_power（单位 W）。
  2. 使用 Integral（积分）集成将其转换为累计电量（kWh），创建 sensor.ac_energy_total（state_class: total_increasing）。
  3. 创建 Utility Meter，设置周期 monthly，但利用 自动化 在每晚 22:00 重置它？ 不行，Utility Meter 固定周期不支持任意时间窗。
    • 变通方案：创建两个辅助日期时间实体，配合自动化手动调用 utility_meter.reset 服务，但更推荐使用 utility_meter + 偏移 + 自定义时间戳 或改用 history_stats 集成。

对于非标准时间窗（如夜间电价时段），history_stats 比 Utility Meter 更合适。

7. 常见问题排查

问题 可能原因 解决方法
Utility Meter 数值一直为 unknown 源实体状态为 unknown 或 unavailable 检查源传感器是否正常工作
数值异常巨大 源实体是瞬时功率(W)但未经过积分；meter_type 选错 先用 Integral 集成累加，或改用 incremental 但确保源值很小
重置后新周期不从0开始 使用了 accumulating 类型且源实体读数未重置 正常行为。若想从0开始，使用 incremental 类型
历史数据不显示在能源仪表板 Utility Meter 的源实体 state_class 缺失 为源实体添加 state_class: total_increasing 或 total

总结

  • Utility Meter = 周期性的累加器 + 自动重置 + 历史存档
  • 最适合与能源仪表板配合，实现日/月/年级别的能耗统计。
  • 源实体必须是累计型数值（自己积分或用累加表），而不是瞬时速率。
  • 配置简单、性能好，是 HA 中能耗管理的基石组件。