From b336f6464b9718c9f2929d9f6996a46b27d06a1d Mon Sep 17 00:00:00 2001 From: andreas Date: Mon, 8 Dec 2025 21:44:38 +0100 Subject: [PATCH] Update README.md --- README.md | 81 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 5c1e552..ca07042 100644 --- a/README.md +++ b/README.md @@ -29,54 +29,77 @@ It is designed to ensure that the room's temperature, as reported by the TRVs, m --- -## 🧠 Logic Explained (The Calibration Formula) +Absolutely. I'll update the "Logic Explained (The Calibration Formula)" section of your README to reflect the more stable **Differential Calibration Method**. -The goal is to calculate a **New Offset** that makes the TRV's internal temperature sensor report the same value as the **External Sensor**. +Here is the revised section: -### 1. The Real Room Temperature +--- -The TRV's internal temperature sensor (`valve_temp`) is often biased due to its proximity to the hot radiator body. The valve attempts to correct this by applying its **Current Offset**. +## 🧠 Logic Explained (The Differential Calibration Method) -The valve's **Estimated Room Temperature** is: -$$\text{Valve Estimated Temp} = \text{Valve Internal Temp} - \text{Current Offset}$$ +The previous calibration method could lead to instability because it continuously compensated for the radiator's heat, even when the valve was actively heating. This revised approach uses a more stable method called **Differential Calibration**, focusing on calculating the temperature error only when the valve is in a **stable, idle state**. -### 2. The Correction Needed +The goal is to calculate a **New Offset** that makes the TRV's internal temperature sensor report the same value as the **External Sensor** when the heating is off. -The difference between the actual temperature and what the valve *thinks* the temperature is determines the needed **Raw Offset**. +### 1. The Stable Calibration Point (Crucial Guardrail) -$$\text{Required Offset} = \text{External Temp} - \text{Valve Estimated Temp}$$ +The calibration logic is **gated by a stability condition** to prevent incorrect adjustments caused by heat fluctuations. The blueprint **will only run the calculation and update** if: -Substituting the estimated temp: -$$\text{Required Offset} = \text{External Temp} - (\text{Valve Internal Temp} - \text{Current Offset})$$ +1. The valve's heating demand is **off** (i.e., `hvac_action` is not `'heating'`). +2. The TRV's setpoint (`target_temp`) is close to or below the external room temperature ($\text{Target Temp} - \text{External Temp} < 0.5^\circ\text{C}$). -This can be rearranged to: -$$\text{Required Offset} = (\text{External Temp} + \text{Current Offset}) - \text{Valve Internal Temp}$$ +This ensures we measure the TRV's internal sensor reading when it is least influenced by the active heat source. + +### 2. The Calibration Formula + +When the stability conditions are met, the formula calculates the **raw temperature error** between the external ground truth and the TRV's uncompensated sensor reading. This error becomes the new required offset. + +$$\text{Raw Offset Required} = \text{External Temp} - \text{Valve Internal Temp}$$ + +This simple formula ensures that if the $\text{External Temp}$ is $20.0^\circ\text{C}$ and the $\text{Valve Internal Temp}$ (being near the radiator) is $22.0^\circ\text{C}$, the $\text{Raw Offset Required}$ will be $-2.0^\circ\text{C}$. This negative offset corrects the valve's internal reading to match the room: $22.0 - (-2.0) = 24.0^\circ\text{C}$. ### 3. Final Calculation and Update -The blueprint applies the **Manual Correction** (bias) and the **Rounding Step** before setting the new value. +The blueprint then applies the **Manual Correction** (bias) and the **Rounding Step** before setting the new value. -$$\text{New Offset} = \text{Round}(\text{Required Offset} + \text{Manual Correction})$$ +$$\text{New Offset} = \text{Round}(\text{Raw Offset Required} + \text{Manual Correction})$$ -The logic sequence for each valve is: +The updated logic sequence for each valve is: -1. **Check Interval:** The automation is triggered by the **Run Interval** (e.g., every 10 minutes). -2. **Iterate:** It loops through every `climate` entity in the **Area**. -3. **Data Check:** It ensures the `climate` entity and its corresponding `number` offset entity are available. -4. **Calculate:** It computes the `new_offset` using the formula above. +1. **Check Interval:** Automation is triggered by the **Run Interval** (e.g., every 10 minutes). +2. **Iterate & Check:** Loops through all `climate` entities in the **Area** and checks for availability. +3. **Stability Gate:** It **skips** the valve if it is currently in the `'heating'` state or has a high setpoint. +4. **Calculate:** It computes the `new_offset` using the differential formula. 5. **Conditional Update:** It checks if the `New Offset` is different from the `Current Offset`. -6. **Update:** If they are different, it calls the `number.set_value` service to update the TRV's offset. +6. **Update:** If they are different, it calls the `number.set_value` service. ### ❓ What does the offset value mean? -* If the blueprint calculates a **Positive Offset** (e.g., $+1.5^\circ\text{C}$): - * This means the valve's internal sensor is reading **too hot** (e.g., $22^\circ\text{C}$) compared to the room ($20^\circ\text{C}$). - * The valve must apply a **positive offset** to make its reported temperature $22 - 1.5 = 20.5^\circ\text{C}$, aligning it with the external sensor. - -* If the blueprint calculates a **Negative Offset** (e.g., $-0.5^\circ\text{C}$): - * This means the valve's internal sensor is reading **too cold** (e.g., $19.5^\circ\text{C}$) compared to the room ($20^\circ\text{C}$). - * The valve must apply a **negative offset** to make its reported temperature $19.5 - (-0.5) = 20.0^\circ\text{C}$. +* If the blueprint calculates a **Positive Offset** (e.g., $+1.5^\circ\text{C}$): This indicates the valve's uncompensated sensor reading is currently **too cold** compared to the external sensor. +* If the blueprint calculates a **Negative Offset** (e.g., $-1.5^\circ\text{C}$): This indicates the valve's uncompensated sensor reading is currently **too hot** compared to the external sensor (the most common result). ## 🙏 Credits -Based on the original single-valve calibration blueprint, enhanced for multi-valve area support with robust error handling and automatic device discovery. \ No newline at end of file +The "Differential Calibration Method" is an approach derived from common practices and community solutions found within the Home Assistant and smart heating enthusiast communities, particularly those dealing with Zigbee or Z-Wave TRVs that exhibit the "heat soak" effect. + +Since this is a composite, community-driven solution rather than a single academic paper or proprietary product, relevant credits should acknowledge the community nature of the logic. + +Here are the relevant credits referencing the sources and conceptual foundation for this approach: + +--- + +## 📚 Credits and Sources for the Differential Calibration Method + +The logic presented in this blueprint is a synthesis of best practices developed and shared by the Home Assistant community. It addresses known challenges with Thermostatic Radiator Valves (TRVs) when using external room sensors for temperature compensation. + +### 1. Conceptual Foundation (The "Heat Soak" Problem) + +* **Source:** **Physics of TRV Placement and Temperature Gradients** +* **Credit:** The core concept addresses the **"heat soak" effect**, where a TRV's internal temperature sensor reports an artificially high temperature because it is mounted directly on the radiator. This physical limitation necessitates the use of an external temperature sensor and a mathematical offset. This issue is widely discussed in forums dedicated to smart heating and hydronics (e.g., r/HomeAssistant, r/smarthome, heating engineer blogs). + +### 2. Implementation Strategy (The Gating Condition) + +* **Source:** **Home Assistant Community Blueprints and Forums** +* **Credit:** The crucial implementation detail—using a **stability or "gating" condition** (checking if the `hvac_action` is not `'heating'`)—is a widely adopted strategy to ensure calibration only occurs when the valve's physical environment is stable. This technique prevents the calculation from running away (or "chasing the heat") by only measuring the offset when the valve is idle. Many community blueprints for generic TRV calibration employ similar logic to prevent oscillation. + +Since the final logic is a *revision* based on iterative community feedback and established programming guards, it stands as an **evolved community solution** rather than a citation of a single authoritative source. \ No newline at end of file