ems/docs/04-modules/modbus-registers.md

Deye Modbus Registry – EMS řízení

Důležité pravidlo

• Registry 60–499: POUZE FC 0x10 (write_registers)
• Registry 0–59: FC 0x03 čtení, FC 0x06 zápis
• Registry 500+: FC 0x03 pouze čtení

EMS zapisuje řídící hodnoty přes journal (modbus_command) a write_registers (FC 0x10), nikdy write_register (FC 0x06) pro rozsah 60–499.

Řídící registry (R/W, FC 0x10)

Reg	Název	Rozsah	Jednotka	Použití v EMS
108	Max charge current	0 … max dle modelu (manuál Deye)	1 A	EMS počítá proud v SQL: COALESCE(deye_register_max_charge_a, FLOOR(LEAST(W)/51.2)) — sloupec stropu v A je volitelný (NULL = jen odvod z kW); při vyplnění např. 350 při W→351 A se použije 350.
109	Max discharge current	0 … max dle modelu (manuál Deye)	1 A	Stejně: COALESCE(deye_register_max_discharge_a, FLOOR(LEAST(W)/51.2)).
128	Grid charge current	0 … max dle modelu (manuál Deye)	1 A	Nabíjení ze sítě
130	Grid charge enable	0/1	—	1 = povolit nabíjení ze sítě
141	Energy mgmt mode	bitmask	—	EMS vždy 0 (neměnit jinak)
142	Limit control (System work mode)	0/1/2	—	0 = selling first, 1 = zero export to load, 2 = zero export to CT. Hodnota v non-SELL režimech pochází z asset_inverter.deye_zero_export_mode (závisí na instalaci – viz tabulka níže). V režimu SELL vždy 0.
145	Solar sell	0/1	—	0 = disabled (omezí FVE aby neexportoval), 1 = enabled. EMS vždy zapisuje 1. Při reg 108 = 0 (baterie se nenabíjí) a solar sell = 1 přebytky FVE tečou do sítě.
143	Export limit W	závisí na typu (SUN-20K až ~13 500)	1 W	Max export do sítě; hodnota z site_grid_connection.max_export_power_w
178	Grid peak shaving switch	bitmask	—	EMS zapisuje pevnou hodnotu (bez read-modify-write kvůli kolizím s paralelním čtením z Loxone): 32 (0b00100000, bit4–5 = 10) v režimu SELL; 48 (0b00110000, bit4–5 = 11) v PASSIVE a CHARGE.
190	GEN peak shaving	0–16000	1 W	Peak shaving na GEN portu
191	Grid peak shaving power	0–16000	1 W	EMS NEZAPISUJE – nastavit manuálně v SolarmanApp. Hodnota určuje výkon peak shavingu v W.

control_exporter.write_inverter_setpoints zapisuje přes modbus_command (journal; jeden řádek na registr) a execute_modbus_commands odesílá souvislé bloky jedním FC 0x10 (např. 62–64, 148–159, 166–177, 108–109, 141–143, 145 podle toho, co je ve frontě). Pořadí v journalu: 62–64 (čas, viz níže), time points 148–177 (jen řádky zařazené do daného běhu), 108, 109, 141, 142, 143, 145, 178. Popisné názvy v DB bere DEYE_REGISTER_NAMES. Reg 191 EMS nezapisuje.

Reg 191 (výkon grid peak shaving)

• EMS NEZAPISUJE – nastavit manuálně v SolarmanApp.
• Hodnota určuje výkon peak shavingu v W (typicky 0–16 000).

Reg 178 – hodnoty podle fyzického režimu

• SELL: 32 – bit4–5 = 10, grid peak shaving disable (export do sítě).
• PASSIVE a CHARGE: 48 – bit4–5 = 11, grid peak shaving enable.

EMS nezapisuje read-modify-write (paralelní čtení jinými klienty může způsobit nesoulad).

Ověření v journalu (modbus_command): u zápisu 178 se při verify porovnávají jen bity 4–5 maskou 0x0030 s očekávanou hodnotou (32/48); value_verified zůstává plný readback. Detail: modbus-command-journal.md.

Klíčové registry podle fyzického režimu Deye

