ems/docs/04-modules/telemetry.md

Modul: Telemetry (Sběr dat ze zařízení)

Co modul dělá

• Čte data ze střídače Deye, EV nabíječek Teltonika a tepelného čerpadla Samsung přes Modbus TCP
• Ukládá surová měření do DB (1min granularita)
• Detekuje výpadky komunikace a loguje chyby
• Agreguje 1min data na 15min průměry pro spotřebu, audit a plánování

---

Komponenta: telemetry_collector (Python service)

Samostatná Python služba. Běží jako smyčka, nezávislá na FastAPI.

Polling intervaly

Zařízení	Interval	Důvod
Deye střídač	60 s	1min granularita telemetrie
Teltonika EV nabíječka 1	60 s
Teltonika EV nabíječka 2	60 s
Samsung tepelné čerpadlo	60 s

Chování při chybě

• Chyba komunikace: záznam se nezapíše, chyba se loguje
• 3 po sobě jdoucí chyby = alert (log WARNING)
• 10 po sobě jdoucích chyb = log ERROR + pokus o reconnect
• Data se neinterpolují – chybějící minuty zůstanou prázdné (audit to pozná)

---

Deye SUN-20K – Modbus registry

Komunikace: Modbus TCP, Unit ID dle DIP přepínače na střídači (typicky 1).

Mapování v kódu: backend/services/telemetry_collector.py (holding registry, decimal adresa = offset pro read_holding_registers).

Dec (hex)	Typ	Popis	Jednotka	Poznámka
500 (0x01F4)	uint16	Provozní stav střídače	enum	raw do run_state, ladění
514 (0x0202)	uint16	Dnešní nabití baterie	Wh	batt_charge_today_wh
515 (0x0203)	uint16	Dnešní vybití baterie	Wh	batt_discharge_today_wh
588 (0x024C)	uint16	Battery SoC	%	battery_soc_percent
590 (0x024E)	int16	Tok výkonu baterie	W	signed: + vybíjení, − nabíjení
625 (0x0271)	int16	Výkon sítě	W	signed: + import, − export
653 (0x028D)	uint16	Celková spotřeba	W	load_power_w
667 (0x029B)	uint16	Výkon GEN portu (FVE pole B)	W	gen_port_power_w, nelze curtailovat
672 (0x02A0)	uint16	Výkon PV1	W	pv1_power_w
673 (0x02A1)	uint16	Výkon PV2	W	pv2_power_w

pv_power_w v DB = PV1 + PV2 + GEN port (celková výroba na instalaci home-01). gen_port_power_w zůstává i nadále uložen samostatně pro audit a detailní diagnostiku.

Zápis setpointů (plánování → Deye):

Registr (hex)	Typ	Popis	Hodnota
0x00F3	Write Single	Battery charge power limit	W
0x00F4	Write Single	Battery discharge power limit	W
0x00F6	Write Single	Grid export power limit	W
0x00F0	Write Single	Work mode	enum (viz tabulka)

Rychlá kontrola komunikace: scripts/test_modbus_deye.py.

---

Teltonika TeltoCharge – Modbus registry

Komunikace: Modbus TCP přes Waveshare, Unit ID = 1 (ověřit).

Registry doplnit z Teltonika TeltoCharge Modbus dokumentace / Loxone šablony.

Registr	Typ	Popis	Jednotka
TBD	Read	Stav konektoru (OCPP status enum)	enum
TBD	Read	Aktuální výkon	W
TBD	Read	Kumulativní energie session	Wh
TBD	Read	Proud L1/L2/L3	0.1A
TBD	Read	Napětí	0.1V
TBD	Read	Session ID	uint
TBD	Read	Error code	uint
TBD	Write	Max proud (charge limit)	A (6–32A)
TBD	Write	Povolení nabíjení (on/off)	bool

---

Samsung tepelné čerpadlo – Modbus registry

Komunikace: Modbus TCP přes Waveshare.

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

Registr	Typ	Popis	Jednotka
TBD	Read	Venkovní teplota	0.1°C
TBD	Read	Teplota vody vstup	0.1°C
TBD	Read	Teplota vody výstup	0.1°C
TBD	Read	Teplota zásobníku TUV	0.1°C
TBD	Read	Příkon	W
TBD	Read	Provozní režim	enum
TBD	Read	Alarm kód	uint
TBD	Read	Odmrazování aktivní	bool
TBD	Write	Povolení provozu	bool
TBD	Write	Požadovaná teplota TUV	°C

---

Kód telemetrie (Python)

Implementace: backend/services/telemetry_collector.py — poll_inverter() používá konstanty DEYE_REG_* a třídu ModbusDevice; hlavní smyčka je run_telemetry_loop / run_telemetry_loop_wrapper.

---

Agregace 1min → 15min

Prováděna PostgreSQL funkcí ems.fn_fill_audit_interval() a ems.fn_fill_baseline_consumption(). Spouštěna každých 15 minut jako scheduled task (Python APScheduler nebo pg_cron).

-- Příklad agregace telemetrie na 15min průměr
-- (součást fn_fill_audit_interval)
SELECT
    site_id,
    time_bucket('15 minutes', measured_at) AS interval_start,
    AVG(pv_power_w)::INT          AS avg_pv_power_w,
    AVG(battery_power_w)::INT     AS avg_battery_power_w,
    AVG(grid_power_w)::INT        AS avg_grid_power_w,
    AVG(load_power_w)::INT        AS avg_load_power_w,
    LAST(battery_soc_percent, measured_at) AS last_soc_pct
FROM ems.telemetry_inverter
WHERE measured_at >= $1 AND measured_at < $1 + INTERVAL '15 minutes'
  AND site_id = $2
GROUP BY site_id, time_bucket('15 minutes', measured_at);

---

Konfigurace (env proměnné)

TELEMETRY_POLL_INTERVAL_SEC=60
TELEMETRY_ERROR_WARN_THRESHOLD=3     # počet chyb před WARNING logem
TELEMETRY_ERROR_RECONNECT_THRESHOLD=10
MODBUS_CONNECT_TIMEOUT_SEC=5
MODBUS_READ_TIMEOUT_SEC=3

---

Otevřené body

• Základní mapování Deye (holding registry 500–673) v telemetry_collector.py
• Doplnit Modbus registry Teltonika z dokumentace / Loxone šablony
• Doplnit Modbus registry Samsung z dokumentace / Loxone šablony
• Ověřit Unit ID všech zařízení při instalaci
• Optimalizovat čtení Deye jako jeden read_holding_registers blok místo jednotlivých registrů