JK-BMS RS485 Home Assistant Addon

domosimple · June 12, 2025, 8:38pm

JK-BMS RS485 Home Assistant Addon

Home Assistant add-on module for managing JK-BMS via Node-RED and Modbus RS485.

Features

Configuration interface for JK-BMS software settings
Modbus RS485 communication
Control panel integrated into Home Assistant
Multi-BMS support
MQTT integration (open to other software)

Screenshot

Configuration

Available parameters

path: The path to the USB port where the Serial port RS485 adapter is connected to your machine
nb_jkbms: Number of JK BMSs to control (from 1 to 15)
mqttaddress: The IP address or DNS name of your MQTT broker.By default, this will be the internal address of HAOS.
mqttport: Port number of the MQTT broker
mqttuser: User name for MQTT authentication
mqttpass: Password for MQTT authentication. Put it in quotation marks

–» Complementary and pre-configured Dashboard: «–

You can obtain two pre-configured dashboards that you can import into your Home Assistant home automation system.
This can save you several hours of work in formatting the data by yourself.
Have a look here

Installation

You can add the repository automatically by following this:

Via the add-on shop

Add this repository in Home Assistant: https://github.com/jean-luc1203/jkbms-rs485-addon
Install the “Smartphoton_JKBMS RS485 Home Assistant Addon”
Configure the parameters according to your installation
Start the module

Manual installation (for development)

Clone this repository in the /addons/ folder of your Home Assistant installation
Reload the add-ons
Install and configure

Use

BMS appear in MQTT devices

BMS-in-MQTT-devices

Entities created

JKBMS-entities

Authors & contributors

For the creation of the module under HAOS, I drew inspiration from Nolak’s work for smartphoton
as well as assistance from various AI.
The Node Red flow are from me JLM.

Support

To report problems or request features, use GitHub issues.

License

MIT License

LawrenceH · June 12, 2025, 10:10pm

Great tool! I’m running HA in Hyper-V, which doesn’t support USB passthrough. Do you think using USB/IP to connect the RS485 USB adapter to HA would work?

domosimple · June 13, 2025, 6:27pm

Thank you @LawrenceH for your comment.

Which interface are you referring to?

At the moment, my code accesses a serial port, which is one of the USB ports. If you are referring to an RS485/IP gateway, this has not been implemented yet. I have done this in my other module smartphoton. Among other things, I use Elfin modules.

If I receive several requests, I can add the code to manage the IP addresses and ports of a gateway, thereby eliminating the need to go through the serial port.

LawrenceH · June 13, 2025, 9:27pm

Yeah, I mean the serial port on the USB adapter. Since Hyper-V can’t pass USB devices from Windows, you need something like USB-over-IP to connect it to HA, like using USB/IP.

domosimple · June 13, 2025, 10:21pm

In my case, I use these inexpensive gateways which give me great satisfaction. Is this what you have in mind?

The rs485 version, then.

LawrenceH · June 14, 2025, 6:02am

Yeah, the USB version

domosimple · June 17, 2025, 11:35am

I am currently adding the ability to connect an RS485-IP gateway of this type. I had it lying around somewhere. This means you can have the PC anywhere and no longer need to connect a physical USB port. It’s starting to work. In a few days, I will make this version available on my GitHub.

This is the one i’m using

domosimple · June 21, 2025, 4:11pm

The version with IP Gateway ethernet-wifi connection is now available on Github

LawrenceH · June 27, 2025, 3:04pm

Great, thanks alot!!

domosimple · July 8, 2025, 4:01pm

It is now possible to leave a BMS in Master mode.

You can use it with your inverter, which requires one of the BMSs to be in the Master position, i.e. 0000 on the switches.
Like Deye, Victron …

This involves setting all 4 small switches to the down or 0000 position.

Parameters can no longer be modified in this mode !

In this configuration, the BMS will query the other BMSs if any are connected to the RS485 bus.

The BMS will then broadcast the information it has retrieved cyclically every 5 seconds. This information will be read by this add-on

domosimple · July 17, 2025, 8:50pm

CAN broadcasting

Here is the latest development (July 2025). CAN bus support is now fully functional

This is the second RJ45 connector from the left. You must first select the CAN protocol to option 006 - (500k) V2.0 in the jkbms application.

