ha-thermostat-calibration/README.md

# Area Valve Temperature Offset Calibration Blueprint

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.