JK BMS
SK EN DE

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.

Important: this integration only works on your local network — Home Assistant must be on the same WiFi/LAN as the device itself. Monitoring from anywhere without a shared network is a separate, not-yet-built idea for the future.

What you'll need

1. Download and install the integration

1

Download the integration files

Download the integration (.zip)

The zip contains a jkbms_web_gateway/ folder, ready in exactly the shape Home Assistant expects.

2

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.

3

Restart Home Assistant

Settings → System → Restart.

4

Add the integration

Settings → Devices & services → Add Integration and search for "JK BMS Web Gateway".

5

Enter the device's address

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.

Once it succeeds, two new devices appear: "JK BMS Gateway" (firmware, IP, license, CAN/NTP status, and a "Rescan bus" button) and "JK BMS" (your battery — voltage, current, power, individual cells, temperatures, status).

Have more than one battery on the same RS485 bus? The integration automatically discovers every connected battery pack (addresses 0–15) and creates a separate device for each one. After wiring in another pack, just press the "Rescan bus" button on the "JK BMS Gateway" device — the new one appears without restarting Home Assistant. Your existing entities stay unchanged.
⚠️ Important with multiple packs: never use address 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 the dashboard

The ready-made dashboard is included in the download above and also lives directly in the project's repository (dashboards/jkbms-dashboard.yaml). You can use it two ways:

1

As a new tab in a dashboard you already have

Open that dashboard → ⋮ (top right) → Edit dashboard → ⋮ → Edit in YAML. Under the views: list, paste in the - title: JK-BMS block (from that line down to the next - title:) as one more entry. Save.

2

Or as a brand-new dashboard

Settings → Dashboards → Add dashboard → New dashboard from scratch → ⋮ → Edit in YAML → paste in the whole file in place of the placeholder content. Save.

If "Edit in YAML" isn't offered on your default dashboard, that's normal — Home Assistant only offers it once that dashboard has been taken over/edited once, or use a new dashboard from scratch, which offers it right away.

The dashboard assumes a 16-cell pack. If your device has a different cell count, adjust the sensor.jk_bms_cell_<n>_voltage / _resistance rows accordingly.

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