diff --git a/README.md b/README.md index 480d38c..5c1e552 100644 --- a/README.md +++ b/README.md @@ -1,279 +1,81 @@ -# Area Valve Temperature Offset Calibration Blueprint +## 🏠 Home Assistant Blueprint: Area Valve Temperature Offset Calibration -Automatically calibrate all smart radiator valves (TRVs) in a room using a single external temperature sensor. +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. -## 🎯 What This Does - -Smart radiator valves have internal temperature sensors, but these are often inaccurate because they're mounted directly on the radiator. This blueprint: - -- **Discovers all thermostats** in a chosen area (e.g., "Living Room") -- **Compares** each valve's internal reading to your accurate external sensor -- **Calculates and applies** the correct temperature offset automatically -- **Skips** any thermostats that don't support offset calibration -- **Updates continuously** to maintain accuracy over time - -### Real-World Example -- Your external sensor reads: **21.0°C** (accurate) -- Valve's internal sensor reads: **23.5°C** (too high, near the radiator) -- Blueprint calculates offset: **-2.5°C** -- Result: Valve now "sees" 21.0°C and heats correctly! 🎉 +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. --- -## 📋 Prerequisites +## 🚀 Key Features -### What You Need - -1. **Smart Radiator Valves** with temperature offset support - - Common brands: Hama, Aqara, Tuya, Zigbee TRVs, Z-Wave TRVs - - Must expose a `number` entity for temperature offset (usually named `*_temperature_offset` or `*_local_temperature_offset`) - -2. **External Temperature Sensor** in the room - - Should be accurate and away from radiators - - Examples: Aqara sensor, Xiaomi sensor, ESP32 sensor, Zigbee temp sensor - -3. **Home Assistant** with areas configured - - Your valves and sensors must be assigned to areas (Settings → Areas & Zones) +* **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. --- -## 🚀 Installation +## ⚙️ Blueprint Configuration -### Step 1: Import the Blueprint - -**Option A: Via URL (Easiest)** -1. Copy the blueprint URL from GitHub -2. Go to **Settings** → **Automations & Scenes** → **Blueprints** -3. Click **Import Blueprint** -4. Paste the URL and click **Preview** → **Import** - -**Option B: Manual** -1. Copy the entire blueprint YAML code -2. Create a new file: `config/blueprints/automation/area_valve_calibration/calibration.yaml` -3. Paste the code and save -4. Restart Home Assistant or reload automations - -### Step 2: Create an Automation - -1. Go to **Settings** → **Automations & Scenes** -2. Click **Create Automation** → **Use Blueprint** -3. Select **Area Valve Temperature Offset Calibration** +| 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` | --- -## ⚙️ Configuration +## 🧠 Logic Explained (The Calibration Formula) -### Required Settings +The goal is to calculate a **New Offset** that makes the TRV's internal temperature sensor report the same value as the **External Sensor**. -| Setting | Description | Example | -|---------|-------------|---------| -| **Area** | The room containing your valves | `Living Room` | -| **External Temperature Sensor** | Your accurate room thermometer | `sensor.living_room_temperature` | +### 1. The Real Room Temperature -### Optional Settings (Recommended Defaults) +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**. -| Setting | Default | Description | -|---------|---------|-------------| -| **Minimum Time Between Updates** | 300 seconds | How often to recalibrate (prevents excessive updates) | -| **Rounding Step** | 1.0°C | Offset precision (use 0.5 for half-degree support) | -| **Manual Correction** | 0.0°C | Fine-tune if valves over/under-heat | -| **Offset Entity Suffix** | `temperature_offset` | Pattern to find offset entities (rarely needs changing) | +The valve's **Estimated Room Temperature** is: +$$\text{Valve Estimated Temp} = \text{Valve Internal Temp} - \text{Current Offset}$$ -### Understanding Manual Correction +### 2. The Correction Needed -After the blueprint runs for a day, you might notice: +The difference between the actual temperature and what the valve *thinks* the temperature is determines the needed **Raw Offset**. -- **Room too warm?** Set manual correction to **+0.2°C to +0.5°C** - - Makes valves think it's warmer → they heat less - -- **Room too cold?** Set manual correction to **-0.2°C to -0.5°C** - - Makes valves think it's cooler → they heat more +$$\text{Required Offset} = \text{External Temp} - \text{Valve Estimated Temp}$$ -Start with **0.0°C** and adjust in small steps (0.1-0.2°C increments). +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}$$ -## 📝 Complete Setup Example +### 3. Final Calculation and Update -### Scenario: Living Room with 3 Radiators +The blueprint applies the **Manual Correction** (bias) and the **Rounding Step** before setting the new value. -**Equipment:** -- 3x Hama smart radiator valves -- 1x Aqara temperature sensor (on the wall, away from radiators) -- All assigned to "Living Room" area +$$\text{New Offset} = \text{Round}(\text{Required Offset} + \text{Manual Correction})$$ -**Configuration:** -```yaml -Area: Living Room -External Sensor: sensor.aqara_living_room_temperature -Min Interval: 300 -Rounding Step: 1.0 -Manual Correction: 0.0 -Offset Suffix: temperature_offset -``` +The logic sequence for each valve is: -**What Happens:** -1. Blueprint discovers all 3 climate entities in Living Room -2. For each valve, it finds the matching `number.*_temperature_offset` entity -3. Every 5 minutes (when sensors update), it: - - Reads Aqara sensor: 20.5°C - - Reads valve 1 internal: 23.0°C → calculates offset: -2.5°C → applies - - Reads valve 2 internal: 22.5°C → calculates offset: -2.0°C → applies - - Reads valve 3 internal: 24.0°C → calculates offset: -3.5°C → applies -4. All valves now heat to maintain accurate 20.5°C room temperature! +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? -## 🔍 Troubleshooting +* 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. -### Problem: Automation doesn't trigger - -**Check:** -- ✅ External sensor is updating (check state history) -- ✅ At least 5 minutes passed since last trigger (min_interval) -- ✅ Climate entities have `current_temperature` attribute - -**Fix:** Look at automation traces (Settings → Automations → [Your Automation] → Traces) - -### Problem: Some valves aren't calibrated - -**Check:** -- ✅ Valve is assigned to the correct area -- ✅ Valve has a `number.*_temperature_offset` entity -- ✅ Offset entity is available (not "unavailable" or "unknown") - -**Fix:** -- Go to Developer Tools → States -- Search for your valve's entities -- Confirm the `number` entity exists and matches the suffix pattern - -### Problem: Offsets keep changing wildly - -**Likely causes:** -- External sensor is near a heat source (window, door) -- Min interval is too short (increase to 600+ seconds) -- Valve readings are unstable - -**Fix:** -- Move external sensor to a neutral location -- Increase minimum interval to 600-900 seconds -- Wait 24 hours for system to stabilize - -### Problem: Room still too warm/cold after calibration - -**Solution:** Use manual correction -- Too warm: Set to +0.3°C, wait 12 hours, adjust if needed -- Too cold: Set to -0.3°C, wait 12 hours, adjust if needed - ---- - -## 🧪 Testing Your Setup - -### Quick Test (5 minutes) - -1. **Check current readings:** - - Note your external sensor: e.g., 21.0°C - - Note each valve's reading: e.g., 23.5°C, 22.8°C, etc. - -2. **Trigger the automation manually:** - - Go to Settings → Automations → [Your Automation] - - Click **Run** (top right) - -3. **Verify offsets updated:** - - Go to Developer Tools → States - - Search for `number.*_temperature_offset` - - Check values changed to match your calculation - -4. **Wait 30 minutes:** - - Check if valves now report temperatures closer to external sensor - - (Internal sensors won't match exactly, but should be closer) - ---- - -## 💡 Tips for Best Results - -### Sensor Placement -- **External sensor:** Mount on interior wall, chest height, away from radiators, windows, and doors -- **Avoid:** Direct sunlight, drafts, near electronics that generate heat - -### Valve Behavior -- **New installations:** Allow 48 hours for initial calibration to settle -- **Seasonal changes:** Offsets may need minor adjustments when outdoor temperature changes drastically -- **Battery levels:** Low batteries can cause erratic valve behavior - -### Optimization -- Start with default settings (300s interval, 1.0°C rounding, 0.0 manual correction) -- Monitor for 24-48 hours before making adjustments -- Change only one setting at a time to isolate effects -- Document your changes and results - ---- - -## 🔧 Advanced: Multiple Rooms - -Create **one automation per room**: - -**Living Room:** -- Area: Living Room -- Sensor: sensor.living_room_temp - -**Bedroom:** -- Area: Bedroom -- Sensor: sensor.bedroom_temp - -**Kitchen:** -- Area: Kitchen -- Sensor: sensor.kitchen_temp - -Each automation independently manages its area's valves. - ---- - -## 📊 How the Math Works - -``` -New Offset = External Temp - (Valve Temp - Current Offset) + Manual Correction -``` - -**Example:** -- External sensor: 21.0°C -- Valve reads: 23.5°C -- Current offset: 0°C -- Manual correction: 0°C - -**Calculation:** -``` -New Offset = 21.0 - (23.5 - 0) + 0 - = 21.0 - 23.5 - = -2.5°C -``` - -**Result:** Valve will subtract 2.5°C from its reading, so it "sees" 21.0°C - ---- - -## 🆘 Support - -### Getting Help -1. Check automation traces for errors -2. Review Home Assistant logs (Settings → System → Logs) -3. Post in Home Assistant Community forums with: - - Your configuration - - Automation trace screenshots - - Error messages from logs - -### Common Log Messages -- `"Skipping entity X: no offset entity found"` → Normal for thermostats without offset support -- `"Entity unavailable"` → Device offline or not responding -- `"Rate limited"` → Too many updates, increase min_interval - ---- - -## 📜 License - -This blueprint is provided as-is under MIT License. Feel free to modify and share! - ---- +* 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