ha-energy

Name: ha-energy
Author: nodnarbnitram

github.com/nodnarbnitram其他16104 次安装27 周前更新

代码仓库

关于 ha-energy

面向 Home Assistant 用户的能源监测配置技能，指导设置传感器、统计记录器和 Utility Meter。内容覆盖电网、太阳能、电池及设备能耗，并提供 YAML 示例与常见配置问题排查。

主要功能

01能源传感器 YAML 配置
02Utility Meter 计费周期追踪
03Recorder 统计配置
04太阳能、电网与电池监测
05功率积分换算能耗
06常见故障排查与模板

适用场景

01配置 Home Assistant 能源仪表板所需传感器
02按日或账单周期统计能源消耗
03分别追踪电网用电与回馈电量
04监测太阳能、电池或智能插座能耗

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-energy

安装后在 Claude Code 中输入/ha-energy确认已加载。

附带文件README.md

详细介绍

Home Assistant Energy Skill

使用仪表盘、太阳能、电网和设备跟踪配置 Home Assistant 能源监控。

开始之前

此技能可避免 8 个常见错误，并节省约 45% 的令牌。

指标	不使用技能	使用技能
设置时间	45+ 分钟	15 分钟
常见错误	8	0
令牌用量	~10000	~5500

此技能可避免的已知问题

state_class 值不正确（必须为 total、total_increasing 或 measurement）
能源传感器缺少 device_class: energy
utility_meter 实体的 state_class 错误（必须为 total_increasing）
使用 unit_of_measurement: kWh 却未设置 state_class（会导致统计数据异常）
忘记在 configuration.yaml 中启用统计数据收集
配置太阳能传感器时未跟踪电池，导致无法计算自耗
电网监控的传感器对不匹配（消耗与回馈）
utility meter 周期设置与计费周期不一致

快速开始

步骤 1：配置能源传感器

# configuration.yaml
template:
  - sensor:
      - name: "Total Energy Consumed"
        unique_id: total_energy_consumed
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.energy_meter') | float(0)) }}"

      - name: "Solar Production"
        unique_id: solar_production
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.solar_meter') | float(0)) }}"

为何重要： 正确设置 state_class 后，Home Assistant 会自动创建统计数据并集成到能源仪表盘中。否则，传感器不会显示在能源仪表盘中。

步骤 2：设置 utility meter 以匹配计费周期

# configuration.yaml
utility_meter:
  daily_energy:
    source: sensor.total_energy_consumed
    cycle: daily
    offset: [hours: 0]

  monthly_energy:
    source: sensor.total_energy_consumed
    cycle: monthly
    offset: [days: 0]

  daily_solar:
    source: sensor.solar_production
    cycle: daily
    offset: [hours: 0]

为何重要： Utility meter 会按指定间隔自动重置，并跟踪用量周期，以便分析账单。

步骤 3：启用统计数据记录器

# configuration.yaml
recorder:
  db_url: !secret database_url  # Optional but recommended
  auto_purge: true
  auto_purge_days: 90           # Adjust retention as needed
  # Include sensors with state_class for statistics
  include:
    entities:
      - sensor.total_energy_consumed
      - sensor.solar_production
      - sensor.grid_consumption
      - sensor.grid_return

为何重要： 统计数据要求正确配置记录器。如果未明确将能源传感器加入配置，它们可能无法生成长期分析所需的统计数据。

关键规则

始终执行

对只增不减的累计计量表使用 state_class: total_increasing
为所有能源传感器添加 device_class: energy
为能源传感器设置 unit_of_measurement: kWh（或适当的单位）
配置 utility_meter 以跟踪计费周期
将所有能源传感器加入记录器的 include 列表
使用模板传感器，在设备重启时重置累计传感器
为电网消耗和电网回馈分别使用独立的传感器

绝不执行

对累计计量表使用 state_class: measurement（会导致统计数据异常）
忘记为 utility_meter 设置 offset 参数（可能导致在午夜重置）
混用功率（W）和能量（kWh）传感器，却不使用黎曼和积分
创建未设置 state_class 的能源传感器（它们无法用于能源仪表盘）
认为太阳能发电量应从消耗量中扣除（能源仪表盘会处理这一点）
在单个传感器上配置双向流量（应使用独立的消耗和回馈传感器）
需要按周期跟踪消耗量时跳过 utility_meter 配置

