esphome-jk-bms: reading a Jikong JK-BMS from ESPHome over UART or BLE

What the esphome-jk-bms component is for

esphome-jk-bms is an ESPHome component for the Jikong JK-BMS, a battery management system used with lithium battery packs in DIY and small commercial storage builds. The repository description says it can monitor and control such a system via UART-TTL or BLE, and the README's own heading is narrower, describing the component as a way to monitor a JK-BMS over UART-TTL or BLE.

The problem it solves is the one every owner of a JK-BMS hits: the vendor's own app tells you what the battery is doing, but it does not put that data into your home automation stack. A JK-BMS exposes cell voltages, pack current, state of charge, temperature and protection status, and with this component those values become ESPHome sensors, which means they can be logged, plotted, alerted on and used in automations. The README shows a Lovelace entities card, which is the Home Assistant view of exactly that.

The audience is therefore a specific person: someone who has already chosen a JK-BMS, already has a working pack, and wants the telemetry inside Home Assistant. The component is not a general battery monitor and not a charge controller. It is a protocol implementation that turns one manufacturer's wire format into ESPHome entities.

The implementation is C++, and the surrounding repository is laid out the way an ESPHome external component usually is. There is a components/ directory holding the code, a docs/ directory, and then the part of the tree that tells you most about the project's scope: a long set of ready-made example configurations, one for each transport, board family and scenario, at the top level of the repository.

Which JK-BMS models the protocol implementation covers

The README gives a clear rule before it gives a list: all JK-BMS models with software version 6.0 or higher use the implemented protocol and should be supported.

That rule is the single most useful line for a prospective user, because it separates the component from a device list that is really a compatibility ledger. A BMS whose firmware predates 6.0 speaks a different protocol and is out of scope, whatever its hardware.

The list that follows is long and specific in a way that tells you how the support was established. Each entry names a model, its hardware revision and its software version, and in most cases attributes the report to the person who supplied it, with a link to the issue or discussion where it was confirmed. Models such as JK-BD6A17S6P at hw 7.2, sw 7.1.0H and JK-BD6A20S12P at hw 11.XW, sw 11.281 appear alongside hardware revisions running from 6.x up to 19.h.

Two things stand out. The hardware revision moves independently of the software version, which is why both are recorded, and the same model appears with different hardware revisions, such as JK-BD6A24S10P appearing at hw 8.x, sw 8.0.6G and at hw 10.xw, sw 10.09. Anyone reading the list for their own battery should look for their model and revision together, not for their model alone.

The list is also a picture of how this kind of support is actually built. Entries are added as users confirm them, which is why the attribution lines are so prominent. The weakness of the arrangement is the same one: the list is community-reported, so an unreported combination is not evidence of incompatibility, it is just missing.

UART-TTL, BLE, and what JK02_24S and JK02_32S actually select

The component supports two transports, and the README is careful about a detail that would otherwise cost a user an afternoon.

The BLE options JK02_24S and JK02_32S select frame formats, not the battery's cell count. The names look like cell counts, 24 cells and 32 cells, and reading them that way leads to the wrong choice. The README's advice is to use reports for the same model and hardware revision when choosing between them, which is exactly the discipline the device table makes possible.

The table then shows how often the two options are mixed for the same unit. A JK-BD6A24S12P at hw 11.XW, sw 11.36 is recorded using JK02_32S over BLE, while a JK-BD4A17S4P at hw 11.xw, sw 11.27 is recorded as using JK02_32S and/or UART-TTL. Several entries show both transports working against the same hardware, and some note UART-TTL specifically, which matters because a serial connection is the one you can inspect with a logic analyser when something is not working.

Choosing between the transports is therefore a hardware and preference decision. UART-TTL is a wired connection to a specific data port, which is stable and inspectable. BLE avoids the wire, which suits a pack that is sealed, and the repository's topic tags list bluetooth and uart alongside esphome and jikong-bms. There is also a hybrid example file in the tree, named esp32-ble-uart-hybrid-example.yaml, which suggests the two can be combined, though the README excerpt does not describe the arrangement in detail.

Working with the example configurations in the repository

The repository ships its example configurations at the top level rather than in a folder, and their names are the fastest way to understand the component's scope. A representative selection:

esp32-example.yaml
esp32-ble-example.yaml
esp32-ble-uart-hybrid-example.yaml
esp32-jk-pb-modbus-example.yaml

