# Loxone Integration – dokumentace pro programátora

## Účel tohoto dokumentu

Popis jak nakonfigurovat Loxone Miniserver pro spolupráci s EMS platformou.
Implementaci provede Loxone programátor dle tohoto zadání.

**Klíčový princip:** Loxone je exekutor a bezpečnostní fallback.
Veškerá optimalizační logika je v EMS. Loxone:
- vykonává setpointy od EMS (v režimu AUTO)
- funguje zcela autonomně bez EMS (v ostatních režimech)
- sám detekuje výpadek EMS a přepne do bezpečného stavu

---

## 1. Virtual Inputs (EMS → Loxone)

Vytvořit jako **Virtual HTTP Input** v Loxone Config.
EMS posílá hodnoty přes HTTP GET: `/dev/sps/io/{název}/{hodnota}`

| Název VI | Typ | Rozsah | Popis |
|---|---|---|---|
| `EMS_Heartbeat` | Digital pulse | 0/1 | Minutový pulz od EMS. Základ pro watchdog. |
| `EMS_Mode` | Analog | 0–4 | Aktivní provozní režim (viz tabulka režimů níže). |
| `EMS_Battery_Setpoint_W` | Analog | -20000 až +20000 | Setpoint baterie ve W. Kladné = nabíjení, záporné = vybíjení. Platí jen v AUTO. |
| `EMS_Grid_Setpoint_W` | Analog | -20000 až +20000 | Setpoint sítě ve W. Kladné = import, záporné = export. Platí jen v AUTO. |
| `EMS_EV1_Power_W` | Analog | 0–22000 | Povolený výkon nabíječky EV č. 1 ve W. 0 = zakázat nabíjení. |
| `EMS_EV2_Power_W` | Analog | 0–22000 | Povolený výkon nabíječky EV č. 2 ve W. 0 = zakázat nabíjení. |
| `EMS_HeatPump_Enable` | Digital | 0/1 | Povolení provozu tepelného čerpadla. 1 = povolen, 0 = zakázán. |
| `EMS_ExportBan_Active` | Digital | 0/1 | **Signál z EMS (journal):** 1 = EMS aktuálně uplatňuje zákaz exportu do sítě (LED / indikace; viz `EXPORT_BAN_ACTIVE` v DB `ems.signal_route`). 0 = export ban neaktivní. Hodnotu periodicky posílá backend po řídicím cyklu; ověření readback viz níže. |

> **Poznámka k setpointům:** `EMS_Battery_Setpoint_W` a `EMS_Grid_Setpoint_W` jsou informativní vstupy pro AUTO režim. Loxone je předá jako Modbus příkazy do střídače Deye. V ostatních režimech (SELF_SUSTAIN, PRESERVE, MANUAL) Loxone tyto hodnoty ignoruje a řídí se vlastní logikou.

---

## 2. Virtual Outputs (Loxone → EMS čtení)

Vytvořit jako **Virtual HTTP Output** nebo stav dostupný přes HTTP GET pro EMS backend.

| Název VO | Typ | Popis |
|---|---|---|
| `EMS_Mode_Active` | Analog | Aktuálně aktivní režim v Loxone. EMS čte při startu pro zjištění stavu. |
| `EMS_Watchdog_Triggered` | Digital | 1 pokud watchdog přepnul na SELF_SUSTAIN bez příkazu od EMS. Pro diagnostiku. |
| `EMS_ExportBan_Active_FB` | Digital | **Readback pro verify:** musí odrážet stejný stav jako `EMS_ExportBan_Active` (např. ve Function Blocku zkopírovat hodnotu z VI na VO). EMS po zápisu čte `GET /dev/sps/io/EMS_ExportBan_Active_FB` a porovná s odeslanou hodnotou. Název lze přepsat v `ems.signal_route.verify_config_json` klíčem `loxone_io_name`. |

**Export ban – výchozí konfigurace DB (Loxone):**

- `ems.signal_def`: řádek `EXPORT_BAN_ACTIVE` (seed v migraci).
- `ems.signal_route`: jeden řádek na lokalitu — `destination_type = 'loxone_vi'`, `endpoint_id` → `site_endpoint` typu `loxone_http`, `signal_code = 'EXPORT_BAN_ACTIVE'`, `destination_key = 'EMS_ExportBan_Active'`, `verify_readback = true`, `verify_config_json = {"loxone_io_name": "EMS_ExportBan_Active_FB"}`.

---

## 3. Provozní režimy – kódování