Provozní režimy EMS (AUTO, SELF_SUSTAIN, SELL, …) se mapují na tři fyzické režimy střídače: PASSIVE, SELL, CHARGE. Solver navíc rozlišuje čtyři typy slotů – každý typ určuje specifickou kombinaci registrů.

Detekce fyzického režimu (get_deye_mode v control_exporter.py)

Vychází z grid_setpoint_w a battery_w z ControlSetpoints (aktivní plán / politika EMS), ne z telemetrie.

Režim	Podmínka
SELL	battery_w < −500 a grid_setpoint_w < −200 (aktivní vybíjení baterie pro export)
CHARGE	battery_w > 500 a grid_setpoint_w > 200
PASSIVE	vše ostatní (včetně pass-through, self-consumption, SELF_SUSTAIN, IDLE, …)

Režim CHARGE_CHEAP v EMS nastaví grid_setpoint_w tak, aby platila podmínka importu (> 200 W), jinak by fyzicky zůstal PASSIVE.

Důležité: SELL se aktivuje pouze při záměrném vybíjení baterie do sítě (bat_w < −500). Pass-through (PV → síť, baterie idle) zůstává v PASSIVE s reg 108 = 0.

Čtyři typy slotů a mapování na registry

Solver předvybírá sloty pro nabíjení a export-vybíjení (_select_charge_slots, _select_discharge_export_slots). Výsledné setpointy pak určují typ slotu:

	Charge	Pass-through	Discharge-export	Self-consumption
Kdy	Solver: bat_w > 0	Solver: bat_w == 0, PV > spotřeba	Solver: bat_w < −500, grid_w < −200	Noc / PV < spotřeba
Deye mode	PASSIVE	PASSIVE	SELL	PASSIVE
108 charge A	max (z DB)	0	0	0
109 discharge A	max	max	max	max
142 limit control	deye_zero_export_mode (1 nebo 2)	deye_zero_export_mode (1 nebo 2)	0 (selling first)	deye_zero_export_mode (1 nebo 2)
145 solar sell	1 (enabled)	1 (enabled)	1 (enabled)	1 (enabled)
178 peak shaving	48 (PASSIVE)	48 (PASSIVE)	32 (SELL)	48 (PASSIVE)
143 export limit	max export W z DB	max export W z DB	max export W z DB	max export W z DB
141 energy mode	0	0	0	0
TOU SOC	min_soc_pct	min_soc_pct	reserve_soc_pct	min_soc_pct

Jak funguje pass-through fyzicky:

1. Reg 108 = 0 → baterie se fyzicky nemůže nabíjet (Deye ji považuje za „plnou")
2. Reg 142 = 1/2 → zero export mode (Deye nebude aktivně prodávat z baterie)
3. Reg 145 = 1 → solar sell enabled: protože baterie je „plná" (108 = 0), PV přebytky tečou do sítě
4. Reg 109 = max → pokud spotřeba překročí FVE, baterie může vybíjet (ochrana self-consumption)

deye_zero_export_mode per inverter

Hodnota registru 142 v non-SELL režimech závisí na fyzické instalaci. Uložena v asset_inverter.deye_zero_export_mode:

Site	Inverter ID	deye_zero_export_mode	Důvod
home-01 (id=2)	3	1 (zero export to load)	Nemá CT
BA81 (id=3)	5	2 (zero export to CT)	CT osazeno
KV1 (id=4)	7	2 (zero export to CT)	CT osazeno

Varování: Záměna způsobí chybné měření – pokud site nemá CT a nastaví se „to CT" (2), střídač nevidí skutečný odběr. Naopak pokud má CT ale nastaví se „to load" (1), zátěže mimo load port (např. wallbox) nebudou vidět.

Efektivní max_charge_a / max_discharge_a pro řízení načítá _load_inverter_config z DB jedním výrazem COALESCE(strop v A, FLOOR z W)) (migrace V044 + dotaz v control_exporter.py). max_export_power_w / reg 143 také z DB.

Time Points – řízení podle fyzického režimu

Deye má 6 časových bloků. EMS přepisuje bloky 1–2 (TOU index 0–1) při každém control_export. Bloky 3–6 (neaktivní výplň, čas 2355) zapisuje nejednou častěji než jednou za kalendářní den v Europe/Prague a okamžitě znovu, pokud se změní podpis deye_tou_inactive_signature (HHMM|min_soc|reserve_soc|tp_discharge_w) — metadata v asset_inverter (V028 + V029 komentář).