You will need to purchase a CAN adapter. Not all adapters are compatible with Home Assistant.

It should not appear under ttyUSBx in the hardware list. However, in a HAOS terminal, run the command: ip link If you see an interface named can0, it will work.

Install the module, then before launching it, go to configuration and set the CANbus_usage variable to true. Also enter the MQTT parameters.

The jkbms continuously broadcasts a certain amount of data that will be sent directly to HAOS under the MQTT device section (must be installed and functional before this module).

The device should appear under the name CANbus-1. The data are inside.

In CAN mode, only reading is possible. No modifications are possible.

This is possible with the rs485 bus if necessary.

Caution: Be sure to use the jkbms protocol and not victron, pylontech, or any other. The data is refreshed every 5 seconds

Imanol82 · September 14, 2025, 5:52pm

Good job!

I’m using esp32 project but I’m going to try this one.

One question, I’m useind a tcp-ip gateway, poe. And I’m receiving this error:

What folder have I to use, if I’m not using USB?

Thank you very much!

domosimple · September 15, 2025, 2:04pm

Merci.

Then it must not be passing through the USB port. A bug?
Have you configured the module correctly?
I suggest you uninstall the entire module and reinstall it.
I’ve just released a new version. There’s a way of getting logs of the conversation between the JK and the HAOS.
Can you set this switch to On and tell me how it looks.
Take a good look at the module logs, and take a screenshot if necessary.
It would be nice to open an issue on Github to continue.

Macrisu · September 23, 2025, 4:09am

I’m using HA on an Rpi5 supervised installation.
Can I access the USB port?

/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0

I’ve tried your integration. I can see on the host the adapter, but I’m not sure about the RS-485 wiring.

Welcome to Node-RED
===================
23 Sep 07:05:07 - [info] Node-RED version: v4.1.0
23 Sep 07:05:07 - [info] Node.js  version: v22.16.0
23 Sep 07:05:07 - [info] Linux 6.12.34+rpt-rpi-v8 arm64 LE
23 Sep 07:05:07 - [info] Loading palette nodes
23 Sep 07:05:08 - [info] Settings file  : /etc/node-red/config.js
23 Sep 07:05:08 - [info] Context store  : 'default' [module=localfilesystem]
23 Sep 07:05:08 - [info] User directory : /config/smartphoton_jkbms/
23 Sep 07:05:08 - [warn] Projects disabled : editorTheme.projects.enabled=false
23 Sep 07:05:08 - [info] Flows file     : /config/smartphoton_jkbms/flows.json
23 Sep 07:05:08 - [info] Server now running at http://127.0.0.1:1891/
23 Sep 07:05:08 - [warn] Encrypted credentials not found
23 Sep 07:05:08 - [info] Starting flows
23 Sep 07:05:08 - [info] Started flows
23 Sep 07:05:08 - [error] [serialconfig:6e1abcbcc6ebb714] serial port /dev/JKBMS error: Error: Error: No such file or directory, cannot open /dev/JKBMS
23 Sep 07:05:08 - [info] [mqtt-broker:56f7b2737cce493b] Connection failed to broker: mqtt://core-mosquitto.local.hass.io:1883
23 Sep 07:05:09 - [info] [function:traitement des variables] Champ 'gateway_ip_port' traité: 192.168.1.100:5000
23 Sep 07:05:09 - [info] [function:traitement des variables] Champ 'mqttadresse_port' traité: 192.168.1.192:1883
23 Sep 07:05:09 - [info] [function:traitement des variables] Champ 'cloud_broker_adress_port' traité: bca204074b374abvcdefbae5b858.s1.eu.hivemq.cloud:8883
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'path' = /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'nb_jkbms' = 6
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'use_gateway' = false
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'gateway_ip' = 192.168.1.100
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'gateway_port' = 5000
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'communication_debug' = true
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'bms_broadcasting' = true
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'CAN_bus_usage' = false
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'mqttadresse' = 192.168.1.192
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'mqttport' = 1883
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'mqttuser' = user
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'mqttpass' = passwd
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_broker' = false
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_broker_adress' = bca204074b374abvcdefbae5b858.s1.eu.hivemq.cloud
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_broker_port' = 8883
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_broker_user' = username
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_broker_pass' = password
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_HA_long_term_access_tokens' = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI1MzIyNGRkZWIxZGU0N2NiYWRhMzk0YzRjZTJmZGI4OCIsImlhdCI6MTc1ODYwMDE5OCwiZXhwIjoyMDczOTYwMTk4fQ.MNcQlRPV7waivrzlqF3NzxOnr0r1g82e6gjK1r0cXcY
23 Sep 07:05:10 - [info] serial port /dev/JKBMS closed
23 Sep 07:05:10 - [info] [serialconfig:6e1abcbcc6ebb714] serial port /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 opened at 115800 baud 8N1
23 Sep 07:05:10 - [info] [mqtt-broker:56f7b2737cce493b] Connected to broker: mqtt://192.168.1.192:1883
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_broker_pass' = password
23 Sep 07:05:09 - [info] [function:traitement des variables] Variable globale 'cloud_HA_long_term_access_tokens' = xxxxx
23 Sep 07:05:10 - [info] serial port /dev/JKBMS closed
23 Sep 07:05:10 - [info] [serialconfig:6e1abcbcc6ebb714] serial port /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 opened at 115800 baud 8N1
23 Sep 07:05:10 - [info] [mqtt-broker:56f7b2737cce493b] Connected to broker: mqtt://192.168.1.192:1883

