Inštalácia Home Assistant integrácie
Táto integrácia zobrazí údaje z vášho JK BMS Web Gateway (napätia článkov, celkové napätie/prúd/výkon, SOC/SOH, teploty, stav MOSFET-ov a poplachov) priamo v Home Assistant — bez akýchkoľvek zmien vo firmvéri. Integrácia sa len pripája na existujúce lokálne rozhranie zariadenia, presne tak, ako to robí jeho vlastný webový dashboard.
Čo budete potrebovať
- Zariadenie JK BMS Web Gateway s aktivovanou licenciou (cez jeho vlastnú webovú stránku — pole „Licencia" v hlavičke). Bez toho inštalácia integrácie zlyhá s chybou o licencii.
- Home Assistant dostupný na rovnakej lokálnej sieti ako zariadenie.
- Spôsob, ako nahrať súbory do priečinka
configvášho Home Assistant — napríklad doplnok Studio Code Server, Samba share alebo File editor (všetky sú bežne dostupné v Obchode s doplnkami).
1. Stiahnutie a inštalácia integrácie
Stiahnite si súbory integrácie
ZIP obsahuje priečinok jkbms_web_gateway/ pripravený presne
v takej podobe, akú Home Assistant očakáva.
Rozbaľte ho do priečinka custom_components
Výsledok musí byť
config/custom_components/jkbms_web_gateway/manifest.json
a ďalšie súbory priamo v tomto priečinku (nie o úroveň hlbšie). Ak
priečinok custom_components v config ešte
neexistuje, vytvorte ho.
Reštartujte Home Assistant
Nastavenia → Systém → Reštartovať.
Pridajte integráciu
Nastavenia → Zariadenia a služby → Pridať integráciu a vyhľadajte „JK BMS Web Gateway".
Zadajte adresu zariadenia a adresy batérií
IP adresu gateway (napr. 192.168.0.239) alebo
jkbms.local, ak vo vašej sieti funguje mDNS. Port
ponechajte na 80, ak ste ho nemenili.
Do poľa „Addresses" zadajte RS485 adresu vašej batérie
(napr. 1), alebo pri viacerých batériách zoznam
oddelený čiarkou (napr. 1,2). Pole je predvyplnené
hodnotou 0 — vždy ju nahraďte skutočnou adresou
(adresa 0 sa nesmie použiť, pozri upozornenie
nižšie).
Po úspešnom pridaní pribudne zariadenie „JK BMS Gateway" (firmvér, IP, licencia, stav CAN/NTP a tlačidlo „Force refresh") a jedno „JK BMS" zariadenie za každú zadanú adresu (napätia, prúd, výkon, jednotlivé články, teploty, stavy).
1,2) — nový prístroj sa objaví bez reštartu
Home Assistant. Existujúce entity zostanú nezmenené. Tlačidlo
„Force refresh" iba okamžite vyvolá nové čítanie už
nakonfigurovaných adries, nové batérie samo nehľadá.
0 sa nesmie použiť.
Overili sme, že batéria nastavená na adresu 0 sa sama
správa ako „master" a nepretržite prehľadáva celú zbernicu — to
blokuje čítanie z nej aj zo susedných batérií, aj keď je zapojenie,
ukončovacie odpory aj uzemnenie úplne správne. Nejde o chybu
gateway ani tejto integrácie. Riešenie: nastavte adresy všetkých
batérií cez DIP prepínače (alebo appku výrobcu) na hodnoty
1–15 — napríklad pri dvoch batériách
použite 1 a 2, nie 0 a 1.
2. Pridanie dashboardu
Pripravené sú tri dashboardy, každý na stiahnutie zvlášť. Vyberte si jeden:
A. Automatický dashboard (odporúčaný)
Sám nájde všetky batérie nastavené v integrácii a ich skutočný počet článkov — jedna záložka na každú RS485 adresu 00–15. Netreba nič prepisovať.
Stiahnuť automatický dashboard (.zip)
Rozbaľte jkbms-fleet-strategy.js do priečinka config/www/ (ak neexistuje, vytvorte ho).
Nastavenia → Dashboardy → ⋮ → Zdroje → Pridať zdroj: URL /local/jkbms-fleet-strategy.js?v=1, typ JavaScript modul. Pri neskoršej aktualizácii súboru zvýšte číslo ?v=, aby prehliadač nenačítal starú verziu z vyrovnávacej pamäte.
Nastavenia → Dashboardy → Pridať dashboard → Nový dashboard od začiatku, otvorte ho → ⋮ → Upraviť v YAML a celý obsah nahraďte týmto. Uložte.
strategy:
type: custom:jkbms-fleet-strategyB. Statický dashboard (YAML)
Klasický YAML pre jednu 16-článkovú batériu s pevnými názvami entít. Hodí sa, ak si ho chcete ručne upravovať.
Stiahnuť statický dashboard (.zip)
Ako nová záložka: otvorte existujúci dashboard → ⋮ → Upraviť dashboard → ⋮ → Upraviť v YAML a do zoznamu views: vložte blok - title: JK-BMS (po ďalší - title:). Uložte.
Alebo ako nový dashboard: Nastavenia → Dashboardy → Pridať dashboard → Nový dashboard od začiatku → ⋮ → Upraviť v YAML a vložte celý obsah súboru jkbms-dashboard.yaml. Uložte.
Ak máte iný počet článkov než 16, upravte riadky sensor.jk_bms_cell_<n>_voltage / _resistance. Ak sa „Upraviť v YAML“ na predvolenom dashboarde nezobrazuje, použite nový dashboard od začiatku.
C. JK-BMS Overview (vzhľad gatewaya, s grafmi)
Vyzerá ako vlastný dashboard gatewaya: batéria so stavom nabitia, údaje o zariadení, články, teploty, stav a všetky ochranné nastavenia BMS, plus predpoveď počasia a spotové ceny, ak ich máte v gatewayi zapnuté. Navyše kreslí históriu napätia, prúdu, výkonu, stavu nabitia a rozptylu článkov za 1 hodinu až 7 dní, so súhrnom nabitej a vybitej energie. Nepotrebuje žiadne karty z HACS. Vyžaduje integráciu vo verzii 1.4.0 alebo novšej (stiahnite si ju znova vyššie a reštartujte Home Assistant).
Čo dashboard zobrazuje
- Záložky Zariadenie 00 – 15 — ako na gatewayi. Po otvorení sa zobrazí prvá batéria, ktorá má údaje; adresy bez batérie sú stlmené.
- Batéria — veľký ukazovateľ stavu nabitia s desiatimi segmentmi.
- Údaje o zariadení — Vendor ID, sériové číslo, verzia hardvéru a firmvéru, počet zapnutí, celkový čas a dátum prvého zapnutia.
- Hlavné hodnoty — napätie batérie, prúd, výkon, stav nabitia, zostávajúca a plná kapacita, počet cyklov.
- História v jednom grafe — výkon ako stĺpce (zelené nabíjanie, oranžové vybíjanie) a čiary napätia, prúdu, stavu nabitia a rozdielu článkov. Rozsah 1 h, 6 h, 24 h alebo 7 dní; kurzor ukáže všetky hodnoty v danom čase.
- Súhrn obdobia — nabitá a vybitá energia v kWh, špička nabíjania a vybíjania, najnižšie a najvyššie napätie, najväčší rozdiel článkov.
- Články — napätie každého článku s pásikom, najnižší a najvyšší článok farebne odlíšený, priemer, rozdiel v mV a stav balancovania.
- Teploty a stav — snímače T1 – T5 a MOSFET, nabíjací a vybíjací MOSFET, zdravie batérie (SOH), doba behu. Aktívne alarmy sa zobrazia v červenom pruhu.
- Ochranné nastavenia BMS — 29 hodnôt v šiestich skupinách: ochrana napätia článkov, napätie batérie, ochrana prúdu, teplotná ochrana, balancovanie a ostatné. Len na čítanie.
- Počasie a elektrina — predpoveď s odhadom výroby FV a spotové ceny, ak ich máte zapnuté v nastaveniach gatewaya.
Stiahnuť JK-BMS Overview (.zip)
Rozbaľte priečinok jkbms-overview/ do config/www/.
Nastavenia → Dashboardy → ⋮ → Zdroje → Pridať zdroj: URL /local/jkbms-overview/jkbms-overview-card.js?v=1, typ JavaScript modul. Pri neskoršej aktualizácii súboru zvýšte číslo ?v=.
Nastavenia → Dashboardy → Pridať dashboard → Nový dashboard od začiatku, otvorte ho → ⋮ → Upraviť v YAML a vložte obsah súboru jkbms-overview-dashboard.yaml (alebo len toto). Uložte.
views:
- title: JK-BMS Overview
type: panel
cards:
- type: custom:jkbms-overview-cardZáložky „Zariadenie 00“ až „Zariadenie 15“ otvárajú batérie nastavené v integrácii; po otvorení sa zobrazí prvá, ktorá má údaje. Grafy čerpajú z histórie a štatistík Home Assistant, takže sa začnú plniť pár minút po pridaní integrácie. Prúd a výkon majú znamienko ako na gatewayi: + nabíjanie, − vybíjanie. Všetky tri dashboardy nesú odkaz „Vytvoril: www.jkbms.sk“ — JK-BMS Overview hore vpravo, automatický a statický ako poslednú kartu každej záložky.
Farebné úrovne batérie
Dashboardy A a B farbia stav nabitia, napätie batérie aj každý článok podľa rovnakých úrovní pre LiFePO4 a obsahujú kartu „Úrovne – vysvetlivky“ s touto tabuľkou. Napätie batérie = napätie článku × počet článkov (tu 16S).
| Úroveň | SOC | Článok | Batéria (16S) |
|---|---|---|---|
| ● Kritické | < 10 % | < 2.90 V | < 46.4 V |
| ● Nízke | 10 – 25 % | 2.90 – 3.10 V | 46.4 – 49.6 V |
| ● Slabšie | 25 – 50 % | 3.10 – 3.20 V | 49.6 – 51.2 V |
| ● Dobré | 50 – 80 % | 3.20 – 3.40 V | 51.2 – 54.4 V |
| ● Plné | 80 – 100 % | 3.40 – 3.55 V | 54.4 – 56.8 V |
| ● Prepätie | — | > 3.55 V | > 56.8 V |
Meradlá SOC a napätia batérie sú štandardné karty Home Assistant. Pruhy článkov potrebujú kartu sensor-bar-card-plus a graf výkonu kartu apexcharts-card — obe nainštalujete cez HACS → Frontend (vyhľadajte podľa názvu → Stiahnuť).
Prerušovaná dostupnosť senzorov — to je normálne
Ak niektoré senzory občas na pár sekúnd zobrazia „Unavailable" a potom sa vrátia s reálnou hodnotou, nejde o chybu integrácie ani dashboardu — presne tak reaguje, keď sa zariadeniu práve nepodarilo prečítať dáta z BMS po RS485 zbernici (napr. dočasné rušenie). Integrácia zámerne nezobrazuje neplatnú alebo zastaranú hodnotu. Ak sú senzory nedostupné trvalo, ide o iný, skutočný problém — pozrite Riešenie problémov nižšie.
Riešenie problémov
- Chyba o licencii pri pridávaní: otvorte vlastnú webovú stránku zariadenia a najprv tam aktivujte licenciu (Licencia → Overiť), potom to skúste znova.
- „Nepodarilo sa pripojiť" pri pridávaní: overte IP adresu/host a či
je zariadenie z Home Assistant vôbec dosiahnuteľné — skúste v prehliadači
na tej istej sieti otvoriť
http://<IP-zariadenia>/api/info. - Senzory sú nedostupné trvalo, nie len občas: skontrolujte diagnostické senzory „License verified" a „Last error" pod zariadením v Home Assistant a či je gateway vôbec zapnutá a dosiahnuteľná.
- Doma všetko funguje, ale mimo domácej WiFi (na mobilných dátach) sa Home Assistant nenačíta: integrácia aj Home Assistant bežia len vo vašej sieti. Ako sa do nej dostať z vonku cez VPN, opisuje návod Vzdialený prístup.
- Chýba možnosť „Upraviť v YAML": predvolený, automaticky vytvorený dashboard túto možnosť neponúka, kým ho prvýkrát neupravíte alebo nezaložíte nový od začiatku.
DEYE Web Gateway v Home Assistant
Pre DEYE Web Gateway (trojfázové hybridné meniče DEYE SUN-xK-SG04LP3 / SG05LP3) je samostatná integrácia a hotový dashboard v rovnakom vzhľade ako záložka „Prehľad“ gatewaya: dom s animovanými tokmi energie, denná výroba a spotreba, grafy, predpoveď počasia, spotové ceny elektriny a AC konektory po fázach. Platia rovnaké podmienky ako vyššie — aktivovaná licencia na gatewayi a rovnaká lokálna sieť.
Čo dashboard zobrazuje
- Štyri hlavné dlaždice — výroba FV (teraz, dnes, celkom, PV1 a PV2), spotreba domu, batéria (stav nabitia, nabíjanie alebo vybíjanie) a sieť (odber a dodávka dnes).
- Dom s tokmi energie — FV, sieť, dom, batéria a GEN port (generátor, smart load alebo mikromenič) s animovanými bodkami. Smer ukazuje, kam energia tečie, počet a rýchlosť bodiek rastie s výkonom.
- Denná výroba a spotreba — koľko z výroby išlo do domu, do siete a do batérie, a koľko zo spotreby prišlo zo slnka, zo siete a z batérie — v kWh aj v percentách.
- Štyri grafy dneška — výkon FV, stav batérie, spotreba domu a výkon siete (odber hore, dodávka dole).
- Predpoveď počasia — na najbližšie dni s hodinami slnka, teplotami a odhadom výroby v kWh podľa výkonu vašej FV (kWp).
- Elektrina — aktuálna spotová cena (OKTE pre Slovensko, OTE pre Česko) s označením lacno / priemer / draho, nákupná a výkupná cena s vašimi poplatkami a DPH, dnešný odber a dodávka v eurách a graf dneška a zajtrajška.
- Tri tabuľky — výroba a spotreba dnes, stav batérie (výkon, napätie, prúd, teplota, nabité a vybité kWh) a výstup meniča (fázy, frekvencia, teploty, napätie siete).
- AC konektory po fázach — sieť, záťaž, GEN port a výstup striedača — napätie, výkon a prúd na L1, L2 a L3.
- Stav meniča — online alebo offline, prevádzkový stav a aktívne varovania a poruchy.
Integrácia navyše vytvorí približne 80 entít (výkony, energie, batéria, fázy, teploty), ktoré môžete použiť v automatizáciách a v paneli Energia.
1. Integrácia
Stiahnuť DEYE integráciu (.zip)
Rozbaľte priečinok deye_web_gateway/ do config/custom_components/ a reštartujte Home Assistant (Nastavenia → Systém → Reštartovať).
Nastavenia → Zariadenia a služby → Pridať integráciu, vyhľadajte „DEYE Web Gateway“ a zadajte IP adresu gatewaya (alebo deye.local) a port 80. Pribudne zariadenie „DEYE“ so senzormi výkonu, energie, batérie, fáz a teplôt. Počítadlá energie sa dajú použiť aj v paneli Energia.
2. Dashboard
Stiahnuť DEYE dashboard (.zip)
Rozbaľte priečinok deye-overview/ (súbory deye-overview-card.js a bg.jpg) do config/www/.
Nastavenia → Dashboardy → ⋮ → Zdroje → Pridať zdroj: URL /local/deye-overview/deye-overview-card.js?v=1, typ JavaScript modul. Pri neskoršej aktualizácii súboru zvýšte číslo ?v=.
Nastavenia → Dashboardy → Pridať dashboard → Nový dashboard od začiatku, otvorte ho → ⋮ → Upraviť v YAML a vložte obsah súboru deye-dashboard.yaml (alebo len toto). Uložte.
views:
- title: DEYE Gateway
type: panel
cards:
- type: custom:deye-overview-card- IP adresa gatewaya — Nastavenia → Zariadenia a služby → DEYE Web Gateway → ⋮ → Prekonfigurovať a zadajte novú adresu. Entity, ich história aj dashboardy zostanú nezmenené, aj keď gateway vymeníte za iný kus. Tlačidlo Konfigurovať (ozubené koliesko) mení len interval čítania.
- Číslo domu a ŠPZ auta — na stránke gatewaya: Nastavenia → Nastavenia web servera → Dom a auto. Číslo domu má najviac 7 znakov, ŠPZ najviac 12; prázdne pole sa na scéne nezobrazí. V tej istej časti je aj poloha pre predpoveď, výkon FV (kWp) a spotové ceny.
- Fotka domu — prepíšte súbor
config/www/deye-overview/bg.jpgvlastnou fotkou v pomere 16:9 a zvýšte číslo?v=pri zdroji. Menovky a čiary tokov sú umiestnené podľa pôvodnej fotky, na inej nemusia sedieť.
Karta si entity nájde sama, netreba nič prepisovať. Predpoveď počasia, polohu, výkon FV (kWp), spotové ceny a poplatky, číslo domu a ŠPZ auta preberá z nastavení gatewaya (Nastavenia web servera na jeho vlastnej stránke) — zmena sa v Home Assistant prejaví do 10 minút, hneď po ⋮ → Znova načítať na integrácii. Grafy čerpajú zo štatistík Home Assistant, takže sa začnú plniť niekoľko minút po pridaní integrácie. Znamienka sú rovnaké ako na gatewayi: výkon batérie + = vybíjanie, výkon siete + = odber. Vpravo hore je odkaz „Vytvoril: www.jkbms.sk“.