Installing the Home Assistant integration
This integration shows your JK BMS Web Gateway's data (cell voltages, total voltage/current/power, SOC/SOH, temperatures, MOSFET and alarm status) directly in Home Assistant — with no firmware changes at all. It simply connects to the device's existing local interface, exactly like its own web dashboard does.
What you'll need
- A JK BMS Web Gateway with an activated license (through its own web page — the "Licencia" field in the header). Without this, setting up the integration fails with a license error.
- Home Assistant reachable on the same local network as the device.
- A way to upload files into your Home Assistant's
configfolder — e.g. the Studio Code Server, Samba share, or File editor add-on (all commonly available in the Add-on Store).
1. Download and install the integration
Download the integration files
Download the integration (.zip)
The zip contains a jkbms_web_gateway/ folder, ready
in exactly the shape Home Assistant expects.
Unzip it into your custom_components folder
The end result must be
config/custom_components/jkbms_web_gateway/manifest.json
and the other files directly inside that folder (not one level
deeper). Create the custom_components folder inside
config first if it doesn't exist yet.
Restart Home Assistant
Settings → System → Restart.
Add the integration
Settings → Devices & services → Add Integration and search for "JK BMS Web Gateway".
Enter the device's address and battery address(es)
The gateway's IP address (e.g. 192.168.0.239) or
jkbms.local if mDNS works on your network. Leave the
port at 80 unless you've changed it.
In the "Addresses" field, enter your battery pack's RS485
address (e.g. 1), or a comma-separated list for more
than one pack (e.g. 1,2). This field is pre-filled
with 0 — always replace it with your pack's real
address, since 0 must never be used (see the
warning below). Submit.
Once it succeeds, one "JK BMS Gateway" device appears (firmware, IP, license, CAN/NTP status, and a "Force refresh" button that re-polls the configured addresses on demand), plus one "JK BMS" device per address you entered (voltage, current, power, individual cells, temperatures, status).
1,2) — the new device appears
without restarting Home Assistant. Your existing entities stay
unchanged. The "Force refresh" button only re-polls addresses
already in that list; it doesn't discover new ones on its own.
0.
We've confirmed a pack set to address 0 behaves as a
"master" on its own and continuously scans the whole bus — this
blocks reads of it and its neighbors, even with perfectly correct
wiring, termination, and grounding. This isn't a bug in the gateway
or this integration. Fix: set every pack's address via its DIP
switches (or the manufacturer's app) to 1-15
— for example, with two packs use 1 and 2,
not 0 and 1.
2. Add a dashboard
Three ready-made dashboards are available, each as its own download. Pick one:
A. Automatic dashboard (recommended)
Finds every pack configured in the integration and its real cell count by itself — one tab per RS485 address 00–15. Nothing to edit.
Download the automatic dashboard (.zip)
Unzip jkbms-fleet-strategy.js into config/www/ (create the folder if it doesn't exist).
Settings → Dashboards → ⋮ → Resources → Add resource: URL /local/jkbms-fleet-strategy.js?v=1, type JavaScript module. When you replace the file later, raise the ?v= number so browsers don't keep a cached copy.
Settings → Dashboards → Add dashboard → New dashboard from scratch, open it → ⋮ → Edit in YAML and replace everything with this. Save.
strategy:
type: custom:jkbms-fleet-strategyB. Static dashboard (YAML)
Classic YAML for one 16-cell pack with fixed entity names. Handy if you want to edit it by hand.
Download the static dashboard (.zip)
As a new tab: open an existing dashboard → ⋮ → Edit dashboard → ⋮ → Edit in YAML and paste the - title: JK-BMS block (up to the next - title:) into the views: list. Save.
Or as a new dashboard: Settings → Dashboards → Add dashboard → New dashboard from scratch → ⋮ → Edit in YAML and paste the whole jkbms-dashboard.yaml. Save.
If your pack doesn't have 16 cells, adjust the sensor.jk_bms_cell_<n>_voltage / _resistance rows. If "Edit in YAML" isn't offered on your default dashboard, use a new dashboard from scratch.
C. JK-BMS Overview (the gateway's look, with charts)
It looks like the gateway's own dashboard: the battery with its state of charge, device details, cells, temperatures, status and every BMS protection setting, plus the weather forecast and spot prices if you have them switched on in the gateway. On top of that it draws the history of voltage, current, power, state of charge and cell spread for 1 hour to 7 days, with a summary of the energy charged and discharged. It needs no HACS cards. It requires the integration in version 1.4.0 or newer (download it again above and restart Home Assistant).
What the dashboard shows
- Tabs Device 00 – 15 — as on the gateway. The first pack that has data is shown when the dashboard opens; addresses without a pack are dimmed.
- Battery — a large state-of-charge gauge with ten segments.
- Device details — vendor ID, serial number, hardware and firmware version, power-on count, total time and the first power-on date.
- Main values — pack voltage, current, power, state of charge, remaining and full capacity, cycle count.
- History in one chart — power as bars (green charging, orange discharging) and lines for voltage, current, state of charge and cell difference. Range 1 h, 6 h, 24 h or 7 days; the cursor shows every value at that time.
- Summary of the period — energy charged and discharged in kWh, peak charging and discharging power, lowest and highest voltage, largest cell difference.
- Cells — every cell's voltage with a bar, the lowest and highest cell in their own colours, the average, the difference in mV and the balancing state.
- Temperatures and status — sensors T1 – T5 and the MOSFET, charging and discharging MOSFET, state of health (SOH), runtime. Active alarms appear in a red banner.
- BMS protection settings — 29 values in six groups: cell voltage protection, pack voltage, current protection, temperature protection, balancing and other. Read-only.
- Weather and electricity — the forecast with a PV yield estimate and spot prices, if you have them switched on in the gateway's settings.
Download JK-BMS Overview (.zip)
Extract the jkbms-overview/ folder into config/www/.
Settings → Dashboards → ⋮ → Resources → Add resource: URL /local/jkbms-overview/jkbms-overview-card.js?v=1, type JavaScript module. When you replace the file later, raise the ?v= number.
Settings → Dashboards → Add dashboard → New dashboard from scratch, open it → ⋮ → Edit in YAML and paste the contents of jkbms-overview-dashboard.yaml (or just this). Save.
views:
- title: JK-BMS Overview
type: panel
cards:
- type: custom:jkbms-overview-cardThe tabs “Device 00” to “Device 15” open the packs configured in the integration; the first one that has data is shown when the dashboard opens. The charts use Home Assistant's history and statistics, so they start filling a few minutes after the integration is added. Current and power carry the gateway's sign: + charging, − discharging. All three dashboards carry a “Made by: www.jkbms.sk” link — JK-BMS Overview at the top right, the automatic and the static one as the last card of each tab.
Battery colour levels
Dashboards A and B colour the state of charge, the pack voltage and every cell by the same LiFePO4 levels, and include a legend card with this table. Pack voltage = cell voltage × cell count (16S here).
| Level | SOC | Cell | Pack (16S) |
|---|---|---|---|
| ● Critical | < 10 % | < 2.90 V | < 46.4 V |
| ● Low | 10 – 25 % | 2.90 – 3.10 V | 46.4 – 49.6 V |
| ● Fair | 25 – 50 % | 3.10 – 3.20 V | 49.6 – 51.2 V |
| ● Good | 50 – 80 % | 3.20 – 3.40 V | 51.2 – 54.4 V |
| ● Full | 80 – 100 % | 3.40 – 3.55 V | 54.4 – 56.8 V |
| ● Overvoltage | — | > 3.55 V | > 56.8 V |
The SOC and pack-voltage gauges are stock Home Assistant cards. The cell bars need sensor-bar-card-plus and the power chart apexcharts-card — install both via HACS → Frontend (search by name → Download).
Sensors going "Unavailable" briefly — that's normal
If some sensors occasionally show "Unavailable" for a few seconds and then come back with a real value, that's not a bug in the integration or dashboard — it's exactly what happens when the device itself briefly fails to read data from the BMS over the RS485 bus (e.g. temporary interference). The integration deliberately never shows a stale or made-up value. If sensors are permanently unavailable, that's a different, real problem — see Troubleshooting below.
Troubleshooting
- License error while adding: open the device's own web page and activate its license there first (Licencia → Overiť), then try again.
- "Cannot connect" while adding: double-check the IP/host and
that the device is actually reachable from Home Assistant — try
opening
http://<device-ip>/api/infoin a browser on the same network. - Sensors are permanently unavailable, not just occasionally: check the "License verified" and "Last error" diagnostic sensors under the device in Home Assistant, and that the gateway is actually powered on and reachable.
- Everything works at home, but Home Assistant does not load away from your home WiFi (on mobile data): the integration and Home Assistant run only inside your network. How to get into it from outside over a VPN is described in the Remote access guide.
- Missing the "Edit in YAML" option: a default, auto-generated dashboard doesn't offer it until you've edited it once or created a new one from scratch.
DEYE Web Gateway in Home Assistant
The DEYE Web Gateway (DEYE SUN-xK-SG04LP3 / SG05LP3 three-phase hybrid inverters) has its own integration and a ready-made dashboard in the same look as the gateway's “Overview” tab: the house with animated energy flows, daily production and consumption, charts, weather forecast, spot electricity prices and the AC connectors per phase. The same requirements apply as above — an activated license on the gateway and the same local network.
What the dashboard shows
- Four main tiles — PV production (now, today, total, PV1 and PV2), house consumption, battery (state of charge, charging or discharging) and grid (import and export today).
- The house with energy flows — PV, grid, house, battery and the GEN port (generator, smart load or micro-inverter) with animated dots. The direction shows where the energy goes; the number and speed of the dots grow with the power.
- Daily production and consumption — how much of the production went to the house, the grid and the battery, and how much of the consumption came from solar, the grid and the battery — in kWh and in percent.
- Four charts of today — PV power, battery level, house consumption and grid power (import up, export down).
- Weather forecast — for the coming days with sunshine hours, temperatures and a yield estimate in kWh from your PV peak power (kWp).
- Electricity — the current spot price (OKTE for Slovakia, OTE for Czechia) rated cheap / average / expensive, the buy and sell price with your fees and VAT, today's import and export in money, and a chart of today and tomorrow.
- Three tables — production and consumption today, battery status (power, voltage, current, temperature, kWh charged and discharged) and inverter output (phases, frequency, temperatures, grid voltage).
- AC connectors per phase — grid, load, GEN port and inverter output — voltage, power and current on L1, L2 and L3.
- Inverter state — online or offline, the run state and active warnings and faults.
The integration also creates about 80 entities (power, energy, battery, phases, temperatures) that you can use in automations and in the Energy dashboard.
1. Integration
Download the DEYE integration (.zip)
Extract the deye_web_gateway/ folder into config/custom_components/ and restart Home Assistant (Settings → System → Restart).
Settings → Devices & services → Add Integration, search for “DEYE Web Gateway” and enter the gateway's IP address (or deye.local) and port 80. A “DEYE” device appears with power, energy, battery, per-phase and temperature sensors. The energy counters also work in the Energy dashboard.
2. Dashboard
Download the DEYE dashboard (.zip)
Extract the deye-overview/ folder (the files deye-overview-card.js and bg.jpg) into config/www/.
Settings → Dashboards → ⋮ → Resources → Add resource: URL /local/deye-overview/deye-overview-card.js?v=1, type JavaScript module. When you replace the file later, raise the ?v= number.
Settings → Dashboards → Add dashboard → New dashboard from scratch, open it → ⋮ → Edit in YAML and paste the contents of deye-dashboard.yaml (or just this). Save.
views:
- title: DEYE Gateway
type: panel
cards:
- type: custom:deye-overview-card- Gateway IP address — Settings → Devices & services → DEYE Web Gateway → ⋮ → Reconfigure and enter the new address. The entities, their history and your dashboards stay unchanged, even when you replace the gateway with another unit. The Configure button (gear icon) only changes the poll interval.
- House number and licence plate — on the gateway's page: Settings → Web server settings → House and car. The house number takes up to 7 characters, the plate up to 12; an empty field is not drawn on the scene. The same section holds the forecast location, the PV peak power (kWp) and the spot prices.
- House photo — overwrite
config/www/deye-overview/bg.jpgwith your own 16:9 photo and raise the?v=number of the resource. The labels and flow lines are placed for the original photo and may not fit another one.
The card finds its entities by itself, nothing to edit. The weather forecast, location, PV peak power (kWp), spot prices and fees, house number and licence plate come from the gateway's own settings (Web server settings on its page) — a change shows up in Home Assistant within 10 minutes, at once after ⋮ → Reload on the integration. The charts use Home Assistant's statistics, so they start filling a few minutes after the integration is added. Signs are the gateway's: battery power + = discharging, grid power + = importing. The top right corner carries a “Made by: www.jkbms.sk” link.