Feature: Add new battery provider JK BMS via CAN bus #2113

mrwillem · 2025-07-14T08:30:33Z

This is a basic CAN Driver for JK BMS which don't support other CAN Protocols like the Pylontech or others.
It will be implemented according to the specifications found here.
http://www.jk-bms.com/en/Upload/2023-12-05/1559288117.pdf

The driver is still in alpha stadium. Not all identifiers are implemented now.

According to the Datasheet, JK has at least two protocol Versions, the 1.0 and the 2.1 which are backward compatible.
The 2.1 version has more features like reading single cell voltage or more detailed temperature readouts.

With this driver it would be possible to have more than one Battery because the CAN Message Identifier is related to the setting "Device Addr.:"
But this is not implemented now.

The driver was cloned from the pylontech driver with some modifications for the hardware interface. The CAN Interface can be configured for 250 kBits CAN Speed by adding the statement "can_type": 2 to the pin description in the hardware config. "battery": { "rx": 13, "tx": 14, "can_type": 2 } sets the speed to 250 kBits. Any other value will set it to 500 kBits which was previously the default.

The number of cells for the battery pack can be configured. Then the voltage of the individual cells will is displayed in the overview. Implemented most JK BMS Can Identifiers. Cleaning up the code. Removed some leftover code from the originating pylontech driver.

…f the manufacturer. The values for _chargeVoltage und _chargeCurrentLimitation are in big endian format. The function ReadBigEndianUnsignedInt16 was implemented to read the data correctly.

… in the battery admin menu. The version 1 CAN Protocol supports a 10 mV accuracy in battery voltage. With version 2 of the CAN Protocol, the accuracy can be higher because the voltages of each individual cell is reported. The pack voltage can be calculated by summing up the voltages of each cell.

AndreasBoehm

Congratulations to your first pull request on this project! 🚀

You mentioned that this is a alpha version. What do you mean by that?
I don't feel confident merging a new battery provider that is marked as alpha version.

I added some comments and would ask to you do some cleanup please.
Please remove commented code and superfluous new lines.

AndreasBoehm · 2025-07-14T11:57:46Z

.github/workflows/test_build.yml

@@ -0,0 +1,103 @@
+name: OpenDTU-onBattery Test Build


Do we need this new workflow? based on the commit it looks like it was added by accident.

AndreasBoehm · 2025-07-14T11:58:15Z

README.md

 print yourself.

 ### Ready-To-Use
-


Please revert the changes to the README. By looking at the commits it looks like those changes got introduced by accident.

AndreasBoehm · 2025-07-14T12:00:08Z

webapp/package.json

    "vite": "^6.3.5",
    "vite-plugin-compression": "^0.5.1",
    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vite-plugin-vue-devtools": "^7.7.6",


Whats the purpose of the devtools?
As it is unrelated to the JK BMS CAN support i would suggest to create a new pull-request to include it, if needed.

AndreasBoehm · 2025-07-14T12:01:13Z

webapp/src/locales/fr.json

        "SerialInterfaceTypeTransceiver": "RS-485 Transceiver on MCU",
        "JbdBmsConfiguration": "JBD BMS Settings",
+        "JkBmsPackConfiguration": "JK BMS pack configuration",
+        "NumberOfCells": "Number of Cells in this battery pack",


You can revert the changes in the french locales file as there will be a fallback to the english file if strings are not present. And because the strings are not translated they are simply duplicates.

AndreasBoehm · 2025-07-14T12:01:39Z

webapp/vite.config.ts


 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
+import vueDevTools from 'vite-plugin-vue-devtools'


See other comment about the addition of the devtools.

AndreasBoehm · 2025-07-14T12:05:47Z

include/battery/jkbmscan/Stats.h

+public:
+    void getLiveViewData(JsonVariant& root) const final;
+    void mqttPublish() const final;
+    // bool getImmediateChargingRequest() const { return _chargeImmediately; } ;


Is this supported? If not, please remove it

AndreasBoehm · 2025-07-14T12:06:20Z

