# Modul: Tepelné čerpadlo (Heat Pump)

## Zařízení

**Samsung tepelné čerpadlo** s Modbus modulem pro dálkové řízení.
Komunikace: Modbus RTU → Waveshare WS-ETH → Modbus TCP.
Loxone šablona k dispozici (reference pro Modbus registry).

## Co systém řídí

- Povolení/zakázání provozu (Modbus příkaz)
- Požadovaná teplota TUV zásobníku (Modbus setpoint)
- Plánování okna provozu na základě COP a ceny elektřiny

## Co systém nečte (z Loxone šablony nebo Modbus registrů)

- Venkovní teplota čerpadla (`outdoor_temp_c`)
- Teplota zásobníku TUV (`tuv_tank_temp_c`)
- Příkon (`power_w`)
- Provozní režim (`operating_mode`)
- Alarm kód (`alarm_code`)
- Stav odmrazování (`defrost_active`)

---

## Logika řízení

### Prioritní pravidla (v pořadí)

1. **Override blokování** (`site_override.override_type = 'block_heat_pump'`) → TČ se nespouští
2. **Nouzový ohřev** – teplota zásobníku pod `tuv_min_temp_c` → spustit bez ohledu na cenu
3. **Zásobník plný** – teplota nad `tuv_max_temp_c` → neohřívat
4. **Ekonomické rozhodnutí** – spustit pokud cena tepla ≤ prahová hodnota

Logika je implementována v PostgreSQL funkci `ems.fn_heat_pump_should_run()`.

### Výpočet COP

COP závisí primárně na **venkovní teplotě**:
- Vyšší venkovní teplota = lepší COP = levnější teplo
- V chladných měsících je přes poledne venkovní teplota nejvyšší → optimální čas pro ohřev TUV

```
COP(t_venkovní) ≈ COP_rated + (t_venkovní - t_reference) × 0.10
```

Funkce: `ems.fn_cop_estimate(heat_pump_id, outdoor_temp_c)`

Cena tepla = cena elektřiny / COP → funkce `ems.fn_heat_pump_cost_per_kwh_heat()`

### Denní provozní okno

Typický scénář v chladných měsících (říjen–březen):
- Přes poledne (11:00–14:00) je venkovní teplota nejvyšší → COP nejlepší
- Pokud je zároveň spot cena nízká nebo FVE přebytek → ideální okno
- TČ potřebuje cca 1–2 hodiny denně pro nahrání TUV zásobníku (závisí na objemu a teplotním rozdílu)

Plánovací horizont: TČ se plánuje v rámci standardního 15min plánování stejně jako ostatní flexibilní spotřebiče.

---

## Omezení kompresoru

| Parametr | Hodnota | Důvod |
|---|---|---|
| `min_run_duration_min` | 30 min | Ochrana před krátkými cykly |
| `min_stop_duration_min` | 15 min | Vyrovnání tlaku před restartem |

Plánování musí respektovat tato omezení – nevytvářet plán s kratšími ON/OFF cykly.

---

## Modbus registry (doplnit z dokumentace Samsung)

> Konkrétní registry doplnit z Loxone šablony a Samsung Modbus dokumentace.

| Registr | Typ | Popis |
|---|---|---|
| TBD | Read | Venkovní teplota |
| TBD | Read | Teplota zásobníku TUV |
| TBD | Read | Příkon |
| TBD | Read | Provozní režim |
| TBD | Read | Alarm kód |
| TBD | Write | Povolení provozu (on/off) |
| TBD | Write | Požadovaná teplota TUV |

---

## Integrace s Loxone

Alternativní cesta (pokud Modbus přímý přístup není z nějakého důvodu vhodný):
- Loxone čte Modbus a vystavuje stav přes Virtual Outputs
- EMS posílá setpointy do Loxone přes HTTP Virtual Inputs
- Loxone přepisuje Modbus registry

Pro začátek doporučujeme **přímý Modbus TCP** (přes Waveshare) bez Loxone prostředníka pro řídící příkazy, Loxone nechat jako fallback.

---

## Otevřené body

- [ ] Doplnit konkrétní Modbus registry ze Samsung dokumentace / Loxone šablony
- [ ] Doplnit model Samsung a jmenovitý výkon do seed dat
- [ ] Ověřit `min_run_duration_min` a `min_stop_duration_min` z dokumentace
- [ ] Kalibrovat COP model na reálná historická data po prvních 4–6 týdnech provozu
- [ ] Rozhodnout: přímý Modbus TCP nebo přes Loxone jako prostředník
- [ ] Doplnit objem zásobníku TUV pro výpočet doby ohřevu