| Kód EMS | Loxone hodnota `EMS_Mode` | Název |
|---|---|---|
| `MANUAL` | 0 | Manuální – žádná logika |
| `AUTO` | 1 | Automatický – EMS řídí |
| `SELF_SUSTAIN` | 2 | Soběstačný – Loxone autonomní |
| `CHARGE_CHEAP` | 3 | Nabíjení levnou cenou |
| `PRESERVE` | 4 | Ochrana baterie |

---

## 4. Watchdog – detekce výpadku EMS

**Toto je nejdůležitější část Loxone implementace.**

Watchdog musí fungovat čistě v Loxone, bez závislosti na DB nebo síti mimo lokální LAN.

### Požadované chování

```
Pokud EMS_Heartbeat pulz nepřijde déle než 5 minut:
  → nastavit EMS_Mode = 2 (SELF_SUSTAIN)
  → nastavit EMS_Watchdog_Triggered = 1
  → logovat čas přepnutí (Loxone log)

Pokud EMS_Heartbeat znovu přijde po výpadku:
  → EMS_Watchdog_Triggered = 0
  → NEMĚNIT EMS_Mode zpět automaticky
    (EMS si to přečte a rozhodne sám při restartu)
```

### Doporučená implementace v Loxone Config

**Varianta A – Timer / Watchdog blok:**
- Použít blok `Watchdog` nebo `Timer` resetovaný příchozím pulzem `EMS_Heartbeat`
- Timeout: 300 sekund (5 minut)
- Při vypršení timeoutu: výstup spustí přepnutí do SELF_SUSTAIN

**Varianta B – Pulse Counter + Time Trigger:**
- Počítat pulzy `EMS_Heartbeat` v 5min okně
- Pokud počet = 0 → přepnout režim

> Výběr varianty závisí na dostupných blocích ve verzi Loxone Config. Programátor zvolí vhodnou implementaci.

### Co Loxone watchdog NESMÍ dělat

- Číst DB nebo jiný HTTP endpoint pro rozhodnutí o watchdogu
- Automaticky přepínat zpět na AUTO při obnovení heartbeatu
- Zasahovat do Modbus komunikace EMS↔střídač (EMS píše Modbus přímo)

---

## 5. Stavový stroj režimů v Loxone

Pro každý `EMS_Mode` hodnotu definovat chování:

### Režim 1 – AUTO
```
Střídač Deye:
  - Battery charge limit  = EMS_Battery_Setpoint_W (pokud kladné)
  - Battery discharge limit = ABS(EMS_Battery_Setpoint_W) (pokud záporné)
  - Grid export limit     = ABS(EMS_Grid_Setpoint_W) (pokud záporné)
  - Grid import limit     = EMS_Grid_Setpoint_W (pokud kladné)

EV nabíječka 1:
  - Max power / current   = EMS_EV1_Power_W (přepočet W → A: W / (fáze × 230))
  - Enable                = 1 pokud EMS_EV1_Power_W > 1380, jinak 0

EV nabíječka 2:
  - Stejná logika, EMS_EV2_Power_W

Tepelné čerpadlo:
  - Enable                = EMS_HeatPump_Enable
```

### Režim 2 – SELF_SUSTAIN
```
Střídač Deye:
  - Přepnout do Self-Consumption / Battery Priority modu
    (konkrétní Modbus registr/hodnota dle Deye dokumentace)
  - Export do sítě:  zakázat (export limit = 0 W)
  - Import ze sítě:  povolen jen při SoC pod min_soc_percent (nouzový)
  - Baterie:         vybíjí do zátěže, nenabíjí ze sítě

EV nabíječky 1 + 2:
  - Enable = 0 (zakázat nabíjení)

Tepelné čerpadlo:
  - Enable = 0 (odstavit)
```

### Režim 3 – CHARGE_CHEAP
```
Střídač Deye:
  - Přepnout do Grid Charge modu
  - Battery charge limit  = EMS_Battery_Setpoint_W (EMS posílá max výkon)
  - Export do sítě: zakázat

EV nabíječky:
  - Enable = 0

Tepelné čerpadlo:
  - Enable = 0
```

### Režim 4 – PRESERVE
```
Střídač Deye:
  - Přepnout do Self-Consumption s omezeným nabíjením/vybíjením
  - Battery: drží aktuální SoC (charge limit = 0, discharge limit = 0)
  - Pokrývá spotřebu z FVE, zbytek ze sítě

EV nabíječky:
  - Enable = 0

Tepelné čerpadlo:
  - Enable = 0
```

### Režim 0 – MANUAL
```
Všechny výstupy: žádné automatické zásahy
Střídač: nechat v aktuálním stavu
EV, TČ: Enable = 0
Použít pouze pro servis a ladění
```

---

## 6. Komunikace Loxone → Deye (Modbus)