The pattern is a board family first, then the transport or device variant. There are esp32-example and esp8266-example files for the two board families the project targets, and each has a ble counterpart, so a plain UART setup, a Bluetooth LE setup, a hybrid of the two, and a JK-PB over Modbus arrangement are all present as starting points. The presence of an esp8266 example is worth noting in itself, since it means the component is not tied to the ESP32.

Beyond the base cases the tree splits by scenario: display examples, active-balancer examples, a scanner example, multiple-devices examples, and the Heltec balancer variants, whose file names include the ek-b24s8e200a model. The topic tags list heltec-balancer and neey-balancer, so balancer hardware is an established use case rather than an experiment.

Some example names carry qualifiers, and the README excerpt does not define them, so the names are the only guide available: there are -debug variants, -faker variants, and one file with a numbered suffix. The documentation folder in the repository is where those definitions would live, and it is the first place to look before copying an example that is not a plain one.

The examples are what makes this usable without deep protocol knowledge, and copying the closest match is faster than writing a configuration from nothing. What you should see after flashing is the set of sensors appearing in ESPHome's logs and in the Home Assistant device page.

Where the component is the wrong tool

The first limit is the firmware rule. A JK-BMS with software older than 6.0 is not supported, and no amount of configuration changes that, because the protocol itself differs. That is a hard boundary rather than a rough edge, and it is worth checking the version on the pack before anything else.

The second limit is the direction of travel. The repository description says the component can monitor and control the BMS, while the README heading describes monitoring over UART-TTL or BLE. The excerpt that documents the component does not set out the control side: which settings can be written, what the write path looks like in YAML, and what protections apply. For a component that can send commands to the safety system of a battery pack, that gap matters, and it means the write path has to be read in the docs/ folder rather than assumed from the description.

The third limit is that this is one manufacturer's protocol. A Home Assistant user with a different BMS, an inverter with its own monitoring port, or a pack with a proprietary app is not served here at all, and the answer for them is a different component rather than a different setting in this one.

The fourth limit is the sensor list versus the device list. The README proves that a large number of hardware and firmware combinations have been tested by users, and it does not enumerate the sensors, the entities or the full option set. Anyone planning a dashboard needs to read the actual configuration and the documentation, because the device table will not tell you what a JK-BMS exposes.

The alternative approach is not another component for the same device but a different ownership model for the telemetry. A vendor app answers the same question about a pack's state without a second device, without a Bluetooth or serial link and without any protocol work on your part, and the trade is that the readings stay inside the vendor's app. The component is worth its effort when you want history in Home Assistant, thresholds in your own automations, and no dependency on the vendor's servers, and it is not worth it when you only want to check the charge level now and then.

Maintenance, tooling and the licence

The project is not archived, the last push was on 2026-10-14, and the release line has moved briskly through 2026: 2.4.0 on 2026-03-23, 2.5.0 on 2026-05-21 and 3.0.0 on 2026-05-25. A major version in a component like this usually means a configuration change for users, so the upgrade notes in the 3.0.0 release are worth reading before you flash it over a working 2.x setup.

The repository shows a project that takes its own quality gates seriously. There is a CI workflow badge in the README, a .pre-commit-config.yaml, and separate linters for C++ and for the Python tooling: .clang-format and .clang-tidy for the component, and .flake8 plus a .yamllint for the configuration examples. The pyproject.toml in the tree configures ruff and pylint for the Python side, and one of its comments says it mirrors ESPHome's own pyproject.toml, which is a sensible way to keep the tooling in step with the upstream project this component plugs into.

The licence is Apache-2.0, with a LICENSE file at the root of the repository. That is permissive, includes an express patent grant, and does not impose the copyleft obligations that would apply to a derivative you distribute, which suits an integration component that people are expected to fork for their own hardware.

The maintenance story has one more dimension: the topic tags include hacktoberfest, which means the project takes outside contributions, and the device table shows how that process has been used, with user reports added model by model and revision by revision. For a protocol implementation, that is the healthy pattern, since the people who own the unusual hardware are the ones who can test it.

Editorial conclusion

esphome-jk-bms fits a Home Assistant user who owns a JK-BMS with software version 6.0 or later and wants cell voltages, current and state of charge in a dashboard instead of a vendor app, and who is comfortable running a small ESP32. It does not fit someone whose BMS firmware predates 6.0, or a project that needs the write and control side documented, which the README excerpt does not cover. Verify first that your model and hardware revision appear in the supported devices table, and that the BLE frame option you pick, JK02_24S or JK02_32S, matches the report for your unit, since those names select a frame format rather than a cell count.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. syssi/esphome-jk-bms on GitHub