JK-BMS wired management (Home Assistant Add-on)

[Ramses]

There are many solutions to monitor the JK BMS, but most of them have limitations or are not easy to implement.
If you have multiple batteries, there are problems with BT and the limited processing power of the devices (ESP8266 or ESP32).

This Home Assistant Add-on is easy to implement, and the processing power of the Raspberry Pi 4/5 is usually plenty for 15 batteries.

You need:
- Device running HA OS/Supervised (Rpi, HA official hardware, PC etc.)
- a working MQTT server in the network (with auth); external or included in HA.
- RS485-USB adapter or RS485-TCP adapter + cable (or the original JK Cable)

For the cable, use an ordinary Ethernet Cable and connect the small wires to the A/B terminals.
A -> Orange
B -> White + Orange
GND -> not used


Is the same cable that you use to connect to the BMS with the PC app, or for the firmware upgrade.



Links:

Project Github Page
Developer Forum
Paid Dashboards models (optional)

* I'm not affiliated with the project; I'm just an user.

 

[ricsun]

Hi Ramses, is it possible to show your YAML config... specifically the first line "JK-BMS- serial port path". where does one find this?
I've got it all wired but no data flowing.
Thx

 

[Ramses]

I have Victron, so this is my YAML config

jkbms_path: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
jkbms_count: 6 # I have 6 batteries
use_gateway: false
gateway_ip_port: 192.168.1.100:5000
communication_debug: false
bms_broadcasting: true # this is as I have a master
CAN_bus_usage: false
mqttadresse_port: 192.168.1.192:1883 #myMQTT external server
mqttuser: user
mqttpass: password
cloud_broker: false
cloud_broker_adress_port: bca204074b374abvcdefbae5b858.s1.eu.hivemq.cloud:8883
cloud_broker_user: username
cloud_broker_pass: password
cloud_HA_long_term_access_tokens: xxxxxxx # create and use a token

For the USB, it differs on each installation, but it is easy to find:

Mine is: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
ssh to your machine running Home Assistant and run:

ls /dev/serial/by-id/

You will see something with "USB_serial".
Copy the name and add it to this path ***

/dev/serial/by-id/****

 

[Ramses]

Here is my quick look control panel for the batteries.
You can use it, but:
- You need to modify your number of batteries (I have 6)
- delete the Victron Shunt info card or edit it (I'm using the Victron integration) for your sensors.

 

[ricsun]

Thx Ramses, I think I'm halfway there now...what are the 4 asterisks denoting after /dev/serial/by-id/ . if I copy/paste your code, it returns; no file or directory.
I'm also using Victron w/7 battery (only 5 are JK tho)

 

[Ramses]

*** is the name of your device, as resulted from the command.

ls /dev/serial/by-id/

On what device are you running Home Assistant?

So, what is the result of running this command via SSH ?

ls /dev/serial/by-id/

 

[ricsun]

As it turns out, the dongle was not doing its job. I had a spare, plugged it in and all is good.
I'm running bare metal on a B-Link NUC.
Thx for taking the time to help out.
Regards

 

[HiwaOC]

I received an update today my jks are connected to solar assistant pi and mqtt to ha
i Will try if v19 works now.

 

[Ramses]

v19 works with some erros in logs...

2025-10-17 08:54:09.995 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_6_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:09.997 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_6_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:14.374 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:14.375 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:14.376 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:14.380 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:14.381 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_master_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:15.269 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:15.270 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:15.270 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:15.276 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:15.277 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_2_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:15.709 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:15.710 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:15.711 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:15.715 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:15.716 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_3_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:16.149 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:16.151 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:16.151 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:16.155 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:16.156 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_4_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:16.591 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_5_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:16.592 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_5_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:16.593 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_5_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:16.596 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_5_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:16.597 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_5_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:17.030 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_6_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:17.031 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_6_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:17.032 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_6_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:17.035 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_6_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:17.036 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_6_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:21.415 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:21.417 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:21.418 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:21.421 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_master_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:21.422 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_master_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:22.310 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:22.311 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:22.312 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:22.316 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_2_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:22.317 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_2_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:22.749 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:22.750 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:22.751 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_discharge_overcurrent_protection_delay: 300 (range 0.0 - 100.0)
2025-10-17 08:54:22.756 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_3_bms_total_battery_capacity_ah: 314 (range 0.0 - 100.0)
2025-10-17 08:54:22.757 WARNING (MainThread) [homeassistant.components.mqtt.discovery] Received message on illegal discovery topic 'homeassistant/number/BMS_3_device/ device_address/config'. The topic contains non allowed characters. For more information see https://www.home-assistant.io/integrations/mqtt/#discovery-topic
2025-10-17 08:54:23.186 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_max_charge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:23.188 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_max_discharge_current: 150 (range 0.0 - 100.0)
2025-10-17 08:54:23.189 ERROR (MainThread) [homeassistant.components.mqtt.number] Invalid value for number.bms_4_bms_discharge_overcurrent_protection_delay: 300 (range 0

 

[Tiger_one]

There are many solutions to monitor the JK BMS, but most of them have limitations or are not easy to implement.
If you have multiple batteries, there are problems with BT and the limited processing power of the devices (ESP8266 or ESP32).

This Home Assistant Add-on is easy to implement, and the processing power of the Raspberry Pi 4/5 is usually plenty for 15 batteries.

You need:
- Device running HA OS/Supervised (Rpi, HA official hardware, PC etc.)
- a working MQTT server in the network (with auth); external or included in HA.
- RS485-USB adapter or RS485-TCP adapter + cable (or the original JK Cable)

For the cable, use an ordinary Ethernet Cable and connect the small wires to the A/B terminals.
A -> Orange
B -> White + Orange
GND -> not used
View attachment 332692

Is the same cable that you use to connect to the BMS with the PC app, or for the firmware upgrade.

View attachment 332708

Links:

Project Github Page
Developer Forum
Paid Dashboards models (optional)

* I'm not affiliated with the project; I'm just an user.

Thanks for the info and help. Me and my AI buddies took all day to get this running! I'm using RS485 to USB cable (works with PC monitor also). The key for me was finally getting the configuration correct. I'm using Dell optiplex 3080 micro for HA, just migrated from RPI.

/dev/ttyUSB1 for JKBMS PB1A16S10P (settings, system, hardware to get USB1 path)
My JKBMS RS485 Wired addon configuration file:

jkbms_path: /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_B002JIET-if00-port0
jkbms_count: 1
use_gateway: false
gateway_ip_port: 192.168.1.100:5000
communication_debug: true
bms_broadcasting: false
CAN_bus_usage: false
mqttadresse_port: core-mosquitto.local.hass.io:1883
mqttuser: mqttBoss
mqttpass: ********

Now, I am editing the dashboard to change french to english and add Sol-ark entities.
P.S. I also have mqtt working for DIYBMSv4 and JKBMS.

 

[Ramses]

Can you share the dashboard?

 

[Tiger_one]

Can you share the dashboard?

I donated $10 to the owner and he supplied 5 items. Couple of templates, two dashboards and some instructions. The link is in addon documentation for JKBMS Wired.

P.S. He also uses BAR CARD which is obsolete now. So that needs to be replaced/deleted in dashboard.

 

[Ramses]

Fixed by adding as a custom repository in HACS this (Dashboards)

GitHub - spacerokk/bar-card: Customizable Animated Bar card for Home Assistant Lovelace

Customizable Animated Bar card for Home Assistant Lovelace - spacerokk/bar-card

github.com

I have no idea how to use this part of the instructions.

 

[HiwaOC]

All works now

 

[Ramses]

Nice; can you share the code?

 

[Ramses]

I have Victron + 6 batteries.
One is Master (bms_master), the others are slaves (bms_1, bms_2 , bms_3 etc)

This is what I use for a quick peek..

1. Create a new dashboard called JK
2. Add the attached code
3. Visually edit for your number of batteries.

 

[HiwaOC]

used perplexity to generate

vertical-stack	Main container organizing all cards
custom:stack-in-card	Groups and formats blocks without margins/borders	Used for clean layout
grid	Displays summary metrics (voltage, current, etc.)	2 columns
markdown	Text-based display with color and conditions	Used for cell voltages
entities	Control switches for BMS functions	Separate for Master and Slave

[th]
Card Type

[/th][th]
Purpose / Content

[/th][th]
Notes

[/th]

 

[HiwaOC]

cards used

The attached file JK-1.txt contains a Home Assistant Lovelace dashboard configuration using various cards arranged in multiple vertical and grid stacks. The main card types used are:

1. custom:stack-in-card – A wrapper used to group other cards without extra margins, shadows, or background styling, keeping the design tight.
2. grid card – Used with columns: 2 to display two-column layouts for sensor groups and voltage cells.
3. vertical-stack card – Groups multiple sections of cards vertically, typically combining sensor blocks and charts.
4. markdown card – Displays text with HTML-style formatting to show colored and styled values (for SOC, cell voltages, temperatures, etc.).
5. custom:mini-graph-card – Plots current (A) and power (W) with color thresholds (green ≤ 10, amber ≤ 100, red > 500) for both BMS Master and BMS1 data.

In summary, your dashboard layout primarily uses Markdown cards for textual data, Mini Graph Cards for dynamic graphs, and Stack‑in‑Card/Grid/Vertical Stack components to organize them into clean, compact visual sections for both BMS units.

 

[HiwaOC]

finally, something came out color changes when its charging