ha-energy（哈能量）

Home Assistant Energy Skill

Configure Home Assistant energy monitoring with dashboards, solar, grid, and device tracking.

Before You Start

This skill prevents 8 common errors and saves ~45% tokens.

Known Issues This Skill Prevents

1. Incorrect state_class values (must be total, total_increasing, or measurement)
2. Missing device_class: energy on energy sensors
3. Wrong state_class for utility_meter entities (must be total_increasing)
4. Using unit_of_measurement: kWh without state_class (breaks statistics)
5. Forgetting to enable statistic collection in configuration.yaml
6. Configuring solar sensors without battery tracking for self-consumption
7. Grid monitoring with mismatched sensor pairs (consumption vs return)
8. Utility meter cycle settings that don't align with billing periods

Quick Start

Step 1: Configure Energy Sensors

# 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)) }}"

Why this matters: Proper state_class enables Home Assistant to automatically create statistics and energy dashboard integration. Without it, your sensors won't appear in the energy dashboard.

Step 2: Set Up Utility Meter for Billing Cycles

# 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]

Why this matters: Utility meters automatically reset at specified intervals and track consumption periods for billing analysis.

Step 3: Enable Statistics Recorder

# 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

Why this matters: Statistics require the recorder to be properly configured. Without explicit inclusion, energy sensors may not generate statistics for long-term analysis.

Critical Rules

Always Do

• Use state_class: total_increasing for cumulative meters that only increase
• Add device_class: energy to all energy sensors
• Set unit_of_measurement: kWh (or appropriate unit) on energy sensors
• Configure utility_meter for billing cycle tracking
• Include all energy sensors in recorder's include list
• Reset cumulative sensors on device restart via template sensor
• Use separate sensors for grid consumption and grid return

Never Do

• Use state_class: measurement for cumulative meters (breaks statistics)
• Forget the offset parameter on utility_meter (may cause midnight resets)
• Mix power (W) and energy (kWh) sensors without Riemann sum integration
• Create energy sensors without state_class (they won't work in energy dashboard)
• Assume solar production should subtract from consumption (energy dashboard handles this)
• Configure bidirectional flow on single sensors (use separate consumption/return sensors)
• Skip utility_meter configuration if you need consumption tracking by period

Common Mistakes

Wrong:

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

Correct:

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)) }}"

Why: Template platform is deprecated. Use template integration with proper state_class and device_class to enable energy dashboard integration.

Known Issues Prevention

Configuration Reference

Energy Sensor 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)) }}"

Key settings:

• device_class: energy - Identifies as energy sensor for energy dashboard
• state_class: total_increasing - Cumulative meter that only increases
• state_class: measurement - Instantaneous values (power, not energy)
• unit_of_measurement: kWh - Energy units; use W for power
• availability_template - Prevents unavailable states from breaking statistics

Utility Meter Configuration (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

Key settings:

• cycle: hourly, daily, weekly, monthly, bimonthly, quarterly, yearly
• offset: Time adjustment for billing alignment
• net_consumption: Set to true for solar to track self-consumption

Riemann Sum Integration (for Power to Energy)

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

Key settings:

• source: Power sensor (W) to integrate
• unit_prefix: k - Converts watts to kilowatts
• method: trapezoidal or left for integration algorithm
• round: 3 - Decimal precision

Common Patterns

Grid Monitoring (Consumption + Return)

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)) }}"

Solar Production with Battery

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)) }}"

Device Power Monitoring (Smart Plug)

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

Bundled Resources

References

Located in references/:

• state-class-guide.md - Comprehensive state_class reference
• device-class-reference.md - All energy-related device classes
• utility-meter-patterns.md - Billing cycle configurations
• energy-dashboard-setup.md - Step-by-step energy dashboard guide
• solar-integration.md - Solar panel and battery tracking

Note: For deep dives on specific topics, see the reference files above.

Assets

Located in assets/:

• energy-sensors-template.yaml - Complete sensor template
• utility-meter-examples.yaml - Meter configurations for all scenarios
• energy-dashboard-card.yaml - Dashboard card configuration

Copy these templates as starting points for your implementation.

Context7 Documentation

For current documentation, use these Context7 library IDs:

Official Documentation

• Energy Integration Overview
• Electricity Grid Monitoring
• Solar Panels Integration
• Utility Meter Integration
• Template Sensor
• Statistics Integration

Troubleshooting

Energy Dashboard Shows No Data

Symptoms: Energy dashboard loads but shows "No data available" or blank graphs.

Solution:

# 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

Utility Meter Not Resetting

Symptoms: Utility meter keeps accumulating without resetting at expected time.

Solution:

# 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

Solar Self-Consumption Not Tracking

Symptoms: Self-consumption percentage is 0% or not shown.

Solution:

# 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

Sensor Shows "unknown" or "unavailable"

Symptoms: Sensor state stuck on "unknown" or "unavailable" in Developer Tools.

Solution:

# 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)) }}"

Setup Checklist

Before using this skill, verify:

• Home Assistant is running 2023.1 or later
• You have access to configuration.yaml (File Editor or VS Code add-on)
• You have at least one energy sensor available (grid meter, smart plug, integration sensor)
• You've decided on meter types (grid consumption/return, solar, battery, individual devices)
• You understand your billing cycle (daily, monthly, etc.)
• Recorder is enabled in configuration.yaml
• You've identified all devices/meters to monitor