feat: add energy-based trapezoidal HRV efficiency and fix NTC redundancy labels

Author: thengeroff

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.4] - 2026-05-15
+
+### Added
+- **Energiebasierte WRG-Effizienz**: Die Berechnung der Wärmerückgewinnung nutzt nun eine numerische Trapez-Integration über den gesamten Luftzyklus (gemäß DIN EN 13141-8). Dies löst das Problem mathematisch instabiler "Live"-Werte bei geringen Temperaturdifferenzen in der Übergangszeit und liefert ein echtes physikalisches Abbild der zurückgewonnenen Energie.
+
+### Fixed
+- **NTC Sensor-Dokumentation**: Korrektur der vertauschten Sensor-Beschreibungen in den Readme-Dateien (Indoor/Outdoor Mapping) zur Vermeidung von Missverständnissen bei der Verkabelung.
+- **C++ Namespace Konflikt**: Behebung des Fehlers `ventosync was not declared in this scope` beim Firmware-Build. Die globale Instanziierung des HRV-Rechners über ESPHomes `globals` wurde auf ein natives und threadsicheres C++ Singleton-Pattern (`get_calculator()`) umgestellt.
+
 ## [0.9.1] - 2026-05-14
 
 ### Fixed

Readme.md

@@ -731,44 +731,40 @@ Exterior → Ceramic heat exchanger → Interior (pre-heated)
 ### NTC Sensors (Temperature Stabilization)
 
 The NTC sensors measure the temperature at the ceramic heat exchanger inside and outside (`temp_zuluft` and `temp_abluft`). Since the fan direction in heat recovery mode changes cyclically (e.g., every 70 seconds), the sensors require a certain amount of time due to their thermal mass to adapt to the new air temperature. To make the measurement as accurate as possible, very small NTC sensors are used with the lowest possible mass and high accuracy. This makes the adaptation to the changing temperature, depending on the ventilation direction, as fast and precise as possible.
-To avoid incorrect intermediate values in Home Assistant, both sensors use **intelligent temperature stabilization**:
+To avoid incorrect intermediate values in Home Assistant and to accurately capture the true thermal limits, both sensors use **intelligent, season-aware temperature stabilization**:
 
-- After a change of direction (Push/Pull), measurement value transmission is paused for **40% of the cycle duration (min. 15s)** (which corresponds to approx. 25-30s).
-- Then the system collects measured values in a **30-second sliding window**.
-- Only when the fluctuation within this window falls to a realistic **0.3 °C** or less is the value considered stable and updated.
+- After a change of direction (Push/Pull), measurement value transmission is paused for **40% of the cycle duration (min. 15s)**.
+- Then the system collects measured values in a **sliding window (size 3)**.
+- **Dynamic Min/Max Selection:** Instead of simple averaging, the system dynamically selects the `min` or `max` value from the window to compensate for thermal inertia of the housing. 
+  - **Winter/Transition:** The outdoor sensor takes the minimum value (true cold outside air), and the indoor sensor takes the maximum value (true warm room air).
+  - **Summer Cooling:** When the outside air is hotter than the inside air, the logic automatically reverses (outdoor takes max, indoor takes min) to avoid false readings from the cooler/warmer housing.
 