platformio_override.ini

 ; then execute ls /dev/tty* again and check which device was added
-;monitor_port = COM4
-;upload_port = COM4
+monitor_port = /dev/ttyACM2


Please revert the changes in this file

AndreasBoehm · 2025-07-14T12:09:54Z

webapp/src/views/BatteryAdminView.vue

                                batteryConfigList.provider == 4 ||
-                                batteryConfigList.provider == 5)
+                                batteryConfigList.provider == 5 ||
+                                batteryConfigList.provider == 8)


As the JK BMS does not report a discharge current limit, at least you are not ever setting in your provider implementation, it should not be part of this list.

AndreasBoehm · 2025-07-14T12:10:56Z

webapp/src/views/BatteryAdminView.vue

+                    :postfix="'Cells'"
+                    wide
+                />
+                  <InputElement


Can we make this a dropdown please that shows supported versions only?
Otherwise people might put in arbitrary numbers and wonder why its not working.

Do we even need to configure the protocol version?

According to your PR description versions are backward compatible and we will simply get more and better data?

The 2.1 version has more features like reading single cell voltage or more detailed temperature readouts.

src/battery/CanReceiver.cpp

mrwillem · 2025-07-15T06:53:43Z

Congratulations to your first pull request on this project! 🚀

You mentioned that this is a alpha version. What do you mean by that? I don't feel confident merging a new battery provider that is marked as alpha version.

Thank your for the revision of the pull request. I actually never contributed to any GitHub Project. So I wanted to see if it is going in the right direction.
You are absolutely right and the code has to be cleaned up. I should have done this before starting the pull request.

By alpha version I mean, that not all CAN Identifiers are correctly implemented now. I am stuck a little bit on the error reporting functions. I have generated two errors (undervoltage and overcurrent) but the Values I got were a little unexpected. So I have to revise this part of the code.

Regarding the different protocol versions. You are right. I also thought about detecting this automatically.
The V1 protocol uses 11 Bit CAN identifiers whereas the V2.1 protocol uses 29 Bit identifiers but also sends the V1 11 Bit identifiers. So one could simply detect whether 29 Bit identifiers are send and use the newer Protocol.

github-actions · 2025-08-07T04:36:29Z

This pull-request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

github-actions · 2025-09-26T04:12:33Z

This pull-request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

mrwillem and others added 10 commits July 11, 2025 00:46

Adding translations for the Web interface in the battery admin module.

feecee1

Changing endianess of two Parameters according to the specification o…

9a61901

…f the manufacturer. The values for _chargeVoltage und _chargeCurrentLimitation are in big endian format. The function ReadBigEndianUnsignedInt16 was implemented to read the data correctly.

Create test_build.yml

3c12d2d

Delete test_build.yml

8fb88ac

create test_build action

57af4fa

set unique name for test_build action

1e488f4

move documentation to opendtu-onbattery.net

010a69d

AndreasBoehm requested a review from Copilot July 14, 2025 11:57

This comment was marked as outdated.

Sign in to view

AndreasBoehm changed the title ~~Feature: Add CAN bus support for JK BMS that don't support other CAN Protocols~~ Feature: Add new battery provider JK BMS via CAN bus Jul 14, 2025

AndreasBoehm requested changes Jul 14, 2025

View reviewed changes

AndreasBoehm added the changes requested label Jul 23, 2025

github-actions bot added the stale label Aug 7, 2025

github-actions bot removed the stale label Sep 4, 2025

Merge branch 'development' into development

ef48663

github-actions bot added the stale label Sep 26, 2025

Uh oh!

Feature: Add new battery provider JK BMS via CAN bus #2113

Are you sure you want to change the base?

Feature: Add new battery provider JK BMS via CAN bus #2113

Uh oh!

Conversation

mrwillem commented Jul 14, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

AndreasBoehm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mrwillem commented Jul 15, 2025

Uh oh!

github-actions bot commented Aug 7, 2025

Uh oh!

github-actions bot commented Sep 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants