Home Assistant custom integration for analyzing your Quatt heat pump performance. Calculates optimal heating curves (stooklijn), COP, heat loss characteristics, and optionally compares with historical gas consumption.
- Heating curve analysis — Calculates the optimal stooklijn based on actual heat pump data and compares it with Quatt's estimated curve
- Heat loss coefficient — Determines your home's heat loss in W/K using linear regression
- COP tracking — Average coefficient of performance and per-temperature scatter data
- Knee temperature — Detects the outdoor temperature where supplemental heating (boiler) kicks in
- Gas comparison (optional) — Compare heat pump performance with historical gas consumption from before installation
- Dashboard included — Pre-built Lovelace dashboard with interactive charts
- Home Assistant 2024.1.0 or newer
- Quatt integration configured and running
- apexcharts-card (HACS frontend) for the dashboard charts
- Open HACS in Home Assistant
- Go to Integrations > Custom repositories
- Add
https://github.com/Appesteijn/stooklijnand select Integration as category - Search for "Quatt Warmteanalyse" and install
- Restart Home Assistant
- Copy the
custom_components/quatt_stooklijnfolder to your Home Assistantconfig/custom_components/directory - Restart Home Assistant
- Go to Settings > Devices & Services > Add Integration
- Search for "Quatt Warmteanalyse"
- Follow the setup wizard:
- Start/end date — The period to analyze (after heat pump installation)
- Temperature sensors — Comma-separated entity IDs for outdoor temperature (in priority order)
- Power sensor — Entity for total heat pump power
- Gas entity — Cumulative gas meter (m³)
- Gas period — Date range from before heat pump installation
- Calorific value — Gas energy content (default: 9.77 kWh/m³ for Dutch gas)
- Boiler efficiency — Your old boiler's efficiency (default: 0.90)
- Hot water threshold — Temperature above which gas usage is counted as hot water only (default: 18°C)
- Enter your current Quatt stooklijn setting as two points (e.g. -10°C/10000W and 16°C/0W) for comparison in charts
The analysis runs automatically when Home Assistant starts, so your dashboards are always populated after a restart.
You can also trigger an analysis manually:
- Call the
quatt_stooklijn.run_analysisservice, or - Press the Analyse Starten button on the dashboard
Import the dashboard from dashboards/quatt_stooklijn_dashboard.yaml:
- Go to Settings > Dashboards > Add Dashboard
- Choose New dashboard from scratch
- Open the dashboard, switch to YAML mode (three dots > Edit in YAML)
- Paste the contents of
quatt_stooklijn_dashboard.yaml
The dashboard shows:
- Key metrics (heat loss, balance temperature, knee point, COP)
- Heat loss vs outdoor temperature (with gas comparison if configured)
- Stooklijn comparison: optimal vs Quatt estimated vs your actual setting
- Heating demand vs Quatt capacity
- COP vs outdoor temperature
- Heat demand table at various temperatures
| Sensor | Unit | Description |
|---|---|---|
heat_loss_coefficient |
W/K | Heat loss per degree below balance point |
balance_point |
°C | Outdoor temp where no heating is needed |
optimal_stooklijn_slope |
W/°C | Slope of the optimal heating curve |
quatt_stooklijn_slope |
W/°C | Slope of Quatt's estimated curve |
knee_temperature |
°C | Temperature where boiler must assist |
average_cop |
— | Average coefficient of performance |
freezing_performance_slope |
W/°C | Heat pump performance below 0°C |
gas_heat_loss_coefficient |
W/K | Heat loss from gas period (if configured) |
actual_stooklijn |
W/°C | Your configured Quatt stooklijn |
last_analysis |
timestamp | When the last analysis was run |
analysis_status |
— | Current analysis status |
| Service | Description |
|---|---|
quatt_stooklijn.run_analysis |
Run the full analysis pipeline |
quatt_stooklijn.clear_data |
Clear all analysis results and reset sensors |
The integration ports the analysis from a Jupyter notebook into a Home Assistant integration:
- Data collection — Uses a hybrid approach combining four data sources (see below)
- Stooklijn estimation — Estimates the current Quatt stooklijn from HA recorder minute-level power data, using the 2500W filter to capture full-capacity operation
- Knee detection — Piecewise linear fit on Quatt hourly data to find the temperature where the boiler must assist
- Heat loss regression — Linear regression on daily heat energy vs outdoor temperature to determine your home's thermal characteristics
- COP calculation — Computes daily COP from heat output (
totalHpHeat) and electrical input (totalHpElectric) for accurate values - Auto-startup — Analysis runs automatically when Home Assistant starts, so dashboards are always populated
The integration combines four data sources for the best balance of coverage, accuracy, and speed:
| Source | Data type | Period | Purpose |
|---|---|---|---|
| HA Recorder statistics | Daily means | Full configured period (months) | Heat loss regression, COP scatter, optimal stooklijn |
| HA Recorder state changes | Minute-level | Last 30 days | Quatt stooklijn estimation (instantaneous power) |
| Quatt API | Hourly detail | Last 30 days | Knee detection, envelope analysis |
| Cache | Hourly detail | Previously fetched days | Extends hourly data beyond 30-day API window |
How it works per analysis run:
- Recorder statistics — Fetches daily mean values from HA's long-term statistics for the full configured period. These are derived from the Quatt integration sensors that HA already records (power, temperature, electricity input, boiler heat).
- Recorder state changes — Fetches minute-level power and temperature readings from the last 30 days (limited by HA's
purge_keep_dayssetting, default 10 days). Used to estimate the Quatt stooklijn — minute-level data is essential here because hourly averages from the API can mask partial operation hours. - Cached historical data — Checks the cache for any hourly data from before the 30-day API window. This data was fetched in previous runs and is reused without any API calls.
- Quatt API — Fetches the last 30 days of hourly data from the Quatt
get_insightsservice. Already-cached days are skipped. - Merge — Recorder data forms the base, API data overwrites recent days (more accurate for the last 30 days).
Result: From the first run you get months of daily data (via recorder), plus 30 days of hourly detail. The hourly cache grows organically over time.
Thanks to the hybrid approach, the integration makes very few API calls:
First run: ~30 API calls (last 30 days) + instant recorder fetch
Day 2: ~1 API call (only today, rest cached)
Day 30: ~1 API call (cache now contains 60 days of hourly data)
Day 90: ~1 API call (cache now contains 120 days of hourly data)
Subsequent analyses typically complete in 1-2 seconds with only 1 API call.
The integration estimates your current Quatt stooklijn (heating curve) from HA recorder data:
- Uses minute-level state changes from the recorder (not Quatt API hourly averages)
- Filters for continuous full-capacity operation (≥ 2500W)
- Fits a linear regression to data right of the knee point
- Minute-level data is essential: hourly averages can include partial operation hours that distort the slope
The integration uses advanced knee detection to find the temperature where your heat pump reaches maximum capacity:
- Primary method — Uses all available Quatt hourly data (30 days + cached history)
- Fallback method — Uses last 30 days of HA recorder data if Quatt data is unavailable
- Smart filtering — Automatically removes defrost cycles and partial operation hours
- Progressive accuracy — As the cache grows, more hourly data is available for knee detection
The cache is stored in .storage/quatt_stooklijn_insights_cache and:
- Automatically cleans up data older than 1 year
- Can be manually cleared by deleting the cache file and restarting HA
- Is completely transparent (no configuration needed)
- Survives Home Assistant restarts
Check your Home Assistant logs to see data source performance:
INFO: Fetching recorder statistics for 2025-06-01 to 2026-02-17...
INFO: Recorder statistics: 261 days (2025-06-01 to 2026-02-17)
INFO: Found 28 days of cached historical hourly data
INFO: Fetching Quatt API data for 2026-01-19 to 2026-02-17 (30 days)...
INFO: API/cache data: 58 days total (57 from cache, 1 from API)
INFO: Knee detection (Quatt): 0.16°C, 6437 W (from 245 stable hours)
INFO: Quatt stooklijn estimated from recorder: slope=-353.5 W/°C, intercept=6037 W, zero at 17.1°C (1820 data points)
Problem: Every analysis makes many API calls (cache not working)
Solutions:
- Check
.storage/quatt_stooklijn_insights_cacheexists - Check Home Assistant has write permissions to
.storage/directory - Check logs for cache errors
Problem: Want to start fresh with empty cache
Solution:
- Stop Home Assistant
- Delete
.storage/quatt_stooklijn_insights_cache - Start Home Assistant
- Next analysis will fetch last 30 days from API and rebuild cache (recorder data is always available)
Problem: Knee detection fails or gives unexpected results
Possible causes:
- Not enough cold weather data in hourly cache yet (daily data from recorder is always available)
- Heat pump hasn't operated at maximum capacity during cached period
- Check logs for specific error messages
Solutions:
- Wait for cache to accumulate more winter days (knee detection uses hourly data)
- Ensure heat pump has run during cold periods
- Check that Quatt integration is working correctly
Problem: COP values seem too low
Possible causes:
- Summer days without heating drag down the average
- The integration filters on days with >= 200W heating demand, but check your configured date range
Solution:
- The integration automatically filters non-heating days from COP and stooklijn calculations
This integration is based on the Jupyter notebooks originally created by Rickvdt. The notebooks provided the foundation for the analysis methods used here.
MIT