常见错误

错误：

sensor:
  - platform: template
    sensors:
      total_energy:
        unit_of_measurement: kWh
        value_template: "{{ states('sensor.meter') }}"

正确：

template:
  - sensor:
      - name: "Total Energy"
        unique_id: total_energy
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.meter') | float(0)) }}"

原因： Template 平台已弃用。请使用 template 集成，并正确设置 state_class 和 device_class，以启用能源仪表盘集成。

已知问题预防

问题	根本原因	解决方案
能源仪表盘没有数据显示	缺少或错误的 `state_class`	累积计量表使用 `total_increasing`
未生成统计数据	传感器不在 recorder 的包含列表中	将传感器实体添加到 recorder 配置中
实用电表未重置	`offset` 错误或缺少 `cycle`	检查周期（每小时／每日／每月）和偏移设置
未计算太阳能自发自用量	未单独配置电池传感器	为电池创建充电／放电传感器
电网用电量不正确	使用双向传感器，而非独立传感器	拆分为 grid_consumption 和 grid_return
重启后传感器不可用	未保留累积计量表读数	为模板传感器添加 `availability_template`
统计数据显示错误数值	原始数据存在负值或缺口	使用黎曼和将功率转换为能量
实用电表显示的周期错误	时区的偏移设置不正确	将偏移与当地午夜或计费周期对齐

配置参考

能源传感器模板（YAML）

template:
  - sensor:
      - name: "Main Energy Meter"
        unique_id: main_energy_meter
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        availability_template: "{{ states('sensor.meter_input') not in ['unavailable', 'unknown'] }}"
        state: "{{ (states('sensor.meter_input') | float(0)) }}"

      - name: "Instantaneous Power"
        unique_id: instantaneous_power
        unit_of_measurement: W
        device_class: power
        state_class: measurement
        state: "{{ (states('sensor.power_meter') | float(0)) }}"

关键设置：

device_class: energy - 标识为能源传感器，以便用于能源仪表盘
state_class: total_increasing - 仅递增的累积计量表
state_class: measurement - 瞬时值（功率，而非能量）
unit_of_measurement: kWh - 能量单位；功率使用 W
availability_template - 防止不可用状态破坏统计数据

实用电表配置（YAML）

utility_meter:
  daily_consumption:
    source: sensor.total_energy_consumed
    cycle: daily
    offset:
      hours: 0
    net_consumption: false        # true for solar with self-consumption

  monthly_consumption:
    source: sensor.total_energy_consumed
    cycle: monthly
    offset:
      days: 1                     # Reset on 1st of month
      hours: 0

  peak_consumption:
    source: sensor.total_energy_consumed
    cycle: weekly
    offset:
      days: 0                     # Reset on Monday
      hours: 0

关键设置：

cycle：每小时、每日、每周、每月、每两个月、每季度、每年
offset：用于与计费周期对齐的时间调整
net_consumption：太阳能场景下设为 true，以跟踪自发自用量

黎曼和积分（将功率转换为能量）

integration:
  - platform: riemann_sum
    name: "Daily Energy from Power"
    unique_id: daily_energy_riemann
    source: sensor.instantaneous_power
    round: 3
    unit_prefix: k                # Converts W to kWh
    unit_time: h
    method: trapezoidal

关键设置：

source：要积分的功率传感器（W）
unit_prefix: k - 将瓦特转换为千瓦
method: trapezoidal 或 left：积分算法
round: 3 - 小数精度

常见模式

电网监测（用电量 + 返送电量）

template:
  - sensor:
      - name: "Grid Consumption"
        unique_id: grid_consumption
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.grid_import') | float(0)) }}"

      - name: "Grid Return"
        unique_id: grid_return
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.grid_export') | float(0)) }}"

带电池的太阳能发电

