From 26e8744b590885b2de3377f73258d00cffb8b2e1 Mon Sep 17 00:00:00 2001 From: andreas Date: Sat, 6 Dec 2025 11:49:43 +0100 Subject: [PATCH] Update README.md --- README.md | 281 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 279 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2d23cef..480d38c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,280 @@ -# ha-thermostat-calibration +# Area Valve Temperature Offset Calibration Blueprint -Calibrate all thermostats in a given area based on an external temperature sensor \ No newline at end of file +Automatically calibrate all smart radiator valves (TRVs) in a room using a single external 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! 🎉 + +--- + +## 📋 Prerequisites + +### 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) + +--- + +## 🚀 Installation + +### 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** + +--- + +## ⚙️ Configuration + +### Required Settings + +| Setting | Description | Example | +|---------|-------------|---------| +| **Area** | The room containing your valves | `Living Room` | +| **External Temperature Sensor** | Your accurate room thermometer | `sensor.living_room_temperature` | + +### Optional Settings (Recommended Defaults) + +| 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) | + +### Understanding Manual Correction + +After the blueprint runs for a day, you might notice: + +- **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 + +Start with **0.0°C** and adjust in small steps (0.1-0.2°C increments). + +--- + +## 📝 Complete Setup Example + +### Scenario: Living Room with 3 Radiators + +**Equipment:** +- 3x Hama smart radiator valves +- 1x Aqara temperature sensor (on the wall, away from radiators) +- All assigned to "Living Room" area + +**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 +``` + +**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! + +--- + +## 🔍 Troubleshooting + +### 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! + +--- + +## 🙏 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