andreas/ha-thermostat-calibration
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README.md

Browse source
This commit is contained in:
Andreas Gammelgaard Damsbo 2025-12-08 21:44:38 +01:00
parent f59e0b9977
commit b336f6464b
1 changed files with 52 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
README.md
View file

@ -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: 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**.
$$\text{Valve Estimated Temp} = \text{Valve Internal Temp} - \text{Current Offset}$$
### 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: 1. The valve's heating demand is **off** (i.e., `hvac_action` is not `'heating'`).
$$\text{Required Offset} = \text{External Temp} - (\text{Valve Internal Temp} - \text{Current Offset})$$ 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: This ensures we measure the TRV's internal sensor reading when it is least influenced by the active heat source.
$$\text{Required Offset} = (\text{External Temp} + \text{Current Offset}) - \text{Valve Internal Temp}$$
### 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 ### 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). 1. **Check Interval:** Automation is triggered by the **Run Interval** (e.g., every 10 minutes).
2. **Iterate:** It loops through every `climate` entity in the **Area**. 2. **Iterate & Check:** Loops through all `climate` entities in the **Area** and checks for availability.
3. **Data Check:** It ensures the `climate` entity and its corresponding `number` offset entity are available. 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 formula above. 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`. 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? ### ❓ What does the offset value mean?
* If the blueprint calculates a **Positive Offset** (e.g., $+1.5^\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.
* 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}$). * 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).
* 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}$.
## 🙏 Credits ## 🙏 Credits
Based on the original single-valve calibration blueprint, enhanced for multi-valve area support with robust error handling and automatic device discovery. 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.