Výběr aktivního segmentu na invertoru: platí poslední časový bod, jehož HH:MM ≤ aktuálnímu času na hodinách střídače (po synchronizaci 62–64). Proto nesmí zůstat jako jediný „minulý“ bod např. 00:00 s pasivním profilem, zatímco profil s nabíjením ze sítě je až u budoucího času – mezi půlnocí a tím budoucím časem by invertor celou dobu používal špatný segment.

Blok	Čas (HHMM, Europe/Prague)	Zdroj plánu	Účel	SOC min	Grid charge
1	current_slot_hhmm() – začátek probíhajícího 15min slotu	planning_interval pro aktuální slot (_fetch_plan_row_for_slot_offset(..., 0))	PASSIVE / SELL / CHARGE dle _deye_tou_params	viz tabulka níže	viz tabulka níže
2	next_slot_hhmm() – začátek následujícího 15min slotu	planning_interval pro další slot (_fetch_plan_row_for_slot_offset(..., 1))	Přechod na další čtvrthodinu	viz tabulka níže	viz tabulka níže
3–6	23:55 (2355)	—	Neaktivní (pasivní profil); ne 23:59 — firmware Deye často 2359 neuloží → verify mismatch	min_soc_percent (DB)	NE

Registry 108 / 109 / 141 / 142 / 143 / 145 / 178 odpovídají aktuálnímu plánu (okamžitý výstup; setpoints_now v write_inverter_setpoints). TOU řádky 1–2 doplňují stejnou logiku pro časové segmenty (_deye_tou_params).

Příklad v 14:18: blok 1 má čas 1415, blok 2 čas 1430 – mezi 14:15 a 14:29 je aktivní segment z bloku 1 (sladěný s plánem pro 14:15–14:30), po 14:30 blok 2 (plán 14:30–14:45). Po dalším exportu se oba časy posunou (např. 14:30 / 14:45).

Fyzické režimy Deye – parametry jednoho time pointu (bloky 1–2)

Režim	Výkon (W)	SOC min (reg 166+)	Grid charge
PASSIVE	max_discharge_a × 51,2	min_soc_percent z DB	NE
SELL	max_discharge_a × 51,2	reserve_soc_percent z DB	NE
CHARGE	battery_watts_to_amps(battery_w, max_charge_a) × 51,2	min(95, cíl SoC z plánu nebo 80)	ANO

Bloky 3–6 používají čas 2355 a stejnou SOC hodnotu jako PASSIVE (min_soc_percent, grid charge = NE).

Synchronizace času

Registry 62–64 nastavují invertoru čas v Europe/Prague.

• reg 62: (rok - 2000) << 8 | měsíc
• reg 63: den << 8 | hodina
• reg 64: minuta << 8 | sekunda — při zápisu z EMS jsou sekundy vždy 0 (stabilnější hodnota; na zařízení pak sekundy dál běží).

Řidší zápis: před každým exportem setpointů EMS přečte 62–64 (FC 0x03). Do journalu 62–64 nezařadí, pokud je dekódovaný čas invertoru vůči aktuální Europe/Prague v odchylce ≤ 60 s a zároveň od posledního úspěšného syncu neuplynulo 24 h. Sloupce asset_inverter.deye_last_system_time_sync_at a deye_last_system_time_sync_minute se doplňují po úspěšném FC 0x10 zápisu batche obsahujícího 62–64 (write_inverter_setpoints) a znovu po úspěšné toleranční verifikaci (_verify_deye_clock_written_bundle) — obojí drží řidší zápis i když verify občas selže. Je-li deye_last_system_time_sync_at NULL (první provoz), zápis času se nevynechá. Při selhání čtení 62–64 před rozhodnutím se čas zařadí do journalu (bezpečný fallback). Při scénáři „žádný řádek journalu, všechny hodnoty jako poslední verified“ se čas v DB neaktualizuje (žádný fiktivní sync).

Zápis prochází journal jako každý jiný registr; na sběrnici jde souvislý blok FC 0x10.

