jk_bms / jktool
Async Rust implementation of jktool — a library and command-line tool for communicating with JIKONG (JK) Battery Management Systems.
Supports the JK02 (24S/32S) and JK04 protocol variants, with automatic detection based on the BMS model string. Provides a reusable async library (jk_bms) and a CLI (jktool).
Features
- Async-first:
Transporttrait and session API are fullyasyncon a Tokio runtime - Reusable transports: ready-to-use [
Transport] implementations shipped in the library ([jk_bms::transport]) so consumers don't need their own link layer - Multi-transport: Serial (
tokio-serial) and Bluetooth LE cross-platform, CAN (SocketCAN) on Linux — sametransport:targetsyntax as the original - Readiness-based I/O: everything is driven by real async I/O (
tokio-serial,socketcan's tokio socket, and btleplug's notificationStream) — no busy polling - Protocol support: JK02_24S, JK02_32S (PB2/BD/HY series), JK04 (auto-detected from info frame)
- Live data: cell voltages, temperatures, SOC/SOH, power, errors, MOSFET states
- Settings read/write: full register map with human-readable names, scaling, and write-frame generation
- Output formats: text, CSV, JSON (with pretty-print)
- BLE frame assembly: reassembles 300-byte JK frames from small BLE MTU chunks with CRC verification
Platform support
| Platform | Bluetooth LE (bluetooth) |
Serial (serial) |
CAN (can) |
|---|---|---|---|
| Linux | ✅ | ✅ | ✅ |
| macOS | ✅ | ✅ | — |
| Windows | ✅ | ✅ | — |
Each transport is behind a cargo feature (all three on by default). CAN uses Linux
SocketCAN, so the can feature is inert on non-Linux targets.
Install
CLI:
Library:
Default features are bluetooth, serial, and can. The bluetooth feature links
libdbus on Linux (sudo apt install libdbus-1-dev). Pick only what you need:
CLI usage
Transports are specified as transport:target[,options] — same syntax as the original jktool.
# Read live data (default action)
# Read settings
# Write a setting
# List supported settings
# Output to file as JSON
# Scan for Bluetooth devices
# Scan for JK BMS devices on a CAN bus (Linux)
Library usage
The jk_bms crate exposes the async Transport/JkSession API as well as the pure
protocol codec (getdata, FrameAssembler, command builders), which is transport-agnostic
and has no async requirements.
Decoding frames (no transport)
use ;
let mut pack = new;
let mut assembler = new;
// Feed raw bytes from any source; decodes once a full CRC-valid frame is buffered.
if let Some = assembler.feed_and_decode
Talking to a BMS with a built-in transport
The library ships ready-to-use transports in [jk_bms::transport], so consumers don't
need to implement the link layer themselves. Example over Bluetooth LE:
use ;
use BluetoothTransport;
async
Discover nearby BLE devices with [jk_bms::transport::scan] (re-exported as bt_scan);
each [BtDevice] carries a stable id to use as the target. [SerialTransport] and,
on Linux, [CanTransport] are available the same way.
Custom transport
To drive some other link, implement the async Transport trait yourself:
use ;
Protocol versions
| Version | Models | Cell voltages | Max cells |
|---|---|---|---|
| JK02_24S | JK-B2AxxS | 2-byte LE mV | 24 |
| JK02_32S | JK_PB2, JK-BD, JK_HY | 2-byte LE mV (16-byte offset) | 32 |
| JK04 | Older JK-BMS | IEEE 754 float | 24 |
Auto-detected from the BMS info frame model string.
License
MIT