A Home Assistant integration to analyze and monitor the thermal performance of your home.

• Why Home Performance?
• Main Features
• Installation
• Hardware Compatibility
• Concept
• Created Sensors
• Multi-zones
• Lovelace Card
• Clearing Card Cache
• Temperature Units
• Prerequisites
• Configuration
• Translations
• Data Persistence
• Usage
• Dashboard Examples
• Energy Performance
• Roadmap
• Support
• Contributing
• License

You have a heating system and wonder:

• "Is my room well insulated?" → Measured K coefficient
• "How much do I actually consume?" → Daily energy
• "Did I forget to close a window?" → Automatic detection
• "Which room costs the most?" → Multi-zone comparison

Home Performance answers these questions by analyzing your real heating data, without theoretical calculations. Works with electric heaters, heat pumps, gas boilers, and gas furnaces!

• 🏠 Multi-zone - Manage all your rooms from a single integration
• 🎴 Built-in Lovelace card - Modern design, ready to use
• 📊 Measured energy counter - Power sensor integration (Utility Meter)
• 💾 Data persistence - Saved after restart
• 🎯 Energy performance - Comparison to national average
• ⚡ Event-driven architecture - Instant detection (heating, windows)
• 🪟 Open window detection - Real-time alert on temperature drop

1. Open HACS
2. Click on "Integrations"
3. Search for "Home Performance"
4. Click "Download"
5. Restart Home Assistant

1. Copy custom_components/home_performance to your config/custom_components/ folder
2. Restart Home Assistant

The integration is 100% hardware agnostic! It works with anything that exposes standard Home Assistant entities.

💡 Important for Heat Pumps: If your heat pump has variable/modulating power, configure a power_sensor (real-time power in Watts). The integration will integrate the actual power over time instead of using a fixed heater_power value. This is much more accurate for systems where power output varies.

The integration supports 4 heat source types:

* For non-electric sources, you can set heater_power to 0 to remove it and rely entirely on energy_sensor or power_sensor for energy calculation.

• New zone: The heat source type selector appears on the first configuration screen
• Existing zone: Go to Settings → Integrations → Home Performance → click Configure (⚙️) on your zone → the heat source type is the first field in the options form

The K coefficient calculation uses energy data from the most accurate available source:

💡 Tips:

• For best accuracy, use an energy meter (smart plug with energy tracking, smart gas meter, etc.)
• For gas/heat pump without smart meter, you can use PowerCalc to create an energy sensor from a power estimate
• If you only have heater_power, the integration will still work but with estimated energy

This integration calculates the thermal loss coefficient K of each room using a simple physical approach:

K (W/°C) = Energy supplied / (ΔT × duration)
         = (Heater_power × heating_time) / (Avg_ΔT × 24h)

Concrete example: A 1000W heater running 6h out of 24h to maintain 19°C when it's 5°C outside:

• Energy = 1000W × 6h = 6 kWh
• ΔT = 14°C
• K = 6000 / (14 × 24) ≈ 18 W/°C

→ This room loses 18W per degree of difference with the outside.

This integration uses empirical measurement of thermal performance, unlike theoretical methods:

Example: A window certified Uw=1.1 W/(m²·K) may actually have degraded performance if poorly installed or with worn seals. Empirical measurement captures these imperfections.

U coefficients (formerly "K" in standards) measure the thermal transmission of a specific wall (window, wall) in W/(m²·K). They are measured in laboratories and allow product comparison.

Home Performance's K coefficient measures the global heat loss of an entire room in W/°C. It's equivalent to the G (or GV) coefficient used in building thermal engineering, but measured empirically rather than calculated.

The K coefficient is a physical constant of your room's insulation. It measures heat loss per degree of temperature difference, so it should remain stable regardless of outdoor temperature.

➡️ You'll consume more energy when it's cold, but your insulation rating should stay the same.

Why might K slightly vary in practice?

Tip: If you notice a significant drop in your insulation rating during cold spells, it may reveal thermal bridges, air leaks around windows/doors, or sealing issues. This is the value of empirical measurement!

The insulation rating is calculated over a 7-day rolling window for stability. This prevents rating changes at midnight and smooths out anomalous days (open window, guests, etc.).

Days are included in the K_7d calculation if:

• ΔT ≥ 5°C (sufficient temperature difference)
• AND one of:
  • Heating time ≥ 30 min (normal case)
  • OR: Heating time ≥ 6 min AND stable indoor temperature (excellent insulation case)

💡 This "smart filtering" rewards days with little heating but stable temperature, instead of ignoring them.

The rating automatically adapts to all situations:

The highest rating S (Optimal) is awarded when your room demonstrates exceptional thermal performance over 7 consecutive days:

Note: This isn't just "no heating" - the room must maintain a comfortable temperature (≥17°C) without significant heating. A cold room with no heating won't qualify.

Days are categorized for the K_7d calculation:

This ensures rooms with excellent insulation (needing little heating) still get accurate K values instead of being ignored.

If after 24h of observation:

• ΔT is significant (≥ 5°C)
• The heater has run very little (< 30 min)
• Indoor temperature remained stable (variation < 2°C)

→ The integration automatically infers that insulation is excellent!

Logic: If the room maintains its temperature without heating while it's cold outside, heat loss is very low.

In summer or shoulder season, the integration keeps the last calculated K coefficient and displays it with the appropriate season message. You thus keep a useful reference all year round.

The Lovelace card displays a warning indicator when indoor temperature conditions suggest the K score may be biased:

Why does this matter?

Large temperature swings (e.g., 15°C at night → 21°C during the day) or letting the room get cold can bias the K calculation. If you let the temperature drop significantly when not heating, the calculated K will appear better than actual insulation quality.

The warning helps you understand that:

• The K value may not reflect true insulation performance
• Consider maintaining more stable temperatures for accurate measurement

Display by layout:

• Full: Orange banner with details (variation range)
• Badge: 2-line indicator "⚠️ VARIATION ±X°C"
• Pill/Multi-zone: Compact ⚠️ icon

When the K coefficient was calculated on a previous day (not today), the card displays the date:

Excellent (K du 19/01)

This helps understand that the current K value comes from historical data, not today's measurements (useful for rooms with minimal recent heating).

Completed renovation work? Changed windows? You can reset the 7-day history to start fresh measurements:

# Developer Tools > Services
service: home_performance.reset_history
data:
  zone_name: "Living Room"

What the reset does:

• ✅ Clears the 7-day history
• ✅ K coefficient recalculates from new data
• ❌ Does NOT delete current day's data (no 12h wait)
• ❌ Does NOT lose last valid K (kept as reference)

For a complete reset (after major changes like new heating equipment, insulation renovation, or to clear all anomalous data):

# Developer Tools > Services
service: home_performance.reset_all
data:
  zone_name: "Living Room"

What the complete reset does:

• ✅ Clears ALL data (history, coefficients, energy counters)
• ✅ Resets to initial state (like a fresh install)
• ⚠️ Requires 12h of new data collection

Timeline after reset:

Note: Measured energy takes priority over estimated in the card. The source attribute indicates the origin: external (HA counter) or integrated (calculation from power sensor).

The source attribute on Time/Ratio indicates: measured (via power sensor > configured threshold) or estimated (via switch state).

Easily manage all your rooms!

1. Settings → Devices & services
2. Click "+ Add integration"
3. Search for "Home Performance"
4. Configure the new zone

Each zone appears as a separate entry, all grouped under "Home Performance":

Home Performance - Flavien's Room
Home Performance - Living Room
Home Performance - Office

In the integrations list, click Options (⚙️) of the zone to modify:

• Change settings (power, surface, sensors...)
• Delete the zone

Each zone has its own sensors and own Lovelace card.

The integration includes a ready-to-use modern custom card with multiple layout options!

The Lovelace resource is automatically registered when installing the integration (HA default storage mode).

Simply add one card per zone in your dashboard:

type: custom:home-performance-card
zone: Living Room
title: Living Room Performance

type: custom:home-performance-card
zone: Bedroom
title: Bedroom Performance

Starting with v1.4.0, the card resource URL has changed and is now automatically managed.

What happens automatically:

• Old manually-added resources (/home_performance/home-performance-card.js) are detected and removed
• New resource is registered with version parameter (/home-performance/home-performance-card.js?v=X.X.X)
• Version mismatch detection notifies you when frontend/backend versions differ

Choose the layout that fits your dashboard style:

type: custom:home-performance-card
zone: Living Room
layout: full

The complete card showing insulation rating, performance, temperatures, and detailed metrics.

type: custom:home-performance-card
zone: Bedroom
layout: badge

A compact vertical card showing the score letter (S to D), zone name, and K coefficient. Perfect for creating a grid of all your rooms.

type: custom:home-performance-card
zone: Office
layout: pill

A slim horizontal bar showing score, zone name, K coefficient, and ΔT. Ideal for sidebars or compact dashboards.

type: custom:home-performance-card
layout: multi
default_view: list
show_sparklines: true

A comprehensive card that displays all your zones in one place. No need to specify a zone - it auto-detects all configured zones.

Features:

• 📋 List View - All zones with expandable details (click to expand)
• 🏆 Compare View - Ranking by K/m³ performance with percentage difference
• 🔄 Toggle - Switch between List and Compare views
• 📊 Sparklines - Mini trend graphs for each zone
• 🎯 Average Score - Overall home performance at a glance

Multi-Zone Options:

* Not required for layout: multi (auto-detects all zones)

• 📊 Visual scores - Insulation rating from S to D with colors
• 📈 Historical K graph - 7-day history with bar chart (full) or sparkline (badge/pill)
• 🌡️ Temperatures - Indoor/Outdoor in real-time
• 📉 Detailed metrics - K coefficient, Energy, Heating time
• 💨 Wind data - Current wind speed, direction and room exposure (full/badge/multi layouts)
• ⏳ Progress - Progress bar during initial analysis
• 🎨 Adaptive design - Adapts to light/dark theme
• 🎛️ Visual editor - Choose layout directly in the UI

After updating the integration, your browser may still display the old card version due to caching.

The card now automatically detects version mismatches between the frontend card and the backend integration. If a mismatch is detected, a notification will appear with a "Reload" button that clears the cache and refreshes the page.

Note: The resource URL now includes an automatic version parameter (?v=X.X.X) that updates with each integration update.

If you need to manually clear the cache:

Method 1: Hard Refresh (Quick)

• Windows/Linux: Ctrl + Shift + R or Ctrl + F5
• Mac: Cmd + Shift + R

Method 2: Clear Browser Cache

1. Open Developer Tools (F12)
2. Right-click the refresh button → "Empty Cache and Hard Reload"

Method 3: Mobile Companion App

• Go to app settings → Clear cache, or force-stop the app

Open the browser console (F12 → Console tab) and look for:

HOME-PERFORMANCE v1.3.0

If you see an older version, the cache hasn't been cleared yet.

The card displays a 7-day history of your K coefficient score:

Features:

• 🎨 Color-coded - Each bar/point colored by its insulation rating (A+ green → D red)
• 📅 Daily K_7j - Shows the rolling 7-day average you had each day (not daily fluctuations)
• 🔮 Estimated days - Days without sufficient data show estimated values (semi-transparent)

Disable the graph:

type: custom:home-performance-card
zone: Living Room
layout: pill
show_graph: false

The integration automatically supports both Celsius and Fahrenheit based on your Home Assistant unit system configuration.

The K coefficient measures thermal loss in Watts per degree Celsius. This is the international scientific standard, ensuring:

• Consistent comparison between users worldwide
• Compatibility with building industry standards
• No confusion with rating thresholds

Note: If your temperature sensors report in Fahrenheit, the integration automatically converts them to Celsius for calculations, then converts back to Fahrenheit for display.

• Home Assistant 2024.4.0 or newer
• Indoor temperature sensor (per zone)
• Outdoor temperature sensor (shareable between zones)
• Climate OR switch entity controlling heating (per zone)

If your heating system uses a select.* or input_select.* entity (common with Modbus heat pumps, NodOn fil pilote modules, etc.), create a template binary sensor to bridge it:

# In configuration.yaml
template:
  - binary_sensor:
      # Example 1: NodOn fil pilote (French modes)
      - name: "Radiateur Salon Actif"
        unique_id: radiateur_salon_actif
        state: "{{ states('select.nodon_fil_pilote_mode') in ['Confort', 'Eco'] }}"
        device_class: running

      # Example 2: Modbus heat pump
      - name: "Heat Pump Heating Active"
        unique_id: heatpump_heating_active
        state: "{{ states('select.heatpump_mode') == 'Heating' }}"
        device_class: running

      # Example 3: Multiple active states
      - name: "HVAC Heating Active"
        unique_id: hvac_heating_active
        state: "{{ states('select.hvac_mode') in ['Heat', 'Auto Heat', 'Emergency Heat'] }}"
        device_class: running

Then use the binary sensor (e.g., binary_sensor.radiateur_salon_actif) as your heating entity in Home Performance.

💡 Why a template? Each heating system has different state names ("Confort", "Heating", "Heat", "On"...). A template lets you define exactly which states mean "heating is active" for YOUR specific setup.

📊 Power Sensor - Dual Purpose: The power_sensor serves two purposes:

1. Precise heating detection: Detects when heating is active (power > threshold) - ideal for thermostatic heaters
2. Energy integration: When no energy_sensor is configured, the integration integrates the real-time power over time to calculate energy consumption. This is especially useful for modulating systems (heat pumps, inverter AC) where power output varies.

The efficiency factor converts consumed energy (electricity, gas) to actual thermal output:

💡 Tips:

• For heat pumps, use your unit's actual COP (Coefficient of Performance) if known, or enable Dynamic COP (see below)
• For gas systems, check your equipment's AFUE rating and convert to decimal (e.g., 92% AFUE = 0.92)

For heat pumps, the COP (Coefficient of Performance) varies significantly based on:

• Outdoor temperature (COP drops when it's very cold)
• Operating mode (heating, defrost cycles)
• System age and maintenance

Instead of using a fixed efficiency factor, you can enable Dynamic COP which automatically measures and adapts the COP based on your real consumption data.

When Dynamic COP is enabled, two additional sensors are created:

• ✅ Seasonal adaptation: COP automatically adjusts between winter (lower) and spring (higher)
• ✅ Performance monitoring: Detect if your heat pump loses efficiency over time
• ✅ Accurate K calculation: Uses real measured efficiency instead of assumed values
• ✅ Zero configuration: Once enabled, everything is automatic

1. Go to Settings → Integrations → Home Performance
2. Click Configure on your zone
3. Select Heat Pump as heat source type
4. Submit → A second step appears: "Heat Pump Options"
5. Enable "Enable dynamic COP calculation"
6. Submit

Requirements: An energy sensor (daily counter) is required for COP calculation. Without it, the COP cannot be measured.

Note: The static efficiency factor remains as a fallback if not enough data is available (first 7 days, or if heating was minimal).

Heat source type: Electric
Heater power: 1500  (required - your heater's rated power in Watts)
Energy sensor: (optional - for measured vs estimated energy)

Heat source type: Heat pump
Heater power: 17600  (optional - declared power for estimation fallback)
Energy sensor: sensor.heatpump_energy  (recommended - required for Dynamic COP)
Enable dynamic COP: Yes  (optional - auto-calibrate efficiency from measurements)

Heat source type: Gas Boiler
Heater power: 17600  (optional - declared power in Watts)
Energy sensor: sensor.gas_energy  (optional but recommended for accuracy)
Efficiency factor: 0.90  (default, condensing boilers typically 0.85-0.95)

Heat source type: Gas Furnace
Heater power: 17600  (optional - declared power in Watts, e.g., 60,000 BTU/h = 17,600W)
Energy sensor: sensor.furnace_energy  (optional but recommended for accuracy)
Efficiency factor: 0.85  (default, typical US furnace 0.78-0.90)

Notes:

• For non-electric sources, the K coefficient is calculated directly from the measured energy.
• If heater_power is not provided, performance thresholds are derived from observed energy/time ratio.
• If you provide an external energy counter AND a power sensor, the external counter is used as priority for energy.
• The power sensor also enables precise heat detection (power > threshold), ideal for heaters with internal thermostat or pilot wire. The threshold is configurable (default: 50W).
• The Window/Door sensor allows using a physical contact sensor (window, door, opening) for accurate open detection instead of relying on temperature-based detection. If the sensor is unavailable, it falls back to temperature detection automatically.
• The Weather entity enables wind data display on cards. Combined with room orientation, it calculates wind exposure (exposed/sheltered) to help understand K coefficient variations.
• Options are modifiable afterwards and the integration reloads automatically.

Get a push notification when a window is detected open while heating is running.

Setup: Settings → Integrations → Home Performance → Configure (⚙️)

The notification is translated (EN/FR/IT) based on your Home Assistant language.

Blueprint alternative: A Blueprint is also available for advanced customization (custom messages, TTS, multiple devices...).

The integration is fully translated in 3 languages:

The language is automatically selected based on your Home Assistant system language.

Data is automatically saved and restored after a Home Assistant restart:

• ✅ Real-time thermal data (up to 48h)
• ✅ Long-term daily history (up to 5 years) 📊
• ✅ Calculated K coefficient
• ✅ Energy counters
• ✅ No need to wait 12h again after each restart!

Storage: /config/.storage/home_performance.{zone}

Save frequency: Every 5 minutes + at HA shutdown

The integration stores daily aggregated data for up to 5 years per zone:

Storage size: ~73 KB per zone per year (very lightweight)

This long-term history will enable future features like:

• 📈 Monthly/yearly performance graphs
• 🔄 Season-to-season comparison (Winter 2024 vs 2023)
• ⚠️ Insulation degradation detection over time

1. Go to Settings → Devices & services
2. Click "Add integration"
3. Search for "Home Performance"
4. Configure your first zone

1. Go to Settings → Devices & services
2. Click "+ Add integration"
3. Search for "Home Performance"
4. Configure the new zone

Note: Calculations start after 12h of collected data and require a minimum ΔT of 5°C to be reliable.

Additional examples are available in examples/dashboard_card.yaml:

For advanced options, install via HACS:

• Mushroom Cards
• stack-in-card
• ApexCharts Card

The performance sensor compares your consumption to the French national average:

Thresholds are dynamically calculated based on heater power (or derived power for non-electric sources):

Excellent      : < (Power_W / 1000) × 4 kWh/day
Standard       : < (Power_W / 1000) × 6 kWh/day
Needs optimization : beyond

For non-electric sources: If heater_power is not configured, the system derives an average power from observed energy / heating_hours. This allows performance evaluation even for heat pumps, gas boilers, or gas furnaces.

Note: These thresholds are automatically calculated for any power entered. The values above correspond to the most common heater powers.

• K Coefficient (W/°C) - empirical thermal loss
• K/m² and K/m³ normalization
• Smart insulation rating (calculated, inferred, or conserved)
• 7-day rolling history for stable insulation rating
• Manual reset service (home_performance.reset_history)
• Season management (summer, shoulder season, heating season)
• Automatically inferred excellent insulation (low heating + stable T°)
• Last valid K conservation (shoulder season)
• Daily energy (estimated and measured)
• External HA energy counter support
• Precise heat detection via power sensor (event-driven)
• Real-time open window detection (event-driven)
• Built-in Lovelace card (auto-registered with version management) 🆕
• Multiple card layouts (full, badge, pill) 🎄
• Celsius/Fahrenheit automatic support
• Data persistence
• Energy performance vs national average
• Utility Meter counter (midnight-to-midnight reset)
• Modifiable options with auto-reload
• Multi-zones (add/remove rooms)
• Event-driven architecture (instant reactivity)
• Historical K graph - 7-day bar chart (full) and sparkline (badge/pill) 📊
• Configurable graph display (show_graph option)
• Efficiency factor for heat pumps (COP) and gas systems
• Physical window/door sensor support
• Multi-zone card - All zones in one card with List/Compare views
• Long-term history - 5 years of daily data storage
• Wind data display - Weather entity integration with wind exposure
• Multiple heat source types (electric, heat pump, gas boiler, gas furnace) 🔥
• Level S "Optimal" rating - 7-day streak of minimal heating + stable comfortable temperature
• Temperature variation warning - Alert when large T° swings may bias K score
• Dynamic COP - Auto-calibrating efficiency factor for heat pumps (measured COP 7d)
• Italian translation - Full i18n support (EN/FR/IT)

• Open window notifications (push) ✅
• Open window notifications (TTS)
• Poor insulation detected alerts
• Weekly consumption report

• Monthly/yearly performance graphs (using 5-year history)
• Season-to-season comparison
• Insulation degradation detection

• BTU/h input support for US furnaces
• Weather correction (wind, sunlight)
• Humidity module (RH, mold risk)
• Air quality module (CO2)
• Thermal comfort module (PMV/PPD)
• Data export (CSV, InfluxDB)
• Native HA Energy Dashboard integration
• Automatic heater detection
• Guided "insulation diagnostic" mode

If this project helps you save energy or understand your home better, consider supporting its development:

Contributions are welcome! Please read the Contributing Guide before submitting a PR.

MIT