Verifikace (journal): registry 62–64 se nikdy neověřují striktním porovnáním po jednotlivých registrech (reg 64 by kvůli běžícím sekundám padal do mismatch a spouštěl SELF_SUSTAIN). Verifikační job vždy přečte FC 0x03 souvisle 62–64 a použije toleranci 120 s na dekódovaný čas (_deye_clock_registers_verify_match). Je-li ve stavu written jen podmnožina řádků (např. jen 64), očekávané hodnoty pro chybějící registry se doplní z posledního verified nebo z aktuálního přečtení na sběrnici (_deye_expected_clock_triplet_for_verify). Po třech neúspěšných ověřeních bloku 62–64 EMS nepřepíná provozní režim na SELF_SUSTAIN; pošle kritický Discord (notify_modbus_clock_verify_exhausted) — viz modbus-command-journal.md.

Před vytvořením journalu: pokud je navrhovaná hodnota shodná s posledním verified záznamem daného registru v modbus_command, EMS řádek nevytvoří a na Modbus neposílá (žádný „X → X“ zápis jen kvůli periodickému exportu). Výjimky řeší stávající logika (řidší 62–64 výše, denní TOU 3–6 + meta sloupce na asset_inverter).

Mapování registrů (time point i, i = 0…5)

Účel	Adresa
Čas HHMM	148 + i
Výkon (W)	154 + i
Min. SOC %	166 + i
Grid charge enable 0/1	172 + i

Limity nabíjení/vybíjení v ampérech a export z site_grid_connection / asset_inverter / asset_battery načítá _load_inverter_config() (max_charge_a / max_discharge_a jako LEAST(BMS, střídač) / 51,2). Python neřeže na univerzální číslo – hodnoty v DB mají odpovídat skutečnému modelu střídače a BMS (maximální povolená hodnota v registru se liší podle typu; není to všude např. 185 A). Ověřit v dokumentaci k danému SUN-*K.

Telemetrické registry (R only, FC 0x03)

Reg	Název	Jednotka	Poznámka
500	Run state	—	0 = standby, 2 = normal
588	Battery SOC	1 %
590	Battery power	1 W S16	+ vybíjení / − nabíjení
625	Grid total power	1 W S16	+ import / − export
653	Load total power	1 W S16
667	GEN port power	1 W S16	FVE pole B; signed — záporné při zpětném toku / bez výroby
672	PV1 power	1 W S16	signed; EMS ukládá raw signed W, do pv_power_w jen max(0, kanál)
673	PV2 power	1 W S16	jako PV1

Přepočty

• Výkon baterie → proud (LV 51,2 V): battery_watts_to_amps(power_w, max_amps) = min(max(0, max_amps), max(0, round(|power_w| / 51.2))), kde max_amps je z DB
• max_export_power_w / max_import_power_w / limity baterie berou se z DB (_load_inverter_config), ne z natvrdo v Pythonu
• Export do registru 143 = site_grid_connection.max_export_power_w (např. home-01 / SUN-20K 13 500 W)

Ověření (Modbus + DB)

docker compose up -d --build backend

import asyncio
from pymodbus.client import AsyncModbusTcpClient

async def check():
    c = AsyncModbusTcpClient('172.16.1.10', port=502, timeout=5)
    await c.connect()

    times = await c.read_holding_registers(148, count=2)
    for i in range(2):
        h, m = divmod(times.registers[i], 100)
        print(f'Time point {i+1}: {h:02d}:{m:02d}')

    for name, reg in [
        ('Limit control', 142),
        ('Solar sell',    145),
        ('Peak sw (bit4-5)', 178),
        ('Export limit',  143),
        ('Discharge A',   109),
        ('Grid power',    625),
    ]:
        r = await c.read_holding_registers(reg, count=1)
        raw = r.registers[0]
        signed = raw - 65536 if raw > 32767 else raw
        print(f'{name} ({reg}): {signed}')

    c.close()

asyncio.run(check())

docker compose exec db psql -U ems_user -d ems -c "
  SELECT register_name, value_to_write, status,
         created_at AT TIME ZONE 'Europe/Prague' AS cas
  FROM ems.modbus_command
  WHERE site_id=2 AND register IN (108, 109, 142, 145)
  ORDER BY created_at DESC LIMIT 9;"

Související

• docs/04-modules/modbus-command-journal.md – journal a verifikace
• backend/services/control_exporter.py – zápisy
• backend/services/modbus_client.py – write_registers (FC 0x10)