ha-thermostat-calibration/README.md

## 🏠 Home Assistant Blueprint: Area Valve Temperature Offset Calibration

This blueprint automatically calibrates the temperature offset of all smart radiator valves (TRVs) within a specified Home Assistant **Area** using readings from a single, accurate external room temperature sensor.

It is designed to ensure that the room's temperature, as reported by the TRVs, matches the temperature measured by the external sensor, thereby making the valves' heating behavior consistent with the actual room conditions.

---

## 🚀 Key Features

* **Area-Based Discovery:** Automatically finds all `climate` entities within the chosen Home Assistant Area.
* **Targeted Calibration:** Identifies and updates the specific `number` entity (the temperature offset) for each TRV's device.
* **Scheduled Execution:** Runs on a defined time interval (e.g., every 10 minutes) for predictable, non-reactive calibration.
* **Efficient Operation:** Only writes a new offset value to a TRV if the calculated offset differs from its current setting, minimizing unnecessary network traffic.
* **Manual Bias:** Allows for a **Manual Correction** (bias) to fine-tune valve behavior, accommodating physical installation issues.

---

## ⚙️ Blueprint Configuration

| Input Field | Description | Example Value |
| :--- | :--- | :--- |
| **Area** | The Home Assistant Area containing the TRVs to be calibrated. | `Living Room` |
| **External temperature sensor** | The reliable sensor that measures the true ambient temperature for the area. | `sensor.living_room_temperature` |
| **Run Interval** | How often the calibration should run, using a Time Pattern string. | `/10` (every 10 minutes) |
| **Rounding step for offset value** | The precision of your TRVs' offset setting (e.g., 0.5 or 1.0). | `0.5` |
| **Manual correction (bias)** | A fixed value added to the final calculated offset. Use to prevent slight overheating/underheating. | `+0.2` (makes valves assume it's warmer) |
| **Offset entity suffix pattern** | The pattern used to find the offset entity (e.g., `_local_temperature_offset`). Only change if necessary. | `_local_temperature_offset` |

---

## 🧠 Logic Explained (The Calibration Formula)

The goal is to calculate a **New Offset** that makes the TRV's internal temperature sensor report the same value as the **External Sensor**.

### 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**.

The valve's **Estimated Room Temperature** is:
$$\text{Valve Estimated Temp} = \text{Valve Internal Temp} - \text{Current Offset}$$

### 2. The Correction Needed

The difference between the actual temperature and what the valve *thinks* the temperature is determines the needed **Raw Offset**.

$$\text{Required Offset} = \text{External Temp} - \text{Valve Estimated Temp}$$

Substituting the estimated temp:
$$\text{Required Offset} = \text{External Temp} - (\text{Valve Internal Temp} - \text{Current Offset})$$

This can be rearranged to:
$$\text{Required Offset} = (\text{External Temp} + \text{Current Offset}) - \text{Valve Internal Temp}$$

### 3. Final Calculation and Update

The blueprint 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})$$

The 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.
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.

### ❓ 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}$.

## 🙏 Credits

Based on the original single-valve calibration blueprint, enhanced for multi-valve area support with robust error handling and automatic device discovery.