Intelligent heat pump optimizer for dynamic electricity markets
USE AT YOUR OWN RISK. This integration controls your heat pump's heating curve offset. While extensively tested and designed with safety-first principles, we are not responsible for:
- Heat pump damage or malfunction
- Uncomfortable indoor temperatures
- Increased energy costs
- Any other issues arising from use of this integration
This is experimental software controlling real heating systems. Monitor your system closely, especially during the first weeks. If anything seems wrong, disable the integration immediately.
Automatically optimizes your heat pump to minimize electricity costs (spot prices + effect tariff) while maintaining comfort and heat pump health. Continuously adjusts heating curve offset based on prices, peak risk, weather forecasts, and learned building characteristics.
Lower bills without sacrificing comfort or longevity.
Currently supports NIBE heat pumps via MyUplink integration, with plans to add support for additional brands in the future.
8-layer decision system that balances competing priorities:
- Safety (temperature limits) - always enforced
- Emergency (thermal debt prevention) - climate-aware DM thresholds
- Effect tariff (peak avoidance) - predictive 15-min protection
- Weather compensation (mathematical flow temp) - André Kühne + Timbones formulas
- Weather prediction (pre-heating) - time-aware cold snap protection
- Spot price (cost reduction) - native GE-Spot 15-min integration
- Learning (predictive control) - self-tuning thermal model
- Comfort (tolerance) - reactive temperature correction
Automatic latitude-based zone detection (Arctic to Mediterranean):
- Extreme Cold (66.5°N+): Kiruna, Tromsø - DM -800 to -1200 normal
- Very Cold (60.5-66.5°N): Luleå, Umeå - DM -600 to -1000 normal
- Cold (56-60.5°N): Stockholm, Oslo, Helsinki - DM -450 to -700 normal
- Moderate Cold (54.5-56°N): Copenhagen, Malmö - DM -300 to -500 normal
- Standard (<54.5°N): Paris, London - DM -200 to -350 normal
No configuration needed - uses Home Assistant latitude. DM -1500 absolute maximum enforced globally.
Learns your building over 7-14 days:
- UFH type detection - concrete slab (6h lag) vs timber (2-3h lag) vs radiators (<1h lag)
- Thermal mass - building heat storage capacity (kWh/°C)
- Heat loss coefficient - envelope performance (W/°C)
- Heating efficiency - system response to offset changes (°C/°C)
- Weather patterns - seasonal adaptation with unusual weather detection
Predictive pre-heating uses learned parameters for intelligent load shifting.
Native 15-minute (quarterly) integration:
- Top-3 monthly peak tracking - prevents creating new peaks
- Predictive peak avoidance - acts before spikes using temp trends
- Day/night weighting - full effect daytime, reduced nighttime
- Savings calculation - estimates monthly savings (effect + spot)
Works with any 15-min price source (GE-Spot, Nordpool, Tibber, etc.).
Physics-based flow temperature optimization:
- André Kühne formula - validated across manufacturers (Vaillant, Daikin, NIBE, etc.)
- Timbones method - radiator-specific calculations (BS EN442)
- UFH adjustments - concrete slab (-8°C), timber (-5°C)
- Climate-aware margins - automatic safety headroom by zone
Uses proper heat transfer mathematics to optimize flow temperature beyond standard outdoor temp curves.
Production-ready safety mechanisms:
- Climate-aware thermal debt - DM thresholds adapt to outdoor temp + zone
- Trend-aware damping - prevents overshoot/undershoot (±0.3°C/h detection)
- Configuration validation - warns about potentially problematic setups
- DHW coordination - prevents thermal debt from hot water cycles
- Manual override - services for diagnostic control
- Home Assistant 2025.10+
- Compatible heat pump with MyUplink integration
- NIBE: F2040, F750, F730, S1155, S-series (currently supported)
- Additional brands: Planned for future releases
- MyUplink integration configured
- Price integration with 15-min data (GE-Spot, Nordpool, Tibber, etc.)
- Weather integration (Met.no or equivalent)
- Open HACS → Integrations
- Click ⋮ → Custom repositories
- Add
https://github.com/enoch85/EffektGuardas Integration - Search for "EffektGuard" and install
- Restart Home Assistant
- Add integration via Settings → Devices & Services → Add Integration
- Download latest release
- Extract to
custom_components/effektguard/ - Restart Home Assistant
- Add integration via Settings → Devices & Services
Guided setup flow with validation:
- Select heat pump entity - heating curve offset (e.g., number.xxx_offset_s1_47011 for NIBE)
- Select price entity - quarterly price sensor (GE-Spot, Nordpool, etc.)
- Select weather entity - forecast integration
- Configure targets - indoor temperature, tolerance, optimization mode
- Optional features - DHW optimization, power meter, extra sensors
System auto-detects:
- Climate zone (from latitude)
- UFH type (from thermal lag)
- Heat pump model (from entity patterns)
- Pump configuration (validates against system type)
Integration Layer (HA-specific)
└── coordinator.py (DataUpdateCoordinator pattern)
├── climate.py (main UI entity)
├── sensor.py (monitoring entities)
└── services.yaml (manual control)
Optimization Engine (pure Python)
└── decision_engine.py (8-layer aggregation)
├── thermal_model.py (physics)
├── price_analyzer.py (GE-Spot classification)
├── effect_manager.py (peak tracking)
├── weather_compensation.py (mathematical WC)
├── adaptive_learning.py (self-tuning)
├── thermal_predictor.py (pre-heating)
└── climate_zones.py (latitude detection)
Data Adapters (external interfaces)
├── nibe_adapter.py (MyUplink read/write)
├── gespot_adapter.py (price data)
└── weather_adapter.py (forecast)
Heat Pump/Price/Weather Entities → Adapters → Coordinator →
Decision Engine → Optimization → Climate Entity → Curve Offset
5-minute update cycle with instant responses to entity state changes (power sensor availability listener).
Weighted average of active layers with critical layer override:
- Critical layers (weight ≥ 1.0): Safety, Emergency, Effect @ peak
- Advisory layers (weight < 1.0): Weighted aggregation
- Emergency always wins - thermal safety > peak cost protection
Heat deficit tracking used by many heat pumps (NIBE Menu 4.9.3, others may vary):
DM = ∫(BT25 - S1) dt
- BT25: Actual flow temperature
- S1: Target flow temperature
- Negative DM: Heat deficit (compressor catching up)
Climate-aware thresholds prevent heat pump damage. DM -1500 absolute maximum enforced.
Native quarterly (15-min) price periods:
- 96 periods/day - matches effect tariff measurement
- 4-tier classification - cheap/normal/expensive/peak (percentile-based)
- Day/night weighting - full optimization daytime, reduced nighttime
- Auto-discovery - finds price entity automatically
# André Kühne formula (universal)
TFlow = 2.55 × (HC × (Tset - Tout))^0.78 + Tset
# Timbones method (radiator-specific)
TFlow = ((Pin / Pout)^(1/1.3) × (DTout / DTin)) × (Tset - Tout) + TsetCombined with climate-aware safety margins (0.0-2.5°C by zone).
- Day 1-3: Low confidence (0.0-0.3), conservative defaults
- Day 4-7: Medium confidence (0.3-0.7), starts using learned params
- Day 8-14: High confidence (0.7-1.0), fully optimized
- Ongoing: Continuous refinement, seasonal adaptation
672 observations (1 week @ 15-min) minimum for reliable learning.
- Climate Zones - Global climate adaptation system
- Architecture - System design with flow diagrams
- DHW Optimization - Hot water scheduling
- Release Process - Version management
Current version: v0.0.23 (pre-release)
Phase 6 complete: Self-learning capability integrated
Production testing: Active in Swedish homes
Production code affecting real homes. Contributions welcome, quality standards apply:
- Read entire files before editing
- Use const.py for all thresholds
- Safety-first approach
- Black formatting (line length 100)
- Test safety-critical code
See .github/copilot-instructions.md for guidelines.
MIT License - See LICENSE file
Author: @enoch85
Built for the Swedish community, works globally.