Loxone komunikuje s Deye střídačem přes **Modbus TCP** (Loxone Modbus Extension nebo přímý TCP).

> Konkrétní Modbus registry Deye SUN-20K doplnit z Deye protokolu PDF.
> Výchozí reference: Loxone šablona pro Deye (pokud existuje).

### Klíčové registry pro zápis (orientační, ověřit z dokumentace)

| Funkce | Registr | Typ | Poznámka |
|---|---|---|---|
| Battery charge power limit | 0x00F3 | Write Single | W |
| Battery discharge power limit | 0x00F4 | Write Single | W |
| Grid export power limit | 0x00F6 | Write Single | W |
| Work mode | 0x00F0 | Write Single | enum hodnoty dle Deye |

### Klíčové registry pro čtení (telemetrie – pouze pokud Loxone čte, jinak EMS přes Waveshare)

> **Doporučení:** Telemetrii čte EMS přímo přes Waveshare (Modbus TCP). Loxone čte jen to co potřebuje pro vlastní logiku (SoC pro SELF_SUSTAIN rozhodování).

---

## 7. Komunikace Loxone → EV nabíječky (Teltonika)

Loxone komunikuje s Teltonika TeltoCharge přes **Modbus TCP** (Waveshare převodník).

> Konkrétní Modbus registry Teltonika TeltoCharge doplnit z dokumentace / Loxone šablony.

### Minimální potřebné registry

| Funkce | Popis |
|---|---|
| Enable charging | Povolení/zakázání nabíjení (digital) |
| Max current limit | Maximální proud v A (6–32A) |
| Connector status | Stav připojení (read) |

---

## 8. Komunikace Loxone → Samsung TČ (Modbus)

Loxone komunikuje se Samsung tepelným čerpadlem přes **Modbus TCP** (Waveshare převodník).

> Registry doplnit ze Samsung NASA Modbus dokumentace / Loxone šablony.

### Minimální potřebné registry

| Funkce | Popis |
|---|---|
| Enable / Disable | Povolení provozu TČ (digital) |
| DHW target temp | Cílová teplota TUV zásobníku (write) |
| DHW tank temp | Aktuální teplota zásobníku (read) – pro watchdog nouzového ohřevu |

### Loxone nouzový ohřev (nezávisle na EMS)

Loxone musí implementovat vlastní minimální ochranu TUV zásobníku:
```
Pokud teplota zásobníku < 40°C (absolutní minimum):
  → spustit TČ bez ohledu na EMS_HeatPump_Enable a aktivní režim
  → logovat jako nouzový ohřev
```
Tato logika chrání zásobník i při výpadku EMS nebo přepnutí na SELF_SUSTAIN.

---

## 9. Testovací scénáře pro programátora

Po implementaci ověřit tyto scénáře:

| # | Scénář | Očekávané chování |
|---|---|---|
| 1 | EMS odešle `EMS_Mode=1`, pak každou minutu `EMS_Heartbeat=1` | Loxone v AUTO, přeposílá setpointy do střídače |
| 2 | EMS přestane posílat heartbeat na 6 minut | Loxone přepne na SELF_SUSTAIN, EMS_Watchdog_Triggered=1 |
| 3 | EMS pošle heartbeat znovu po výpadku | Watchdog_Triggered=0, Mode zůstane SELF_SUSTAIN (EMS rozhodne) |
| 4 | EMS odešle `EMS_Mode=4` (PRESERVE) | Loxone drží baterii, žádné nabíjení/vybíjení |
| 5 | Teplota TUV klesne pod 40°C v SELF_SUSTAIN | Loxone spustí TČ nouzově |
| 6 | EMS odešle `EMS_Battery_Setpoint_W=-5000` (vybíjení) | Loxone nastaví discharge limit 5000W, charge limit 0W |
| 7 | EMS odešle `EMS_EV1_Power_W=0` | Loxone zakáže nabíjení nabíječky 1 |

---

## 10. Otevřené body pro programátora

- [ ] Ověřit dostupnost Watchdog / Timer bloku v instalované verzi Loxone Config
- [ ] Zjistit konkrétní Modbus work mode hodnoty pro Deye (Self-Consumption, Grid-Charge, Backup)
- [ ] Ověřit Modbus registry Teltonika z dodané šablony/dokumentace
- [ ] Ověřit Modbus registry Samsung TČ z dodané šablony/dokumentace
- [ ] Dohodnout jestli Loxone čte SoC ze střídače pro SELF_SUSTAIN logiku (nebo pevný threshold)
- [ ] Loxone log přepnutí watchdogu – jak přístupný pro EMS při restartu?
