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.

Dôležité: Táto integrácia funguje iba v rámci vašej lokálnej siete — Home Assistant musí byť na rovnakej WiFi/LAN sieti ako samotné zariadenie. Sledovanie odkiaľkoľvek bez zdieľanej siete je samostatná, zatiaľ nedokončená funkcia do budúcna.

Č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 config váš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

Stiahnuť integráciu (.zip)

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

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.

Po úspešnom pridaní pribudnú dve nové zariadenia: „JK BMS Gateway" (firmvér, IP, licencia, stav CAN/NTP a tlačidlo „Rescan bus") a „JK BMS" (vaša batéria — napätia, prúd, výkon, jednotlivé články, teploty, stavy).

Máte viac batérií na jednej RS485 zbernici? Integrácia automaticky rozpozná každú pripojenú batériu (adresy 0–15) a vytvorí pre ňu samostatné zariadenie. Po pripojení ďalšej batérie stačí stlačiť tlačidlo „Rescan bus" na zariadení „JK BMS Gateway" — nový prístroj sa objaví bez reštartu Home Assistant. Existujúce entity zostanú nezmenené.

⚠️ Dôležité pri viacerých batériách: adresa 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

Hotový dashboard nájdete v stiahnutom balíčku vyššie aj priamo v repozitári projektu (dashboards/jkbms-dashboard.yaml). Dá sa použiť dvoma spôsobmi:

Ako nová záložka v existujúcom dashboarde

Otvorte dashboard → ⋮ (vpravo hore) → Upraviť dashboard → ⋮ → Upraviť v YAML. Do zoznamu views: vložte blok - title: JK-BMS (od tohto riadku po ďalší - title:) ako ďalšiu položku. Uložte.

Alebo ako úplne nový dashboard

Nastavenia → Dashboardy → Pridať dashboard → Nový dashboard od začiatku → ⋮ → Upraviť v YAML → vložte celý obsah súboru namiesto pôvodného obsahu. Uložte.

Ak sa „Upraviť v YAML" nezobrazuje na predvolenom dashboarde, je to normálne — Home Assistant túto možnosť ponúkne až po jeho prvom prevzatí/úprave, alebo použite nový dashboard od začiatku, ktorý ju ponúka rovno.

Dashboard počíta s 16-článkovým balíkom. Ak má vaše zariadenie iný počet článkov, riadky sensor.jk_bms_cell_<n>_voltage / _resistance podľa toho upravte.

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á.
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.