template:
  - sensor:
      - name: "Solar Production"
        unique_id: solar_production
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.solar_meter') | float(0)) }}"

      - name: "Battery Charge"
        unique_id: battery_charge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_charge_meter') | float(0)) }}"

      - name: "Battery Discharge"
        unique_id: battery_discharge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_discharge_meter') | float(0)) }}"

设备功率监测（智能插座）

template:
  - sensor:
      - name: "Device Energy Today"
        unique_id: device_energy_today
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.device_energy') | float(0)) }}"

utility_meter:
  device_daily_energy:
    source: sensor.device_energy_today
    cycle: daily
    offset:
      hours: 0

捆绑资源

参考资料

位于 references/ 中：

state-class-guide.md - 全面的 state_class 参考
device-class-reference.md - 所有与能源相关的设备类别
utility-meter-patterns.md - 计费周期配置
energy-dashboard-setup.md - 能源仪表盘分步指南
solar-integration.md - 太阳能板和电池跟踪

**注意：**有关特定主题的深入介绍，请参阅上述参考文件。

资源文件

位于 assets/ 中：

energy-sensors-template.yaml - 完整的传感器模板
utility-meter-examples.yaml - 适用于所有场景的计量表配置
energy-dashboard-card.yaml - 仪表盘卡片配置

将这些模板复制为实现方案的起点。

Context7 文档

如需最新文档，请使用以下 Context7 库 ID：

库 ID	用途
`/home-assistant/home-assistant.io`	用户文档：能源、太阳能、电网、utility_meter
`/home-assistant/integrations`	特定设备的集成文档
`/home-assistant/template`	模板传感器参考

官方文档

故障排查

能源仪表板没有数据显示

症状： 能源仪表板加载后显示“没有可用数据”或图表为空白。

解决方案：

# 1. Verify sensors exist and have state_class
developer-tools > States > Search for energy/solar sensors

# 2. Check recorder includes sensors
# In configuration.yaml:
recorder:
  include:
    entities:
      - sensor.total_energy_consumed
      - sensor.solar_production

# 3. Restart Home Assistant
# 4. Wait 10 minutes for statistics to generate
# 5. Check Developer Tools > Statistics

公用事业计量表未重置

症状： 公用事业计量表持续累计，未在预期时间重置。

解决方案：

# Check offset configuration
utility_meter:
  daily_energy:
    source: sensor.total_energy_consumed
    cycle: daily
    # For midnight reset in your timezone:
    offset:
      hours: 0
    # For reset at 6 AM:
    # offset:
    #   hours: 6

太阳能自发自用情况未追踪

症状： 自发自用比例为 0%，或未显示。

解决方案：

# Create separate battery sensors
template:
  - sensor:
      - name: "Battery Charge"
        unique_id: battery_charge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_charge_meter') | float(0)) }}"

      - name: "Battery Discharge"
        unique_id: battery_discharge
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        state: "{{ (states('sensor.battery_discharge_meter') | float(0)) }}"

# In energy dashboard configuration, set:
# - Source: Solar production sensor
# - Battery (optional): Both charge and discharge sensors

传感器显示“unknown”或“unavailable”

症状： 开发者工具中的传感器状态卡在“unknown”或“unavailable”。

解决方案：

# Add availability_template
template:
  - sensor:
      - name: "Energy Meter"
        unique_id: energy_meter
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
        availability_template: "{{ states('sensor.meter_input') not in ['unavailable', 'unknown'] }}"
        state: "{{ (states('sensor.meter_input') | float(0)) }}"

设置清单

使用此技能前，请确认：

Home Assistant 正在运行 2023.1 或更高版本
你可以访问 configuration.yaml（File Editor 或 VS Code 插件）
至少有一个可用的能源传感器（电网电表、智能插头、集成传感器）
已确定计量表类型（电网用电/返送电、太阳能、电池、单个设备）
了解你的计费周期（每日、每月等）
已在 configuration.yaml 中启用 Recorder
已确定所有要监控的设备/计量表

支持 Markdown

登录后评论

基本信息

作者: nodnarbnitram
仓库: nodnarbnitram/claude-code-extensions
分类: 其他
安装次数: 104
GitHub Stars: 16

报告问题