domosimple · September 23, 2025, 2:08pm

Everything seems fine with the USB port connection to the HA container.
Could you enable the debug switch and check what’s in the module log?
Otherwise, did you reverse A and B?
And no GND connected.

ClarreJu · September 23, 2025, 7:13pm

Hi!
Thank you so much for a great add-on!
One problem, though: I don’t seem to be able to update parameters. I have tried to flip the charge switch with no change on the BMS side. I also change one of the overcurrent time values with no change on the BMS.

The log looks like this:

23 Sep 21:04:22 - [info] [debug:port used] /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0

23 Sep 21:04:22 - [info] [debug:host used] 192.168.1.100

23 Sep 21:04:22 - [info] [debug:JK-BMS response: ]

<Buffer 04 10 16 20 00 01 02 00 00 e9 a1>

Input value: False

Converted to: false

Trame générée: [

1, 16, 16, 112, 0, 2,

4, 0, 0, 0, 0, 57,

75

]

Message payload: False

Type of payload: string

23 Sep 21:04:23 - [info] [debug:port used] /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0

23 Sep 21:04:23 - [info] [debug:host used] undefined

23 Sep 21:04:23 - [info] [debug:JK-BMS response: ]

<Buffer 05 10 16 1e 00 01 02 00 00 e0 ef>

I have set the pins on the BMS to 1 (first up, the rest down) and have bms_broadcasting: false in settings.
Any idea what I’m doing wrong?

All the best
C-H

domosimple · September 25, 2025, 10:55am

Hello, would it be possible to open a ticket on the module’s GitHub?
I am currently very busy with a new module. However, I will do my best to resolve this issue.

Jorge_Matias · September 25, 2025, 7:56pm

Dear, new module? What’s news?

domosimple · September 27, 2025, 7:41am

Yes, a new module that I hope will be useful. It should enable data exchange between HA and the Net-cloud. All this without the need for a VPN, reverse proxy, or other tools. Communications will be encrypted. 4G connection planned. Client with esp32, PC, PLCs, etc.

domosimple · September 30, 2025, 11:39am

It’s ready.
This is the very first functional version of the synchronization module for Home Assistant entities exported to an MQTT cloud broker and, conversely, an isolated client that can send topics to this broker. This will trigger the automatic creation of entities in Home Assistant.
All you need to do is send an auto-discovery topic and a status topic.
Communications are TLS-encrypted.

For example, an ESP32 that manages sensors and actuators in a second home can send its information to your Home Assistant at home via its built-in 4G connection. No other physical architecture is required.

Another case: one or more PLC Schneider devices by exemple (which use MQTT) can easily send their data externally.
I don’t yet know if this is feasible in practice.

Basically, any MQTT client can send its values to the cloud and then simply used in HA for storage in the DB and creation of graphs, automations, or other utilities