Initial commit

Made-with: Cursor

docs/04-modules/heat-pump.md

@@ -0,0 +1,107 @@
+# 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