-*Note on redundancy:* `temp_abluft` provides the actual outside temperature when the airflow is directed inward. `temp_zuluft` provides the room temperature when the airflow is directed outward and serves as redundancy for the more precise SCD41 sensor.
+*Note on redundancy:* `temp_zuluft` (Outdoor NTC) provides the actual outside temperature when the airflow is directed inward. `temp_abluft` (Indoor NTC) provides the room temperature when the airflow is directed outward and serves as redundancy for the more precise SCD41 sensor.
 
 Specifically, the following sensor is used:
 
 | Manufacturer | Part Number | Source | Accuracy | Data Sheet |
 | :--- | :--- | :--- | :--- | :--- |
 | **VARIOHM** | `ENTC-EI-10K9777-02` | [Reichelt Elektronik](https://www.reichelt.de/de/de/shop/produkt/thermistor_NTC_-40_bis_125_c-350474) | ± 0.2 °C | [PDF](EasyEDA-Pro/components/NTC_ENTC_EI-10K9777-02.pdf) |
 
-### Efficiency Calculation
+### Efficiency Calculation (Energy-Based)
 
-At the end of the supply air phase, the heat recovery is calculated:
+The true heat recovery efficiency of a ceramic regenerator over a complete cycle is energy-based, not based on instantaneous temperatures (according to DIN EN 13141-8). 
+
+At the end of the supply air phase, the system calculates the efficiency using **numerical trapezoidal integration** over the entire phase duration:
 
 $$
-	ext{Efficiency} = \frac{T_{\text{Supply}} - T_{\text{Outside}}}{T_{\text{Room}} - T_{\text{Outside}}} \times 100\%
+	\eta_{WRG} = \frac{\int (\text{T}_{Supply} - \text{T}_{Outside}) dt}{\int (\text{T}_{Room} - \text{T}_{Outside}) dt}
 $$
 
-**Example calculation:**
-
-- Room temperature: 21°C
-- Outside temperature: 5°C
-- Supply temperature: 16°C
-
-$$
-	ext{Efficiency} = \frac{16°C - 5°C}{21°C - 5°C} \times 100\% = \frac{11°C}{16°C} \times 100\% = 68.75\%
-$$,
-0
+**Why this is mathematically superior:**
+If the efficiency was calculated as a simple average of instantaneous point-in-time efficiencies, it would become highly inaccurate and numerically unstable (exploding values) when the temperature difference ($\Delta T$) is very small (e.g., during the transition seasons). By integrating the temperature deltas over time, the calculation remains physically accurate, stable, and provides a true representation of the thermal energy recovered during the cycle.
 
 **Interpretation:**
 
 - **> 70%:** Excellent heat recovery
 - **50-70%:** Good heat recovery
-- **< 50%:** Ceramic too cold or cycle too short
+- **< 50%:** Ceramic too cold, cycle too short, or temperature difference too small
 
 ### Optimizing Efficiency
 

Readme_de.md

@@ -701,43 +701,40 @@ Außen → Keramikspeicher → Innenraum (vorgewärmt)
 ### NTC Sensoren (Temperatur-Stabilisierung)
 
 Die NTC Sensoren messen die Temperatur am Keramikspeicher innen und außen (`temp_zuluft` und `temp_abluft`). Da die Lüfterrichtung im Wärmerückgewinnungs-Modus zyklisch (z.B. alle 70 Sekunden) wechselt, benötigen die Sensoren aufgrund ihrer thermischen Masse eine gewisse Zeit, um sich an die neue Lufttemperatur anzupassen. Um die Messung möglichst genau zu machen, werden sehr kleine NTC Sensoren genutzt, mit möglichst geringer Masse und hoher Genauigkeit. Dadurch wird die Anpassung an die wechselnde Temperatur je nach Lüftungsrichtung möglichst schnell und präzise.
-Um fehlerhafte Zwischenwerte in Home Assistant zu vermeiden, nutzen beide Sensoren eine **intelligente Temperatur-Stabilisierung**:
+Um fehlerhafte Zwischenwerte in Home Assistant zu vermeiden und die wahren thermischen Grenzwerte exakt zu erfassen, nutzen beide Sensoren eine **intelligente, saisonabhängige Temperatur-Stabilisierung**:
 
-- Nach einem Richtungswechsel (Push/Pull) wird die Messwertübertragung für **40% der Zyklusdauer (min. 15s)** pausiert (was ca. 25-30s entspricht).
-- Danach sammelt das System Messwerte in einem **30-Sekunden Sliding-Window**.
-- Erst wenn die Schwankung innerhalb dieses Fensters auf realistische **0,3 °C** oder weniger fällt, gilt der Wert als stabil und wird aktualisiert.
+- Nach einem Richtungswechsel (Push/Pull) wird die Messwertübertragung für **40% der Zyklusdauer (min. 15s)** pausiert.
+- Danach sammelt das System Messwerte in einem **Sliding-Window (Größe 3)**.
+- **Dynamische Min/Max-Auswahl:** Anstelle einer simplen Durchschnittsbildung wählt das System dynamisch den `min` oder `max` Wert aus dem Fenster, um die thermische Trägheit des Gehäuses zu kompensieren.
+  - **Winter/Übergangszeit:** Der Außensensor nimmt den Minimalwert (wahre kalte Außenluft), der Innensensor den Maximalwert (wahre warme Raumluft).
+  - **Sommer-Kühlung:** Wenn die Außenluft heißer ist als die Innenluft, kehrt sich die Logik automatisch um (Außen nimmt Max, Innen nimmt Min), um verfälschte Werte durch das kühlere/wärmere Gehäuse zu vermeiden.
 
-*Hinweis zur Redundanz:* `temp_abluft` liefert bei nach innen gerichtetem Luftstrom die tatsächliche Außentemperatur. `temp_zuluft` liefert bei nach außen gerichtetem Luftstrom die Raumtemperatur und dient als Redundanz zum präziseren SCD41 Sensor.
+*Hinweis zur Redundanz:* `temp_zuluft` (Außen-NTC) liefert bei nach innen gerichtetem Luftstrom die tatsächliche Außentemperatur. `temp_abluft` (Innen-NTC) liefert bei nach außen gerichtetem Luftstrom die Raumtemperatur und dient als Redundanz zum präziseren SCD41 Sensor.
 
 Konkret wird der folgende Sensor verwendet:
 
 | Hersteller | Artikelnummer | Bezugsquelle | Genauigkeit | Datenblatt |
 | :--- | :--- | :--- | :--- | :--- |
 | **VARIOHM** | `ENTC-EI-10K9777-02` | [Reichelt Elektronik](https://www.reichelt.de/de/de/shop/produkt/thermistor_ntc_-40_bis_125_c-350474) | ± 0,2 °C | [PDF](EasyEDA-Pro/components/NTC_ENTC_EI-10K9777-02.pdf) |
 
-### Effizienzberechnung
+### Effizienzberechnung (Energiebasiert)
 
-Am Ende der Zuluft-Phase wird die Wärmerückgewinnung berechnet:
+Die wahre Wärmerückgewinnungseffizienz eines Keramikspeichers über einen vollständigen Zyklus ist energiebasiert, nicht basierend auf punktuellen Temperaturen (gemäß DIN EN 13141-8).
 
-$$
-\text{Effizienz} = \frac{T_{\text{Zuluft}} - T_{\text{Außen}}}{T_{\text{Raum}} - T_{\text{Außen}}} \times 100\%
-$$
-
-**Beispielrechnung:**
-
-- Raumtemperatur: 21°C
-- Außentemperatur: 5°C
-- Zulufttemperatur: 16°C
+Am Ende der Zuluft-Phase berechnet das System die Effizienz mittels **numerischer Trapez-Integration** über die gesamte Phasendauer:
 
 $$
-\text{Effizienz} = \frac{16°C - 5°C}{21°C - 5°C} \times 100\% = \frac{11°C}{16°C} \times 100\% = 68.75\%
+\eta_{WRG} = \frac{\int (\text{T}_{Zuluft} - \text{T}_{Außen}) dt}{\int (\text{T}_{Raum} - \text{T}_{Außen}) dt}
 $$
 
+**Warum das mathematisch überlegen ist:**
+Würde man die Effizienz als simplen Durchschnitt der momentanen Effizienzwerte berechnen, würde der Wert bei sehr kleinen Temperaturunterschieden ($\Delta T$) extrem ungenau und numerisch instabil werden (explodierende Werte) – etwa in der Übergangszeit. Durch die Integration der Temperaturdifferenzen über die Zeit bleibt die Berechnung physikalisch korrekt, stabil und liefert ein echtes Abbild der während des Zyklus zurückgewonnenen Wärmeenergie.
+
 **Interpretation:**
 
 - **> 70%:** Ausgezeichnete Wärmerückgewinnung
 - **50-70%:** Gute Wärmerückgewinnung
-- **< 50%:** Keramik zu kalt oder Zyklus zu kurz
+- **< 50%:** Keramik zu kalt, Zyklus zu kurz oder Temperaturdifferenz zu gering
 
 ### Optimierung der Effizienz