├── .github └── workflows │ ├── ci.yaml │ └── matchers │ ├── ci-custom.json │ ├── clang-tidy.json │ ├── gcc.json │ ├── lint-python.json │ └── python.json ├── README.md ├── docs ├── 2007290932_HK-HK32F103C8T6_C482563.pdf ├── BMS-CAN Communication protocol.pdf ├── Communication protocol between monitoring platform and BMS.pdf ├── JK-Jiabaida_communication_protocol_v4.0.pdf ├── Lithium battery smart bms instructions.pdf ├── RS485 Communication example.pdf ├── RS485-english-OBSOLETE.pdf ├── SMA CAN Protocol Mapping.pdf ├── SMA CAN protocol.pdf ├── btsnoop_hci_jk-b1a20s15p_hw10xw_sw1007.log ├── btsnoop_hci_jk-b2a16s_hw30_sw330.log ├── btsnoop_hci_jk-b2a16s_hw30_sw330_cmds.log ├── btsnoop_hci_jk-bd6a17s6p_hw72_sw710h.log ├── btsnoop_hci_jk-bd6a24s10p_hw8x_sw806g.log ├── display-port.md ├── jk-bms-manual-1520084771.pdf ├── jkbms-ble-connected-capture.zip └── protocol-design.md └── firmware └── Readme /.github/workflows/ci.yaml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: # yamllint disable-line rule:truthy 4 | push: 5 | branches: 6 | - main 7 | - develop 8 | pull_request: 9 | schedule: 10 | - cron: 0 12 * * * 11 | 12 | jobs: 13 | yamllint: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: actions/checkout@v1 17 | - name: yaml-lint 18 | uses: ibiqlik/action-yamllint@v3 19 | with: 20 | config_file: .yamllint 21 | 22 | lint-clang-format: 23 | env: 24 | esphome_directory: esphome 25 | runs-on: ubuntu-latest 26 | # cpp lint job runs with esphome-lint docker image so that clang-format-* 27 | # doesn't have to be installed 28 | container: esphome/esphome-lint:latest 29 | steps: 30 | - uses: actions/checkout@v2 31 | # Set up the pio project so that the cpp checks know how files are compiled 32 | # (build flags, libraries etc) 33 | 34 | - name: 💣 Clone esphome project 35 | run: git clone https://github.com/esphome/esphome.git 36 | - name: 💣 Copy component into the esphome project 37 | run: | 38 | cp -r ../components/* esphome/components/ 39 | git config user.name "ci" 40 | git config user.email "ci@github.com" 41 | git add . 42 | git commit -a -m "Add external component" 43 | working-directory: ${{ env.esphome_directory }} 44 | 45 | - name: Set up platformio environment 46 | run: pio init --ide atom 47 | working-directory: ${{ env.esphome_directory }} 48 | 49 | - name: Run clang-format 50 | run: script/clang-format -i 51 | working-directory: ${{ env.esphome_directory }} 52 | 53 | - name: Suggest changes 54 | run: script/ci-suggest-changes 55 | working-directory: ${{ env.esphome_directory }} 56 | 57 | lint-clang-tidy: 58 | env: 59 | esphome_directory: esphome 60 | runs-on: ubuntu-latest 61 | # cpp lint job runs with esphome-lint docker image so that clang-format-* 62 | # doesn't have to be installed 63 | container: esphome/esphome-lint:latest 64 | steps: 65 | - uses: actions/checkout@v2 66 | 67 | - name: 💣 Clone esphome project 68 | run: git clone https://github.com/esphome/esphome.git 69 | - name: 💣 Copy component into the esphome project 70 | run: | 71 | cp -r ../components/* esphome/components/ 72 | git config user.name "ci" 73 | git config user.email "ci@github.com" 74 | git add . 75 | git commit -a -m "Add external component" 76 | working-directory: ${{ env.esphome_directory }} 77 | 78 | # Set up the pio project so that the cpp checks know how files are compiled 79 | # (build flags, libraries etc) 80 | - name: Set up platformio environment 81 | run: pio init --ide atom 82 | working-directory: ${{ env.esphome_directory }} 83 | 84 | - name: Register problem matchers 85 | run: | 86 | echo "::add-matcher::.github/workflows/matchers/clang-tidy.json" 87 | echo "::add-matcher::.github/workflows/matchers/gcc.json" 88 | # Can be removed as soon as esphome-lint container is fixed 89 | - name: Add missing pexpect 90 | run: pip install pexpect 91 | - name: Run lint-cpp 92 | run: script/lint-cpp -c 93 | working-directory: ${{ env.esphome_directory }} 94 | - name: Suggest changes 95 | run: script/ci-suggest-changes 96 | working-directory: ${{ env.esphome_directory }} 97 | 98 | lint-python: 99 | env: 100 | esphome_directory: esphome 101 | # Don't use the esphome-lint docker image because it may contain outdated requirements. 102 | # This way, all dependencies are cached via the cache action. 103 | runs-on: ubuntu-latest 104 | steps: 105 | - uses: actions/checkout@v2 106 | - name: Set up Python 107 | uses: actions/setup-python@v2 108 | with: 109 | python-version: '3.9' 110 | - name: Cache pip modules 111 | uses: actions/cache@v1 112 | with: 113 | path: ~/.cache/pip 114 | key: esphome-pip-3.9-${{ hashFiles('setup.py') }} 115 | restore-keys: | 116 | esphome-pip-3.9- 117 | 118 | - name: 💣Clone esphome project 119 | run: git clone https://github.com/esphome/esphome.git 120 | - name: 💣Copy component into the esphome project 121 | run: | 122 | cp -r ../components/* esphome/components/ 123 | git config user.name "ci" 124 | git config user.email "ci@github.com" 125 | git add . 126 | git commit -a -m "Add external component" 127 | working-directory: ${{ env.esphome_directory }} 128 | 129 | - name: Add missing requirements 130 | run: pip3 install setuptools wheel 131 | - name: Set up python environment 132 | run: script/setup 133 | working-directory: ${{ env.esphome_directory }} 134 | 135 | - name: Register problem matchers 136 | run: | 137 | echo "::add-matcher::.github/workflows/matchers/ci-custom.json" 138 | echo "::add-matcher::.github/workflows/matchers/lint-python.json" 139 | echo "::add-matcher::.github/workflows/matchers/python.json" 140 | 141 | - name: Lint Custom 142 | run: script/ci-custom.py -c 143 | working-directory: ${{ env.esphome_directory }} 144 | - name: Lint Python 145 | run: script/lint-python -c 146 | working-directory: ${{ env.esphome_directory }} 147 | 148 | esphome-config: 149 | runs-on: ubuntu-latest 150 | steps: 151 | - name: ⤵️ Check out configuration from GitHub 152 | uses: actions/checkout@v2 153 | - name: Setup Python 3.9 154 | uses: actions/setup-python@v1 155 | with: 156 | python-version: 3.9 157 | - name: Install dependencies 158 | run: | 159 | python -m pip install --upgrade pip setuptools wheel 160 | pip install esphome 161 | pip list 162 | esphome version 163 | - name: Write secrets.yaml 164 | shell: bash 165 | run: 'echo -e "wifi_ssid: ssid\nwifi_password: password\nmqtt_host: host\nmqtt_username: username\nmqtt_password: password" > secrets.yaml' 166 | - run: | 167 | esphome -s external_components_source components config esp32-heltec-balancer-ble-example.yaml 168 | - run: | 169 | esphome -s external_components_source components config esp8266-example.yaml 170 | esphome -s external_components_source components config esp8266-example-debug.yaml 171 | esphome -s external_components_source components config esp8266-example-faker.yaml 172 | - run: | 173 | esphome -s external_components_source components config esp32-example.yaml 174 | esphome -s external_components_source components config esp32-example-debug.yaml 175 | esphome -s external_components_source components config esp32-example-faker.yaml 176 | esphome -s external_components_source components config esp32-example-multiple-devices.yaml 177 | - run: | 178 | esphome -s external_components_source components config esp32-ble-example.yaml 179 | esphome -s external_components_source components config esp32-ble-example-debug.yaml 180 | esphome -s external_components_source components config esp32-ble-example-faker.yaml 181 | esphome -s external_components_source components config esp32-ble-jk04-example.yaml 182 | esphome -s external_components_source components config esp32-ble-example-multiple-devices.yaml 183 | 184 | esphome-compile: 185 | runs-on: ubuntu-latest 186 | needs: [esphome-config] 187 | steps: 188 | - name: ⤵️ Check out configuration from GitHub 189 | uses: actions/checkout@v2 190 | - name: Cache .esphome 191 | uses: actions/cache@v2 192 | with: 193 | path: .esphome 194 | key: esphome-compile-esphome-${{ hashFiles('*.yaml') }} 195 | restore-keys: esphome-compile-esphome- 196 | - name: Cache .pioenvs 197 | uses: actions/cache@v2 198 | with: 199 | path: .pioenvs 200 | key: esphome-compile-pioenvs-${{ hashFiles('*.yaml') }} 201 | restore-keys: esphome-compile-pioenvs- 202 | - name: Set up Python 3.9 203 | uses: actions/setup-python@v1 204 | with: 205 | python-version: 3.9 206 | - name: Install dependencies 207 | run: | 208 | python -m pip install --upgrade pip setuptools wheel 209 | pip install esphome 210 | pip list 211 | esphome version 212 | - name: Register problem matchers 213 | run: | 214 | echo "::add-matcher::.github/workflows/matchers/gcc.json" 215 | echo "::add-matcher::.github/workflows/matchers/python.json" 216 | - name: Write secrets.yaml 217 | shell: bash 218 | run: 'echo -e "wifi_ssid: ssid\nwifi_password: password\nmqtt_host: host\nmqtt_username: username\nmqtt_password: password" > secrets.yaml' 219 | - run: | 220 | esphome -s external_components_source components compile esp32-heltec-balancer-ble-example.yaml 221 | - run: | 222 | esphome -s external_components_source components compile esp8266-example-faker.yaml 223 | - run: | 224 | esphome -s external_components_source components compile esp32-example-faker.yaml 225 | - run: | 226 | esphome -s external_components_source components compile esp32-ble-example-faker.yaml 227 | -------------------------------------------------------------------------------- /.github/workflows/matchers/ci-custom.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "ci-custom", 5 | "pattern": [ 6 | { 7 | "regexp": "^ERROR (.*):(\\d+):(\\d+) - (.*)$", 8 | "file": 1, 9 | "line": 2, 10 | "column": 3, 11 | "message": 4 12 | } 13 | ] 14 | } 15 | ] 16 | } 17 | -------------------------------------------------------------------------------- /.github/workflows/matchers/clang-tidy.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "clang-tidy", 5 | "pattern": [ 6 | { 7 | "regexp": "^(.*):(\\d+):(\\d+):\\s+(error):\\s+(.*) \\[([a-z0-9,\\-]+)\\]\\s*$", 8 | "file": 1, 9 | "line": 2, 10 | "column": 3, 11 | "severity": 4, 12 | "message": 5 13 | } 14 | ] 15 | } 16 | ] 17 | } 18 | -------------------------------------------------------------------------------- /.github/workflows/matchers/gcc.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "gcc", 5 | "severity": "error", 6 | "pattern": [ 7 | { 8 | "regexp": "^(.*):(\\d+):(\\d+):\\s+(?:fatal\\s+)?(warning|error):\\s+(.*)$", 9 | "file": 1, 10 | "line": 2, 11 | "column": 3, 12 | "severity": 4, 13 | "message": 5 14 | } 15 | ] 16 | } 17 | ] 18 | } 19 | -------------------------------------------------------------------------------- /.github/workflows/matchers/lint-python.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "flake8", 5 | "severity": "error", 6 | "pattern": [ 7 | { 8 | "regexp": "^(.*):(\\d+) - ([EFCDNW]\\d{3}.*)$", 9 | "file": 1, 10 | "line": 2, 11 | "message": 3 12 | } 13 | ] 14 | }, 15 | { 16 | "owner": "pylint", 17 | "severity": "error", 18 | "pattern": [ 19 | { 20 | "regexp": "^(.*):(\\d+) - (\\[[EFCRW]\\d{4}\\(.*\\),.*\\].*)$", 21 | "file": 1, 22 | "line": 2, 23 | "message": 3 24 | } 25 | ] 26 | } 27 | ] 28 | } 29 | -------------------------------------------------------------------------------- /.github/workflows/matchers/python.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "python", 5 | "pattern": [ 6 | { 7 | "regexp": "^\\s*File\\s\\\"(.*)\\\",\\sline\\s(\\d+),\\sin\\s(.*)$", 8 | "file": 1, 9 | "line": 2 10 | }, 11 | { 12 | "regexp": "^\\s*raise\\s(.*)\\(\\'(.*)\\'\\)$", 13 | "message": 2 14 | } 15 | ] 16 | } 17 | ] 18 | } 19 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # esphome-jk-bms-can 2 | 3 | ![GitHub stars](https://img.shields.io/github/stars/Uksa007/esphome-jk-bms-can) 4 | ![GitHub forks](https://img.shields.io/github/forks/Uksa007/esphome-jk-bms-can) 5 | ![GitHub watchers](https://img.shields.io/github/watchers/Uksa007/esphome-jk-bms-can) 6 | [!["Support development"](https://img.shields.io/badge/support%20development-donate-yellow.svg)](https://www.patreon.com/Uksa007Codedevelopment) 7 | 8 | ESPHome component to monitor a Jikong Battery Management System (JK-BMS) via RS485 or BLE 9 | 10 | ## Note this has code been depricated in favour of [iBMS interface for BMS](https://shop.jamestronics.com) 11 | This has resulted as I spent all my time trying to help people build hardware with little to no electronics experience, and then configuring and compiling the firmware was not easy for most. Most want it all with support for nothing. I no longer have the time. 12 | 13 | The solution is I supply the hardware kit configured how you want, plug and play, you end up with a quality product as opposed to modules connected with dupont connectors which were unreliable at best. 14 | 15 | iBMS: Interface for BMS [available here](https://shop.jamestronics.com) 16 | 17 | Isolated CAN1/2 for Multi-BMS 18 | 19 | This all new Interface is designed with many features: 20 | 21 | - Updated design specifically for Muli-BMS use with Isolated CAN1/2 ports, dedicated Isolated CAN Power supply and new Isolated CAN driver with +-70 bus fault protection. 22 | - Supports Most Inverters with CAN communications, profiles for: BYD, Deye, Generic, Goodwe, Pylon, Victron, LIA (beta) 23 | - New iBMS firmware completely written in esp-idf using 100% my own code, no more esp-home. 24 | - New companion Home Assistant integration(custom component must be installed) 25 | - Web page designed for mobile phone size screens 26 | - The one board can be used with a standalone battery or used in a multi BMS setup, software configurable as a Master or Slave(1-9).  One board needed per BMS  27 | - Future proof, can be used with the original JK-BMS or the new Inverter type. 28 | - One board to rule them all. 29 | - DIP switches to enable CAN termination. 30 | - Improved CAN bus driver chip now fully isolated 31 | - TVS Transient voltage suppression, to protect the CAN driver chip. 32 | - On board buck converter with resettable fuse. 33 | 34 | The original JK-BMS with the 4 pin connecter supplies power to board, plug and play.
35 | Note: Inverter type, must be powered direct from battery 12-60v, with the included cable. 2 temperature sensors displayed with newer JK-BMS
36 | Professionally manufactured and burn in testing.
37 | Lead free construction, greener and low environmental impact! 38 | 39 | Supported inverter models in addition to the original BD JK-BMS: 40 | JK-PB1A16S10P / JK-PB1A16S15P / JK-PB2A16S15P / JK-PB1A16S20P / JK-PB2A16S20P 41 | 42 | iBMS: Interface for BMS [available here](https://shop.jamestronics.com) 43 | 44 | ## Which JK BMS should I order, you should order this model: 45 | [I would recommend the 200A model B2A20S20P](https://s.click.aliexpress.com/e/_Dl3owdX) if you are planning on constant change/discharge of 150A, better to have a little head room. 46 | This model has a 2A active balancer and 8-20S LiFePO4 47 | You have to click view more and select the correct model, Note model is the Color: 48 | Work in progess to support the new inverter style Jk-BMS, see below for supported devices. 49 | 50 | ## This fork supports CAN bus communication with inverters supporting the CANBUS Protocol compatible with Pylontech V1.3 and Goodwe V1.5. 51 | Note Pylontech uses 15s/48v Goodwe uses 16s/51.2v @3.2v/cell nominal. 52 | Other battery profiles that utilise the pylonton/goodwe protocol with differnt cell counts may also work, eg Alpha Ess Smile, BYD Battery-Box LV Flex Lite 53 | Select the correct battery profile in the inverter to match your battery pack! 54 | 55 | **New: Plug and play Hardware interface see [here for more info: iBMS interface for BMS](https://shop.jamestronics.com)** 56 | 57 | The ESP32 communicates with the JK-BMS using the RS485 port(GPS) which is in fact not RS485, it is 3.3V TTL so it can be directly connected to the ESP32. 58 | The ESP32 then sends the required CAN bus data to the inverter via a TJA1050 CAN bus transceiver. 59 | 60 | Sends over CAN bus to inverter: 61 | - Battery Voltage 62 | - Battery Current (+charge, -discharge) 63 | - State of Charge (SOC) 64 | - State of health (SOH) 65 | - BMS Temperature 66 | - Charging Voltage 67 | - Charging Amps 68 | - Discharge min Voltage 69 | - Battery name 70 | - Alarms: Cell over/under voltage, Charge/discharge over current, High/low Temp, BMS fault 71 | - Charging logic: Complete rework of the charging logic, now charges with constant current(CC) to the absorption voltage, then has an absorption timer (Constant Voltage, user configurable time), with rebulk feature (user configurable offset from absorption voltage). 72 | 73 | Note:- The standard code support one BMS connection per inverter. 74 | Multi BMS support availabe for [Alpha testers](https://github.com/Uksa007/esphome-jk-bms-can/discussions/20)
75 | Early stages are under way to support multiple BMS, but need funding to purchase additional hardware, please consider supporting me if you would like to see this functionally, early access code with be made available in the Alpha testers: https://www.patreon.com/Uksa007Codedevelopment 76 | 77 | NOTE: ESP32 has a bug that causes WDT reboot if no other devices on CAN bus to ACK the packets. 78 | If you try to run without inverter it will not work as it will constantly WDT reboot! 79 | There is an early access beta version available that works around no inverter(CAN bus requires 2 devices to work) 80 | 81 | 82 | Home Assistant native integration via ESPHome: 83 | - Inverter control switches to manage inverter remotely 84 | - Disable inverter charging 85 | - Disable inverter discharging 86 | - Enable inverter charging (top balancing) 87 | - All BMS sensor vaules listed below 88 | 89 | I have been testing using the Goodwe LX U5.4-L battery profile selected in the inverter.
90 | Each LX U5.4-L battery has 5.4kWh of storage, so select the number that is the closest match to your battery's total capacity.
91 | 92 | **Note:- I'm using this with my Goodwe GW5000S-BP inverter however CAN bus support is still in development and testing!!!**
93 | Further deatils in the discussion tab https://github.com/Uksa007/esphome-jk-bms-can/discussions 94 | 95 | 96 | If you find this useful and would like to suppport my work [!["Support development"](https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/main/images/become_a_patron_button.png)](https://www.patreon.com/Uksa007Codedevelopment) here thanks! 97 | 98 | 99 |
**NOTE: ESP32 has a bug that causes WDT reboot if no other devices on CAN bus to ACK the packets.
100 | If you try to run without inverter to CAN bus it will NOT work as it will constantly WDT reboot!
101 | There is an [early access beta version available](https://www.patreon.com/posts/beta-tester-code-78524976) that works around no inverter(CAN bus requires 2 devices to work).
102 | If you would like to test without inverter connected, only the [beta version will work!](https://www.patreon.com/posts/beta-tester-code-78524976)**

103 | 104 | 105 | * Connect a TJA1050 to an ESP32 (default GPIO 23 TX, 22 RX) as per https://esphome.io/components/canbus.html?highlight=can#wiring-options 106 | * Use this code in esphome https://github.com/Uksa007/esphome-jk-bms-can/blob/main/esp32-example-can.yaml 107 | * (optional) A second ESP32 and TJA1050 make a test CAN bus/receiver https://github.com/Uksa007/esphome-jk-bms-can/blob/main/test-esp32-receiver-can.yaml 108 | If you don't yet have TJA1050 you can still test with two ESP32 by making a makeshif CAN bus DO NOT CONNECT TO A REAL CAN BUS! 109 | Add a blocking diode between the CAN-TX and CAN-RX pins (cathode towards the CAN-TX pin) at both ESP32s! 110 | So a Diode between GPIO5, GPIO4 diode cathode to GPIO5 at both ESP32 111 | Then tie the CAN-RX lines together with a pull-up resistor to 3.3V I used 10K pullup. 112 | 113 | ## Home Assistant intergration 114 | ![Lovelace entities card](images/Homeassistantbatery_s_new.jpg "Lovelace entities card") 115 | 116 | 117 | ## Supported devices 118 | 119 | Inverters supporting CAN Pylon/Goodwe Low Voltage protocol should work, check your inverter manual to confirm. 120 | 121 | The following are confirmed and known to work: 122 | * Deye 5k-sg03lp1-eu (reported by [@vdiex](https://github.com/Uksa007/esphome-jk-bms-can/discussions/1#discussioncomment-4481364)) 123 | * Deye SUN-12K-SG04LP3-EU (reported by [@lucize](https://github.com/Uksa007/esphome-jk-bms-can/discussions/25#discussioncomment-5890844)) 124 | * Goodwe 3648-ES (GW5048-ES) (reported by [@jirdol](https://github.com/Uksa007/esphome-jk-bms-can/discussions/1#discussioncomment-5498743)) 125 | * Goodwe GW5000S-BP (reported by [@Uksa007](https://github.com/Uksa007/esphome-jk-bms-can/discussions/2#discussion-4469605) using the "Goodwe LX U5.4-L * 3" battery profile) 126 | * Sofar solar me3000sp (reported by [@starman](https://diysolarforum.com/threads/jk-bms-can-bus-comms-now-possible-for-inverters-that-support-goodwe-and-pylontech-batteries.48963/post-755539)) 127 | * Turbo energy (reported by [@ibikku](https://github.com/Uksa007/esphome-jk-bms-can/discussions/13#discussion-4823950)) 128 | 129 |
All JK-BMS models with software version `>=6.0` are using the implemented protocol and should be supported. 130 | 131 | * JK-BD6A17S6P, hw 7.2, sw 7.1.0H 132 | * JK-BD6A17S8P, hw 9.x, sw 9.01G (reported by [@jonadis](https://github.com/syssi/esphome-jk-bms/issues/35#issuecomment-1035312712)) 133 | * JK-BD6A20S10P, hw 10.XW, sw 10.07 (reported by [@adadrag](https://github.com/syssi/esphome-jk-bms/issues/123)) 134 | * JK-BD6A24S6P, hw 6.x, sw 6.10S (reported by [@ziporah](https://github.com/syssi/esphome-jk-bms/issues/41)) 135 | * JK-BD6A24S10P, hw 8.x, sw 8.0.6G (reported by [@spoonwzd](https://github.com/syssi/esphome-jk-bms/issues/67#issuecomment-1093844076)) 136 | * JK-BD4A17S4P, hw 11.xw, sw 11.01 (reported by [@Condor-XYZ](https://github.com/syssi/esphome-jk-bms/issues/221)) 137 | * JK-B1A24S15P, hw 8.x, sw 8.1.0H (reported by [@killee](https://github.com/syssi/esphome-jk-bms/discussions/4)) 138 | * JK-B1A20S15P, hw 8.x, sw 8.14U (reported by [@trippfam07](https://github.com/syssi/esphome-jk-bms/issues/31)) 139 | * JK-B2A24S15P, hw 6.x, sw 6.1.3S (reported by [@miguel300477](https://github.com/syssi/esphome-jk-bms/issues/57)) 140 | * JK-B2A24S15P, hw 8.x, sw 8.21W (reported by [@mariusvaida](https://github.com/syssi/esphome-jk-bms/issues/120)) 141 | * JK-B2A24S15P, hw 10.xw, sw 10.07 142 | * JK-B2A24S15P, hw 10.xw, sw 10.08 (reported by [@meccip](https://github.com/syssi/esphome-jk-bms/discussions/175#discussioncomment-3687287)) 143 | * JK-B2A24S20P, hw 8.x, sw 8.1.2H (reported by [@KlausLi](https://github.com/syssi/esphome-jk-bms/issues/15#issuecomment-961447064)) 144 | * JK-B2A24S20P, hw 8.x, sw 8.20G (reported by [@rob-oravec](https://github.com/syssi/esphome-jk-bms/discussions/46)) 145 | * JK-B2A24S20P, hw 10.X-W, sw 10.02 (reported by [@SeByDocKy](https://github.com/syssi/esphome-jk-bms/issues/37#issuecomment-1040569576)) 146 | * JK-B2A24S20P, hw 10.XG, sw 10.07D30 (reported by [@TheSmartGerman](https://github.com/syssi/esphome-jk-bms/discussions/122)) 147 | * JK-B2A24S20P, hw 10.XW, sw 10.07 (reported by [@amagr0](https://github.com/syssi/esphome-jk-bms/issues/124#issuecomment-1166366196)) 148 | * JK-B2A8S20P, hw 9.x, sw 9.01M3 (reported by [@EasilyBoredEngineer](https://github.com/syssi/esphome-jk-bms/discussions/110)) 149 | * JK-B2A8S20P, hw 9.x, sw 9.08W (reported by [@vrabi-cv](https://github.com/syssi/esphome-jk-bms/discussions/144#discussioncomment-3285901)) 150 | * JK-B2A8S20P, hw 11.XW, sw 11.17 (reported by [@senfkorn](https://github.com/syssi/esphome-jk-bms/issues/147)) 151 | * JK-B2A20S20P, hw 10.XW, sw 10.09 (reported by [@markusgg84](https://github.com/syssi/esphome-jk-bms/discussions/173)) 152 | * JK-B5A24S, hw 8.x, sw 8.0.3M, using `JK04` (reported by [@JSladen](https://github.com/syssi/esphome-jk-bms/issues/213)) 153 | * GW-24S4EB (NEEY/Heltec 4A Smart Active Balancer), hw HW-2.8.0, sw ZH-1.2.3 (reported by [@cristi2005](https://github.com/syssi/esphome-jk-bms/issues/109)) 154 | 155 | ## Untested devices 156 | 157 | * JK-BD6A20S6P 158 | 159 | ## Requirements 160 | 161 | * [ESPHome 2022.11.0 or higher](https://github.com/esphome/esphome/releases). 162 | * Generic ESP32, I use the esp32doit-devkit-v1 NOTE: ESP32-S2 currently has issues with CAN BUS and does not work! 163 | * TJA1050 CAN controller interface module and 4.7K resistor for 5v to 3.3v level shifing. 164 | * Optional: JK RS485 Adaptor and RS484 to TTL3.3v Adaptor (see optional schematic below) 165 | 166 | ## Schematics 167 | I have designed and build a [Hardware interface baord](https://github.com/Uksa007/esphome-jk-bms-can/discussions/16) pictured below on the left. 168 | This has all the hardware needed to communicate with BMS and Inverter over CAN bus. 169 | It is a plug and play device, just add power (5v USB) 170 | Hand built on a PCB and soldered to the ESP32, bulletproof design for production use. 171 | Don't use modules and Dupont connectors for long term production use, they are for proof of concept and prototyping only, and are prone to fail. 172 | Update: now available with two RJ45 with Termination disabled for Multi BMS 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | ``` 183 | RS485-TTL RS232-TTL CAN BUS 184 | ┌──────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ 185 | │ ││16 23│| | | | 186 | │ JK-BMS ││17 22│| TJA1050 |<---CAN H --->| Inverter | 187 | │ │<----GND--->│ │<----GND---->| CAN |<---CAN L --->| | 188 | │ │ 3.3V ---->│ ESP32 │<----5V----->| | | | 189 | └──────────┘ └─────────┘ └─────────┘ └──────────┘ 190 | 191 | 192 | 193 | Optional below, as seen in pic above: RS485 between JK-BMS GPS port and ESP32, uses JK RS485 adaptor and RS485 to TTL3.3v adaptor. 194 | 195 | RS485-TTL RS485 RS485-TTL RS232-TTL CAN BUS 196 | ┌──────────┐ ┌───────────┐ ┌────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ 197 | │ │<--- TX --->│Y JK Y││ ││16 23│| | | | 198 | │ JK-BMS │<--- RX --->│W RS485 W││ RS485 ││17 22│| TJA1050 |<---CAN H --->| Inverter | 199 | │ │<--- GND -->│B Adaptor B│<---GND--->│To 3.3V │<---GND--->| |<----GND---->| CAN |<---CAN L --->| | 200 | │ │<--Bat V -->│R │ │ │<---3.3V-->| ESP32 |<----5V----->| | | | 201 | └──────────┘ └───────────┘ └────────┘ └─────────┘ └─────────┘ └──────────┘ 202 | 203 | 204 | 205 | # RS485-TTL jack on JK-BMS (4 Pin, JST 1.25mm pitch) 206 | ┌─── ─────── ────┐ 207 | │ │ 208 | │ O O O O │ 209 | │GND RX TX VBAT│ 210 | └────────────────┘ 211 | │ │ │ | VBAT is full battery volatge eg 51.2V (No connect) 212 | │ │ └──── ESP32 GPIO16 (`rx_pin`) 213 | │ └──────── ESP32 GPIO17 (`tx_pin`) 214 | └──────────── GND 215 | ``` 216 | 217 | 218 | The RS485-TTL jack of the BMS can be attached to any UART pins of the ESP. A hardware UART should be preferred because of the high baudrate (115200 baud). The connector is called 4 Pin JST with 1.25mm pitch. 219 | 220 | ## Firmware releases for direct flashing to ESP32 221 | This code is old has been depricated. 222 | 223 | ## Optional add to Home Assistant 224 | In Home Assistant under settings->Intergration "Add Intergration" select ESPHome add device jk-bms-can if found or supply ip address of ESP32 225 | 226 | 227 | ## Example CAN messages 228 | 229 | ``` 230 | [main:141]: send can id: 0x359 hex: 0 0 0 0 3 0 0 0 231 | [canbus:033]: send extended id=0x359 rtr=FALSE size=8 232 | [main:187]: send can id: 0x351 hex: 28 2 e8 3 e8 3 a0 1 233 | [canbus:033]: send extended id=0x351 rtr=FALSE size=8 234 | [main:199]: send can id: 0x355 hex: 4f 0 64 0 235 | [canbus:033]: send extended id=0x355 rtr=FALSE size=4 236 | [main:213]: send can id: 0x356 hex: 63 14 62 fc 86 1 237 | [canbus:033]: send extended id=0x356 rtr=FALSE size=6 238 | [canbus:070]: received can message (#1) std can_id=0x305 size=8 239 | [light:035]: 'Builtin LED' Setting: 240 | [light:046]: State: OFF 241 | [main:238]: send can id: 0x35C hex: c0 0 242 | [canbus:033]: send extended id=0x35c rtr=FALSE size=2 243 | [canbus:033]: send extended id=0x35e rtr=FALSE size=8 244 | ``` 245 | 246 | ## Example response all sensors enabled 247 | 248 | ``` 249 | [sensor:125]: 'jk-bms-can cell voltage 1': Sending state 3.27200 V with 3 decimals of accuracy 250 | [sensor:125]: 'jk-bms-can cell voltage 2': Sending state 3.26900 V with 3 decimals of accuracy 251 | [sensor:125]: 'jk-bms-can cell voltage 3': Sending state 3.26800 V with 3 decimals of accuracy 252 | [sensor:125]: 'jk-bms-can cell voltage 4': Sending state 3.26700 V with 3 decimals of accuracy 253 | [sensor:125]: 'jk-bms-can cell voltage 5': Sending state 3.25000 V with 3 decimals of accuracy 254 | [sensor:125]: 'jk-bms-can cell voltage 6': Sending state 3.26600 V with 3 decimals of accuracy 255 | [sensor:125]: 'jk-bms-can cell voltage 7': Sending state 3.25600 V with 3 decimals of accuracy 256 | [sensor:125]: 'jk-bms-can cell voltage 8': Sending state 3.26800 V with 3 decimals of accuracy 257 | [sensor:125]: 'jk-bms-can cell voltage 9': Sending state 3.25800 V with 3 decimals of accuracy 258 | [sensor:125]: 'jk-bms-can cell voltage 10': Sending state 3.26000 V with 3 decimals of accuracy 259 | [sensor:125]: 'jk-bms-can cell voltage 11': Sending state 3.26200 V with 3 decimals of accuracy 260 | [sensor:125]: 'jk-bms-can cell voltage 12': Sending state 3.25700 V with 3 decimals of accuracy 261 | [sensor:125]: 'jk-bms-can cell voltage 13': Sending state 3.25700 V with 3 decimals of accuracy 262 | [sensor:125]: 'jk-bms-can cell voltage 14': Sending state 3.26000 V with 3 decimals of accuracy 263 | [sensor:125]: 'jk-bms-can cell voltage 15': Sending state 3.26500 V with 3 decimals of accuracy 264 | [sensor:125]: 'jk-bms-can cell voltage 16': Sending state 3.26800 V with 3 decimals of accuracy 265 | [sensor:125]: 'jk-bms-can min cell voltage': Sending state 3.25000 V with 3 decimals of accuracy 266 | [sensor:125]: 'jk-bms-can max cell voltage': Sending state 3.27200 V with 3 decimals of accuracy 267 | [sensor:125]: 'jk-bms-can max voltage cell': Sending state 1.00000 with 0 decimals of accuracy 268 | [sensor:125]: 'jk-bms-can min voltage cell': Sending state 5.00000 with 0 decimals of accuracy 269 | [sensor:125]: 'jk-bms-can delta cell voltage': Sending state 0.02200 V with 3 decimals of accuracy 270 | [sensor:125]: 'jk-bms-can average cell voltage': Sending state 3.26269 V with 3 decimals of accuracy 271 | [sensor:125]: 'jk-bms-can power tube temperature': Sending state 39.00000 °C with 0 decimals of accuracy 272 | [sensor:125]: 'jk-bms-can temperature sensor 1': Sending state 26.00000 °C with 0 decimals of accuracy 273 | [sensor:125]: 'jk-bms-can temperature sensor 2': Sending state 26.00000 °C with 0 decimals of accuracy 274 | [sensor:125]: 'jk-bms-can total voltage': Sending state 52.20000 V with 2 decimals of accuracy 275 | [sensor:125]: 'jk-bms-can current': Sending state -92.64000 A with 2 decimals of accuracy 276 | [sensor:125]: 'jk-bms-can power': Sending state -4835.80762 W with 2 decimals of accuracy 277 | [sensor:125]: 'jk-bms-can charging power': Sending state 0.00000 W with 2 decimals of accuracy 278 | [sensor:125]: 'jk-bms-can discharging power': Sending state 4835.80762 W with 2 decimals of accuracy 279 | [sensor:125]: 'jk-bms-can capacity remaining': Sending state 79.00000 % with 0 decimals of accuracy 280 | [sensor:125]: 'jk-bms-can temperature sensors': Sending state 2.00000 with 0 decimals of accuracy 281 | [sensor:125]: 'jk-bms-can charging cycles': Sending state 4.00000 with 0 decimals of accuracy 282 | [sensor:125]: 'jk-bms-can total charging cycle capacity': Sending state 1280.00000 Ah with 0 decimals of accuracy 283 | [sensor:125]: 'jk-bms-can battery strings': Sending state 16.00000 with 0 decimals of accuracy 284 | [sensor:125]: 'jk-bms-can errors bitmask': Sending state 0.00000 with 0 decimals of accuracy 285 | [text_sensor:067]: 'jk-bms-can errors': Sending state '' 286 | [sensor:125]: 'jk-bms-can operation mode bitmask': Sending state 3.00000 with 0 decimals of accuracy 287 | [text_sensor:067]: 'jk-bms-can operation mode': Sending state 'Charging enabled;Discharging enabled' 288 | [sensor:125]: 'jk-bms-can total voltage overvoltage protection': Sending state 57.60000 V with 2 decimals of accuracy 289 | [sensor:125]: 'jk-bms-can total voltage undervoltage protection': Sending state 41.60000 V with 2 decimals of accuracy 290 | [sensor:125]: 'jk-bms-can cell voltage overvoltage protection': Sending state 3.60000 V with 3 decimals of accuracy 291 | [sensor:125]: 'jk-bms-can cell voltage overvoltage recovery': Sending state 3.55000 V with 3 decimals of accuracy 292 | [sensor:125]: 'jk-bms-can cell voltage overvoltage delay': Sending state 5.00000 s with 0 decimals of accuracy 293 | [sensor:125]: 'jk-bms-can cell voltage undervoltage protection': Sending state 2.60000 V with 3 decimals of accuracy 294 | [sensor:125]: 'jk-bms-can cell voltage undervoltage recovery': Sending state 2.65000 V with 3 decimals of accuracy 295 | [sensor:125]: 'jk-bms-can cell voltage undervoltage delay': Sending state 5.00000 s with 0 decimals of accuracy 296 | [sensor:125]: 'jk-bms-can cell pressure difference protection': Sending state 0.30000 V with 3 decimals of accuracy 297 | [sensor:125]: 'jk-bms-can discharging overcurrent protection': Sending state 100.00000 A with 0 decimals of accuracy 298 | [sensor:125]: 'jk-bms-can discharging overcurrent delay': Sending state 300.00000 s with 0 decimals of accuracy 299 | [sensor:125]: 'jk-bms-can charging overcurrent protection': Sending state 100.00000 A with 0 decimals of accuracy 300 | [sensor:125]: 'jk-bms-can charging overcurrent delay': Sending state 30.00000 s with 0 decimals of accuracy 301 | [sensor:125]: 'jk-bms-can balance starting voltage': Sending state 3.40000 V with 3 decimals of accuracy 302 | [sensor:125]: 'jk-bms-can balance opening pressure difference': Sending state 0.00500 V with 3 decimals of accuracy 303 | [sensor:125]: 'jk-bms-can power tube temperature protection': Sending state 90.00000 °C with 0 decimals of accuracy 304 | [sensor:125]: 'jk-bms-can power tube temperature recovery': Sending state 70.00000 °C with 0 decimals of accuracy 305 | [sensor:125]: 'jk-bms-can temperature sensor temperature protection': Sending state 100.00000 °C with 0 decimals of accuracy 306 | [sensor:125]: 'jk-bms-can temperature sensor temperature recovery': Sending state 100.00000 °C with 0 decimals of accuracy 307 | [sensor:125]: 'jk-bms-can temperature sensor temperature difference protection': Sending state 20.00000 °C with 0 decimals of accuracy 308 | [sensor:125]: 'jk-bms-can charging high temperature protection': Sending state 70.00000 °C with 0 decimals of accuracy 309 | [sensor:125]: 'jk-bms-can discharging high temperature protection': Sending state 70.00000 °C with 0 decimals of accuracy 310 | [sensor:125]: 'jk-bms-can charging low temperature protection': Sending state -20.00000 °C with 0 decimals of accuracy 311 | [sensor:125]: 'jk-bms-can charging low temperature recovery': Sending state -10.00000 °C with 0 decimals of accuracy 312 | [sensor:125]: 'jk-bms-can discharging low temperature protection': Sending state -20.00000 °C with 0 decimals of accuracy 313 | [sensor:125]: 'jk-bms-can discharging low temperature recovery': Sending state -10.00000 °C with 0 decimals of accuracy 314 | [sensor:125]: 'jk-bms-can total battery capacity setting': Sending state 280.00000 Ah with 0 decimals of accuracy 315 | [sensor:125]: 'jk-bms-can capacity remaining derived': Sending state 221.19998 Ah with 0 decimals of accuracy 316 | [sensor:125]: 'jk-bms-can current calibration': Sending state 1.04800 A with 3 decimals of accuracy 317 | [sensor:125]: 'jk-bms-can device address': Sending state 1.00000 with 0 decimals of accuracy 318 | [text_sensor:067]: 'jk-bms-can battery type': Sending state 'Ternary Lithium' 319 | [sensor:125]: 'jk-bms-can sleep wait time': Sending state 10.00000 s with 0 decimals of accuracy 320 | [sensor:125]: 'jk-bms-can alarm low volume': Sending state 20.00000 % with 0 decimals of accuracy 321 | [text_sensor:067]: 'jk-bms-can password': Sending state '123456' 322 | [text_sensor:067]: 'jk-bms-can device type': Sending state 'Input Us' 323 | [sensor:125]: 'jk-bms-can total runtime': Sending state 226.13333 h with 0 decimals of accuracy 324 | [text_sensor:067]: 'jk-bms-can total runtime formatted': Sending state '9d 10h' 325 | [text_sensor:067]: 'jk-bms-can software version': Sending state '10.XG_S10.07___' 326 | [sensor:125]: 'jk-bms-can actual battery capacity': Sending state 256.00000 Ah with 0 decimals of accuracy 327 | [text_sensor:067]: 'jk-bms-can manufacturer': Sending state 'Input UserdaJK-B2A24S15P' 328 | ``` 329 | 330 | ## Known issues 331 | 332 | * The battery type sensor is pretty useless because the BMS reports always the same value (`Ternary Lithium`). Regardless of which battery type was set / parameter set was loaded via the android app. ([#9][i9]) 333 | * ESP32: Adding all supported sensors can lead to a stack overflow / boot loop. This can be solved by increasing the stack size. ([#63][i63]) 334 | * BLE: Please stick to the `esp-idf` framework because the Arduino framework crashs on the first received BLE notification. 335 | * Raspberry Pi & ESP-IDF: If the project doesn't compile because of `Error: Could not find the package with 'platformio/toolchain-esp32ulp @ ~1.22851.0' requirements for your system 'linux_aarch64'` please use a host with another processor architecture (f.e. x86). The toolchain isn't `linux_aarch64` (ARM64) compatible at the moment. 336 | * MQTT & BLE: Please use ESPHome `>=2022.4.0` if you want to use the BLE component (requires `esp-idf`) and MQTT. The MQTT component wasn't ESP-IDF compatible until then. 337 | 338 | [i9]: https://github.com/syssi/esphome-jk-bms/issues/9 339 | [i63]: https://github.com/syssi/esphome-jk-bms/issues/63 340 | 341 | ## Debugging 342 | 343 | If this component doesn't work out of the box for your device please update your configuration to enable the debug output of the UART component and increase the log level to the see outgoing and incoming serial traffic: 344 | 345 | ``` 346 | logger: 347 | level: DEBUG 348 | 349 | uart: 350 | id: uart0 351 | baud_rate: 115200 352 | rx_buffer_size: 384 353 | tx_pin: GPIO14 354 | rx_pin: GPIO4 355 | debug: 356 | direction: BOTH 357 | ``` 358 | 359 | ## References 360 | * https://github.com/syssi/esphome-jk-bms Thanks go to syssi for help and making the original RS485 code! 361 | * https://secondlifestorage.com/index.php?threads/jk-b1a24s-jk-b2a24s-active-balancer.9591/ 362 | * https://github.com/jblance/jkbms 363 | * https://github.com/jblance/mpp-solar/issues/112 364 | * https://github.com/jblance/mpp-solar/blob/master/mppsolar/protocols/jk232.py 365 | * https://github.com/jblance/mpp-solar/blob/master/mppsolar/protocols/jk485.py 366 | * https://github.com/sshoecraft/jktool 367 | * https://github.com/Louisvdw/dbus-serialbattery/blob/master/etc/dbus-serialbattery/jkbms.py 368 | * https://blog.ja-ke.tech/2020/02/07/ltt-power-bms-chinese-protocol.html 369 | -------------------------------------------------------------------------------- /docs/2007290932_HK-HK32F103C8T6_C482563.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/2007290932_HK-HK32F103C8T6_C482563.pdf -------------------------------------------------------------------------------- /docs/BMS-CAN Communication protocol.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/BMS-CAN Communication protocol.pdf -------------------------------------------------------------------------------- /docs/Communication protocol between monitoring platform and BMS.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/Communication protocol between monitoring platform and BMS.pdf -------------------------------------------------------------------------------- /docs/JK-Jiabaida_communication_protocol_v4.0.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/JK-Jiabaida_communication_protocol_v4.0.pdf -------------------------------------------------------------------------------- /docs/Lithium battery smart bms instructions.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/Lithium battery smart bms instructions.pdf -------------------------------------------------------------------------------- /docs/RS485 Communication example.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/RS485 Communication example.pdf -------------------------------------------------------------------------------- /docs/RS485-english-OBSOLETE.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/RS485-english-OBSOLETE.pdf -------------------------------------------------------------------------------- /docs/SMA CAN Protocol Mapping.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/SMA CAN Protocol Mapping.pdf -------------------------------------------------------------------------------- /docs/SMA CAN protocol.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/SMA CAN protocol.pdf -------------------------------------------------------------------------------- /docs/btsnoop_hci_jk-b1a20s15p_hw10xw_sw1007.log: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/btsnoop_hci_jk-b1a20s15p_hw10xw_sw1007.log -------------------------------------------------------------------------------- /docs/btsnoop_hci_jk-b2a16s_hw30_sw330.log: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/btsnoop_hci_jk-b2a16s_hw30_sw330.log -------------------------------------------------------------------------------- /docs/btsnoop_hci_jk-b2a16s_hw30_sw330_cmds.log: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/btsnoop_hci_jk-b2a16s_hw30_sw330_cmds.log -------------------------------------------------------------------------------- /docs/btsnoop_hci_jk-bd6a17s6p_hw72_sw710h.log: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/btsnoop_hci_jk-bd6a17s6p_hw72_sw710h.log -------------------------------------------------------------------------------- /docs/btsnoop_hci_jk-bd6a24s10p_hw8x_sw806g.log: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/btsnoop_hci_jk-bd6a24s10p_hw8x_sw806g.log -------------------------------------------------------------------------------- /docs/display-port.md: -------------------------------------------------------------------------------- 1 | # JK-BMS display port 2 | 3 | Since hardware version 10 the JK-BMS comes with a display port. The port can be used to turn the BMS on (short press = 1s) and off (long press = 3s). 4 | 5 | ## Connector and pinout 6 | 7 | | Model | Connector type | 8 | | -------------- | --------------------------------- | 9 | | JK-BD4A17S4P | No display port | 10 | | JK-BD6A17S6P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 11 | | JK-BD6A17S8P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 12 | | JK-BD6A20S6P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 13 | | JK-BD6A20S8P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 14 | | JK-BD6A24S6P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 15 | | JK-BD6A24S8P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 16 | | JK-B1A8S20P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 17 | | JK-B2A8S20P | 6 Pin, Micro JST 1.25mm pinch(?) or Micro JST GH 1.25mm pinch | 18 | | JK-BD6A20S10P | 6 Pin, Micro JST GH 1.25mm pinch | 19 | | JK-BD6A24S10P | 6 Pin, Micro JST GH 1.25mm pinch | 20 | | JK-B1A20S15P | 6 Pin, Micro JST GH 1.25mm pinch | 21 | | JK-B1A24S15P | 6 Pin, Micro JST GH 1.25mm pinch | 22 | | JK-B2A24S15P | 6 Pin, Micro JST GH 1.25mm pinch | 23 | | JK-B2A24S20P | 6 Pin, Micro JST GH 1.25mm pinch | 24 | 25 | ``` 26 | # JK-BD6AxxSxP 27 | 28 | │ JK-BD6AxxSxP │ 29 | │ │ 30 | │ RS485 Display │ 31 | └────────────────────[oooo]─────────────[oooooo]──┘ 32 | ││ 33 | ││ 34 | │└─── K+ 35 | └──── K- 36 | 37 | 38 | # JK-B2A8S20P 39 | 40 | │ JK-B2A8S20P │ 41 | │ │ 42 | │ Temp RS485 Display Balancer │ 43 | └──[oooo]──[ooo]──[oooo]──[oooooo]──[oooooooooo]──┘ 44 | ││ 45 | ││ 46 | │└─── K- 47 | └──── K+ 48 | 49 | 50 | # JK-BD6A2xS10P, JK-BxA24SxxP 51 | 52 | │ JK-BD6A2xS10P, JK-BxA24SxxP │ 53 | │ │ 54 | │ CAN RS485 Display Heat │ 55 | └────[ooo]─[oooo]───[oooooo]───[ooooooo]──────────┘ 56 | ││││││ 57 | │││││└─ VCC 58 | ││││└── A 59 | │││└─── B 60 | ││└──── GND 61 | │└───── K+ 62 | └────── K- 63 | ``` 64 | 65 | ## Schematics 66 | 67 | ``` 68 | 69 | K- o-------[ 100kΩ ]-----o / 70 | /---| 71 | K+ o---------------------o/ 72 | 73 | ``` 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | ## References 89 | 90 | * https://de.aliexpress.com/item/1005003451100409.html 91 | * https://diysolarforum.com/threads/heltec-jk-200a-smart-bms-with-2a-active-balance.17831/page-27#post-472301 92 | * https://forum.drbacke.de/viewtopic.php?p=22931 93 | -------------------------------------------------------------------------------- /docs/jk-bms-manual-1520084771.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/jk-bms-manual-1520084771.pdf -------------------------------------------------------------------------------- /docs/jkbms-ble-connected-capture.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Uksa007/esphome-jk-bms-can/cb24f7437dfa2fbb4e6c2409f1fb122b9b65ac2e/docs/jkbms-ble-connected-capture.zip -------------------------------------------------------------------------------- /docs/protocol-design.md: -------------------------------------------------------------------------------- 1 | # JK-BMS protocol design 2 | 3 | ## Request / Response example 4 | 5 | ``` 6 | >>> 4E 57 00 13 00 00 00 00 06 03 00 00 00 00 00 00 68 00 00 01 29 7 | ``` 8 | 9 | ``` 10 | <<< 4E 57 01 1B 00 00 00 00 06 00 01 11 | 79 2A 12 | 01 0E ED 13 | 02 0E FA 14 | 03 0E F7 15 | 04 0E EC 16 | 05 0E F8 17 | 06 0E FA 18 | 07 0E F1 19 | 08 0E F8 20 | 09 0E E3 21 | 0A 0E FA 22 | 0B 0E F1 23 | 0C 0E FB 24 | 0D 0E FB 25 | 0E 0E F2 26 | 80 00 1D 27 | 81 00 1E 28 | 82 00 1C 29 | 83 14 EF 30 | 84 80 D0 31 | 85 0F 32 | 86 02 33 | 87 00 04 34 | 89 00 00 00 00 35 | 8A 00 0E 36 | 8B 00 00 37 | 8C 00 07 38 | 8E 16 26 39 | 8F 10 AE 40 | 90 0F D2 41 | 91 0F A0 42 | 92 00 05 43 | 93 0B EA 44 | 94 0C 1C 45 | 95 00 05 46 | 96 01 2C 47 | 97 00 07 48 | 98 00 03 49 | 99 00 05 50 | 9A 00 05 51 | 9B 0C E4 52 | 9C 00 08 53 | 9D 01 54 | 9E 00 5A 55 | 9F 00 46 56 | A0 00 64 57 | A1 00 64 58 | A2 00 14 59 | A3 00 46 60 | A4 00 46 61 | A5 FF EC 62 | A6 FF F6 63 | A7 FF EC 64 | A8 FF F6 65 | A9 0E 66 | AA 00 00 00 0E 67 | AB 01 68 | AC 01 69 | AD 04 11 70 | AE 01 71 | AF 01 72 | B0 00 0A 73 | B1 14 74 | B2 31 32 33 34 35 36 00 00 00 00 75 | B3 00 76 | B4 49 6E 70 75 74 20 55 73 77 | B5 32 31 30 31 78 | B6 00 00 E2 00 79 | B7 48 36 2E 58 5F 5F 53 36 2E 31 2E 33 53 5F 5F 80 | B8 00 81 | B9 00 00 00 00 82 | BA 42 54 33 30 37 32 30 32 30 31 32 30 30 30 30 32 30 30 35 32 31 30 30 31 83 | C0 01 84 | 00 00 00 00 68 00 00 54 D1 85 | ``` 86 | 87 | ## Registers 88 | 89 | | RW | Code | Name | Bytes | Type | Info | 90 | | ---: | :--- | :-------------------------------------------------- | :---: | :---: | :--- | 91 | | R | 0x79 | Individual Cell voltage | 3*n | Hex | The first byte is the cell number, the next two bytes is the voltage value MV. When reading all the data at the same time, 0x79 is followed by one byte length data, n as shown above, and then a group of three bytes represents the | electricity Cell voltage. | 92 | | R | 0x80 | Read power tube temperature | 2 | Hex | 0-140 (-40 to 100) The part exceeding 100 is negative temperature, such as 101 is negative 1 degree (100 Benchmark) | 93 | | R | 0x81 | Read the temperature in the battery box | 2 | Hex | 0-140 (-40 to 100) The part exceeding 100 is negative temperature, the same as above (100 reference) | 94 | | R | 0x82 | Read battery temperature | 2 | Hex | 0-140 (-40 to 100) The part exceeding 100 is negative temperature, the same as above (100 reference) | 95 | | R | 0x83 | Total battery voltage | 2 | Hex | 0.01V 3500*0.01=35.00v minimum unit 10mV | 96 | | R | 0x84 | Current data | 2 | Hex | 10000 (10000-11000)*0.01=-10.00 A (discharge) (10000-9500)*0.01=5.00 A (charging) Accuracy 10 mA unit: 0.01 A Note: C0:0x01 redefine 0x84 current data, the unit is 10 mA, the highest bit is 0 Means discharging, 1 means charging If discharging 20 A, the data transmitted will be 2000 (0x07D0) If charging 20 A, the transmission data is 34768 (0x87D0) | 97 | | R | 0x85 | Battery remaining capacity | 1 | Hex | SOC, 0-100%, | 98 | | R | 0x86 | Number of battery temperature sensors | 1 | Hex | Two battery temperature sensors | 99 | | R | 0x87 | Number of battery cycles | 2 | Hex | | 100 | | R | 0x89 | Total battery cycle capacity | 4 | Hex | Anshi | 101 | | R | 0x8a | Total number of battery strings | 2 | Hex | | 102 | | R | 0x8b | Battery warning message | 2 | Bitmask | See ^1 | 103 | | R | 0x8c | Battery status information | 2 | Bitmask | 0 bit charging MOS tube state 1 on 0 off This is for upload prompt 1 bit discharge MOS tube state 1 on 0 off This is for upload prompts. 2-position balance switch state 1 on, 0 off, this is for uploading prompts 3 battery dropped 1 is normal. 0 is offline, this is the upload prompt, Bits 4-15: reserved example: 00 01: Indicates that the charging MOS tube is turned on | 104 | | RW | 0x8e | Total voltage overvoltage protection | 2 | Hex | 1000-15000 (10 mV) Minimum unit 10mV | 105 | | RW | 0x8f | Total voltage undervoltage protection | 2 | Hex | 1000-15000 (10 mV) Minimum unit 10mV | 106 | | RW | 0x90 | Single overvoltage protection voltage | 2 | Hex | 1000-4500 mV | 107 | | RW | 0x91 | Cell overvoltage recovery voltage | 2 | Hex | 1000-4500 mV | 108 | | RW | 0x92 | Single overvoltage protection delay | 2 | Hex | 1-60 seconds | 109 | | RW | 0x93 | Single undervoltage protection voltage | 2 | Hex | 1000-4500 mV | 110 | | RW | 0x94 | Monomer undervoltage recovery voltage | 2 | Hex | 1000-4500 mV | 111 | | RW | 0x95 | Single undervoltage protection delay | 2 | Hex | 1-60 seconds | 112 | | RW | 0x96 | Cell pressure difference protection value | 2 | Hex | 0-1000 mV | 113 | | RW | 0x97 | Discharge overcurrent protection value | 2 | Hex | 1-1000 A | 114 | | RW | 0x98 | Discharge overcurrent delay | 2 | Hex | 1-60 seconds | 115 | | RW | 0x99 | Charging overcurrent protection value | 2 | Hex | 1-1000 A | 116 | | RW | 0x9a | Charge overcurrent delay | 2 | Hex | 1-60 seconds | 117 | | RW | 0x9b | Balanced starting voltage | 2 | Hex | 2000-4500 mV | 118 | | RW | 0x9c | Balanced opening pressure difference | 2 | Hex | 10-1000 mV | 119 | | RW | 0x9d | Active balance switch | 1 | Hex | 0 (off), 1 (on) | 120 | | RW | 0x9e | Power tube temperature protection value | 2 | Hex | 0-100 | 121 | | RW | 0x9f | Power tube temperature recovery value | 2 | Hex | 0-100 | 122 | | RW | 0xa0 | Temperature protection value in the battery box | 2 | Hex | 40-100 | 123 | | RW | 0xa1 | Temperature recovery value in the battery box | 2 | Hex | 40-100 | 124 | | RW | 0xa2 | Battery temperature difference protection value | 2 | Hex | 5-20 | 125 | | RW | 0xa3 | Battery charging high temperature protection value | 2 | Hex | 0-100 | 126 | | RW | 0xa4 | Battery discharge high temperature protection value | 2 | Hex | 0-100 | 127 | | RW | 0xa5 | Charging low temperature protection value | 2 | Hex | -45 /+25 (no reference-signed data) | 128 | | RW | 0xa6 | Charging low temperature protection recovery value | 2 | Hex | -45 /+25 (no reference-signed data) | 129 | | RW | 0xa7 | Discharge low temperature protection value | 2 | Hex | -45 /+25 (no reference-signed data) | 130 | | RW | 0xa8 | Discharge low temperature protection recovery value | 2 | Hex | -45 /+25 (no reference-signed data) | 131 | | RW | 0xa9 | Battery string setting | 1 | Hex | 3-32 | 132 | | RW | 0xaa | Battery capacity setting | 4 | Hex | Ah (Amp Hour) | 133 | | RW | 0xab | Charging MOS tube switch | 1 | Hex | 0 (off), 1 (open) | 134 | | RW | 0xac | Discharge MOS tube switch | 1 | Hex | 0 (off), 1 (open) | 135 | | RW | 0xad | Current calibration | 2 | Hex | 100-20000 mA | 136 | | RW | 0xae | Protection board address | 1 | Hex | is reserved for use when cascading, | 137 | | RW | 0xaf | Battery Type | 1 | Hex | 0 (lithium iron phosphate), 1 (ternary), 2 (lithium titanate) | 138 | | RW | 0xb0 | Sleep waiting time | 2 | Hex | second data, temporarily for reference | 139 | | RW | 0xb1 | Low volume alarm value | 1 | Hex | 0-80 % | 140 | | RW | 0xb2 | Modify parameter password | 10 | Hex | is temporarily used as a reference, fix a password, | 141 | | RW | 0xb3 | Dedicated charger switch | 1 | Hex | 0 (off), 1 (on) | 142 | | RW | 0xb4 | Device ID code | 8 | Char | Example 60300001 (60-nominal voltage level: defined by the voltage level, for example, 60 is 60V. Series 48 is 48V series; 3-material system: according to the system definition of battery materials such as iron. Lithium code is 1 manganic acid code 2 ternary code 3; 00001-production serial number: according to manufacturing. The Nth group of the model produced by the manufacturer that month is numbered N (for example: a certain type The first group of the number, then N is 00001)) characters | 143 | | RW | 0xb5 | Date of manufacture | 4 | Char | Example 2004-production year: take the last two digits according to the actual production year; list the production in 2020, Battery, year code 20; Production month: 01-12 months; | 144 | | RW | 0xb6 | System working hours | 4 | Hex | is cleared when leaving factory, unit minute | 145 | | R | 0xb7 | Software version number | 15 | Char | NW_1_0_0_200428 | 146 | | RW | 0xb8 | Whether to start current calibration | 1 | Hex | 1 (Start calibration) 0 (Close calibration) | 147 | | RW | 0xb9 | Actual battery capacity | 4 | Hex | Ah (Amp Hour) | 148 | | RW | 0xba | Manufacturer ID naming | 24 | Char | See ^2 | 149 | | W | 0xbb | Restart the system | 1 | Hex | 1 (Restart the system) | 150 | | W | 0xbc | reset | 1 | Hex | 1 (Restore) (only restore the factory reference parameters) | 151 | | W | 0xbd | Remote upgrade logo | 1 | Hex | Start of Hex 1 (wait for logo response when issuing documents) | 152 | | W | 0xbe | Battery low voltage turns off GPS | 2 | Hex | unit: mV ( turn off the power to GPS when low voltage is detected ) | 153 | | W | 0xbf | Battery low voltage recovery GPS | 2 | Hex | unit: mV ( turn on the power to the GPS when the recovery voltage value is detected ) | 154 | | R | 0xc0 | Protocol version number | 1 | Hex | Default value: 0x00 0x01: Redefine 0x84 current data, the unit is 10 mA, and the highest bit is 0 for discharging. 1 means charging If discharging 20A, the data transmitted will be 2000 (0x07D0) If charging 20A, the transmission data is 34768 (0x87D0) | 155 | 156 | *^1: Battery warning message 157 | 158 | | Bit | Description | Values | Severity | 159 | | --- | ----------------------------------- | --------------------- | -------- | 160 | | 0 | Low capacity alarm | 1 (alarm), 0 (normal) | warning | 161 | | 1 | MOS tube over-temperature alarm | 1 (alarm), 0 (normal) | alarm | 162 | | 2 | Charging over-voltage alarm | 1 (alarm), 0 (normal) | alarm | 163 | | 3 | Discharge undervoltage alarm | 1 (alarm), 0 (normal) | alarm | 164 | | 4 | Battery over temperature alarm | 1 (alarm), 0 (normal) | alarm | 165 | | 5 | charging overcurrent alarm | 1 (alarm), 0 (normal) | alarm | 166 | | 6 | Discharge overcurrent alarm | 1 (alarm), 0 (normal) | alarm | 167 | | 7 | Cell pressure difference alarm | 1 (alarm), 0 (normal) | alarm | 168 | | | | | | 169 | | 8 | Over-temperature alarm in the battery box | 1 (alarm), 0 (normal) | alarm | 170 | | 9 | Battery low temperature alarm | 1 (alarm), 0 (normal) | alarm | 171 | | 10 | Monomer overvoltage alarm | 1 (alarm), 0 (normal) | alarm | 172 | | 11 | Monomer undervoltage alarm | 1 (alarm), 0 (normal) | alarm | 173 | | 12 | 309_A protection | 1 (alarm), 0 (normal) | alarm | 174 | | 13 | 309_A protection | 1 (alarm), 0 (normal) | alarm | 175 | | 14 | Reserved | | | 176 | | 15 | Reserved | | | 177 | 178 | **Example** 179 | 180 | 0x0001 = 00000000 00000001: Low capacity alarm \ 181 | 0x0002 = 00000000 00000010: MOS tube over-temperature alarm \ 182 | 0x0003 = 00000000 00000011: Low capacity alarm AND MOS tube over-temperature alarm 183 | 184 | 185 | *^2: Manufacturer ID naming (24 chars) 186 | 187 | Example value: BT3072020120000200521001 -> BT 3 072 020 12 0000 20 05 21 001 188 | 189 | | Value | Description | Known values | 190 | | ----- | ----------------- | --------------------------------------------------------- | 191 | | BT | Product name | BT for battery | 192 | | 3 | Battery type | 1 (Iron-Lithium), 2 (Mangenese acid), 3 (Ternary code) | 193 | | 072 | Voltage level | 48V, 60V, 72V | 194 | | 020 | Capacity grade | 20 for 20AH | 195 | | 12 | Cycle life | 4 (400 cycles), 12 (1200 cycles) | 196 | | 0000 | Manufacturer code | | 197 | | 20 | Production year | 20 (2020), 21 (2021) | 198 | | 05 | Production month | 1-12 | 199 | | 21 | Production day | 1-31 | 200 | | 0001 | Production serial number | According to the Nth group of the model produced on the day of the manufacturer’s production date, The number is N (for example: the first group of a certain model, then 001) | 201 | 202 | -------------------------------------------------------------------------------- /firmware/Readme: -------------------------------------------------------------------------------- 1 | Readme 2 | --------------------------------------------------------------------------------