fix: correct non-linear volume flow mapping for energy recovery

Author: thengeroff

.agent/workflows/release.md

@@ -13,7 +13,8 @@ Wenn dieser Workflow aufgerufen wird, führst du als KI-Assistent vollautomatisc
 2. **CHANGELOG.md analysieren (Ressourcenschonend):**
    Nutze das Terminal (`run_command`), um mit `tail -n 80 CHANGELOG.md` ausschließlich die letzten 80 Zeilen der Changelog-Datei zu lesen. **Lies auf keinen Fall die komplette Datei ein**, um Tokens zu sparen. Verstehe anhand des Ausschnitts das gewünschte Format.
 3. **Dateien aktualisieren:**
-   *   **version.json**: Erstelle einen sehr kurzen, prägnanten englischen Satz (ca. 5-12 Wörter). Überschreibe damit den Wert des `"description"`-Feldes in `version.json`. **WICHTIG: Erhöhe NICHT den Wert für "version". Der Version-Bump geschieht automatisch beim Build!**
+   *   **version.json**: Erstelle einen sehr kurzen, prägnanten englischen Satz (ca. 5-12 Wörter). Überschreibe damit den Wert des `"project_description"`-Feldes in `version.json`.
+       **⚠️ KRITISCHE REGEL:** Erhöhe **NIEMALS** manuell den Wert für `"project_version"` in der Datei, auch wenn der User dich im aktuellen Prompt dazu auffordert. Der Version-Bump geschieht **vollautomatisch** durch das Pre-Compile-Skript (`version_bump.py`) während des ESPHome-Builds. Ein manuelles Erhöhen führt zu einer fehlerhaften "doppelten" Erhöhung (Double Bump). Falls der User nach einer bestimmten Zielversion fragt, stelle sicher, dass die `version.json` auf dem Stand **vor** dieser Version bleibt.
    *   **CHANGELOG.md**: Schreibe einen **ausführlichen, detaillierten** Changelog-Eintrag zu deinen analysierten Code-Änderungen (so detailliert wie bisher auch). Leite für den Titel des Eintrags (z.B. `## [0.8.252] - YYYY-MM-DD`) die *nächste* Versionsnummer ab, indem du die Patch-Version aus der `version.json` im Kopf um 1 erhöhst. Füge diesen Eintrag oben an der passenden Stelle in der `CHANGELOG.md` ein.
 4. **Kompilierung & Git Push:**
    Generiere eine kurze, passende englische Commit-Nachricht für die Code-Änderungen (z.B. `feat: ...` oder `fix: ...`).

CHANGELOG.md

@@ -5,6 +5,17 @@ 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.9] - 2026-05-16
+
+### Fixed
+- **Volumenstrom-Schätzung**: Korrektur der bisherigen linearen Heuristik (4,5 m³/h pro Stufe). Diese wurde durch eine präzise, nicht-lineare Lookup-Tabelle ersetzt, welche die 10 benutzerdefinierten Lüfterstufen auf die realen Herstellerdaten des Ventomaxx v-wrg-1 (17–43 m³/h) abbildet. Dies stellt die physikalische Korrektheit der berechneten Wattstunden (Wh) sicher.
+
+### Added
+- **Technische Dokumentation (v0.9.9)**: Ergänzung der Readme-Dateien um wichtige technische Details: NVS-Flash-Schutz (8h-Speicherintervall), LED-Selbsttest beim Booten und die NTC-Fallback-Logik (NaN bei Sensorausfall).
+
+### Changed
+- **Energie-Integration**: Verfeinerung der HRV-Integrator-Logik. Die Berechnung der zurückgewonnenen thermischen Energie nutzt nun die realen Volumenstromwerte der jeweiligen Lüfterstufe für ein exaktes energetisches Abbild.
+
 ## [0.9.8] - 2026-05-15
 
 ### Fixed

Readme.md

@@ -760,6 +760,9 @@ $$
 **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.
 
+**Recovered Thermal Energy (Wh):**
+In addition to the percentage efficiency, the system calculates the actual recovered thermal energy in **Watt-hours (Wh)**. This is achieved by a non-linear mapping of the 10 fan levels to the real volumetric flow rates of the Ventomaxx v-wrg-1 (ranging from approx. 17 m³/h at level 1 up to 43 m³/h at level 10) and integrating the actual temperature difference ($T_{supply} - T_{outside}$) over time. This allows you to track exactly how much heating energy (or cooling energy in summer) the system has "saved" during each cycle.
+
 **Interpretation:**
 
 - **> 70%:** Excellent heat recovery
@@ -920,6 +923,9 @@ To ensure 24/7 reliability and premium performance on the ESP32-C6, the firmware
   - ✅ **Unified Control Authority**: Centralized intensity calculation (`evaluate_auto_mode`) to eliminate race conditions between independent update intervals.
   - ✅ **Smart Group Sync**: Automatic propagation of modes and configurations across peer devices via ESP-NOW with built-in loop prevention.
   - ✅ **Config Safety**: Added validation for min/max fan levels (swap-guard) to prevent inverted scaling on UI misconfiguration.
+  - ✅ **NVS Wear Protection**: Write access to the internal flash memory is minimized by buffering non-critical data like filter operating hours and writing them only once every 8 hours (3x per day) to maximize memory longevity.
+  - ✅ **LED Self-Test**: During the boot sequence, the system performs a 3-second hardware check by forcing all LEDs to 100% brightness, ensuring visual feedback reliability before restoring user settings.
+  - ✅ **NTC Fallback**: If an NTC sensor is disconnected or faulty (reporting values around 87°C), the system automatically declares the state as `NaN` (Unknown). This prevents invalid efficiency calculations and ensures clean status data in Home Assistant.
 
 #### **4. 🏁 System Boot Flow**
 

Readme_de.md

@@ -730,6 +730,9 @@ $$
 **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.
 
+**Zurückgewonnene thermische Energie (Wh):**
+Zusätzlich zur prozentualen Effizienz berechnet das System die tatsächlich zurückgewonnene thermische Energie in **Wattstunden (Wh)**. Dies erfolgt durch ein nicht-lineares Mapping der 10 Lüfterstufen auf die realen Volumenströme des Ventomaxx v-wrg-1 (von ca. 17 m³/h auf Stufe 1 bis zu 43 m³/h auf Stufe 10) und der Integration der tatsächlichen Temperaturdifferenz ($T_{Zuluft} - T_{Außen}$) über die Zeit. So lässt sich genau nachvollziehen, wie viel Heizenergie (oder Kühlenergie im Sommer) das System pro Zyklus "eingespart" hat.
+
 **Interpretation:**
 
 - **> 70%:** Ausgezeichnete Wärmerückgewinnung
@@ -889,6 +892,9 @@ Um eine 24/7-Zuverlässigkeit und Premium-Performance auf dem ESP32-C6 zu gewäh
   - ✅ **Einheitliche Steuerungsautorität**: Zentralisierung der Intensitätsberechnung (`evaluate_auto_mode`), um Race-Conditions zwischen unabhängigen Update-Intervallen zu eliminieren.
   - ✅ **Smart Group Sync**: Automatische Übertragung von Modi und Konfigurationen an alle Geräte im Raum via ESP-NOW mit integrierter Loop-Prevention.
   - ✅ **Konfigurations-Sicherheit**: Validierung von Min/Max-Lüfterstufen (Swap-Guard) zur Vermeidung von invertierter Skalierung bei Fehlkonfigurationen.
+  - ✅ **NVS-Verschleißschutz**: Schreibzugriffe auf den internen Flash-Speicher werden minimiert, indem nicht-kritische Daten wie die Filter-Betriebsstunden gepuffert und nur alle 8 Stunden (3x pro Tag) festgeschrieben werden.
+  - ✅ **LED-Selbsttest**: Beim Systemstart führt das Gerät einen 3-sekündigen Hardware-Check durch, bei dem alle LEDs auf 100% Helligkeit gezwungen werden, um die visuelle Rückmeldung zu verifizieren.
+  - ✅ **NTC-Fallback**: Bei nicht angeschlossenen oder defekten NTC-Sensoren (Werte um 87°C) deklariert das System den Status automatisch als `NaN` (Unknown). Dies verhindert ungültige Effizienzberechnungen und sorgt für saubere Sensordaten in Home Assistant.
 
 
 

manifest_example.json

@@ -1,11 +1,11 @@
 {
   "name": "thomasengeroff.ventosync",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "builds": [
     {
       "chipFamily": "ESP32-C6",
       "ota": {
-        "md5": "bcdcc784c1c821f42e8ffc21bcbcf3b0",
+        "md5": "0ce3fe1442412fcb595fad14e4fb0976",
         "path": "firmware.bin",
         "summary": "OTA update check frequency set to 15 minutes"
       }

packages/sensors/sensor_hrv_efficiency.yaml

@@ -12,6 +12,7 @@ sensor:
   - platform: template
     name: "WRG Effizienz (Zyklus)"
     id: hrv_efficiency_cycle
+    internal: ${hide_ntc_sensors}
     unit_of_measurement: "%"
     accuracy_decimals: 1
     icon: "mdi:heat-wave"
@@ -25,6 +26,7 @@ sensor:
   - platform: template
     name: "WRG Effizienz"
     id: heat_recovery_efficiency
+    internal: ${hide_ntc_sensors}
     unit_of_measurement: "%"
     accuracy_decimals: 1
     icon: "mdi:heat-wave"
@@ -41,6 +43,7 @@ sensor:
   - platform: template
     name: "WRG Energie (Zyklus)"
     id: hrv_energy_cycle
+    internal: ${hide_ntc_sensors}
     unit_of_measurement: "Wh"
     accuracy_decimals: 2
     icon: "mdi:lightning-bolt"
@@ -65,10 +68,24 @@ interval:
           
           if (last_was_supply && !is_supply) {
             // Zuluft-Phase ist gerade beendet → Zyklus finalisieren
-            // Estimate volume flow (approx. 4.5 m³/h per fan level, max 45 m³/h)
+            // Estimate volume flow based on manufacturer data for Ventomaxx v-wrg-1
+            // Mapping 10 custom levels to the 5 original stages (17, 21, 24, 34, 43 m³/h)
             float flow_m3h = 0.0f;
             if (id(ventilation_ctrl) != nullptr) {
-              flow_m3h = id(ventilation_ctrl)->current_fan_intensity * 4.5f;
+              int level = id(ventilation_ctrl)->current_fan_intensity;
+              switch (level) {
+                case 1:  flow_m3h = 17.0f; break;
+                case 2:  flow_m3h = 18.0f; break;
+                case 3:  flow_m3h = 20.0f; break;
+                case 4:  flow_m3h = 21.0f; break;
+                case 5:  flow_m3h = 22.5f; break;
+                case 6:  flow_m3h = 24.0f; break;
+                case 7:  flow_m3h = 29.0f; break;
+                case 8:  flow_m3h = 34.0f; break;
+                case 9:  flow_m3h = 38.5f; break;
+                case 10: flow_m3h = 43.0f; break;
+                default: flow_m3h = 0.0f;  break;
+              }
             }
             auto result = ventosync::hrv::get_calculator().finalize_cycle(flow_m3h);
             

version.json

@@ -1,5 +1,5 @@
 {
-    "project_version": "0.9.8",
-    "project_date": "2026-05-14",
-    "project_description": "Fix HRV efficiency sensor mapping and implement volume flow estimation for energy recovery."
+    "project_version": "0.9.9",
+    "project_date": "2026-05-16",
+    "project_description": "Implement precise non-linear volume flow mapping for accurate energy recovery."
 }