Initial commit
Made-with: Cursor
This commit is contained in:
Dusan Vojacek
263
docs/loxone-integration.md
Normal file
263
docs/loxone-integration.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# 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. |
|
||||
|
||||
> **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. |
|
||||
|
||||
---
|
||||
|
||||
## 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?
|
||||
Reference in New Issue
Block a user