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 - Multi-transport: Serial and CAN (Linux), Bluetooth LE (cross-platform), with the same
transport:targetsyntax as the original - Readiness-based I/O: raw fds are driven by Tokio's reactor (
AsyncFd); BLE consumes the notificationStreamdirectly — 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 | Serial | CAN |
|---|---|---|---|
| Linux | ✅ | ✅ | ✅ |
| macOS | ✅ | — | — |
| Windows | ✅ | — | — |
Serial and CAN use Linux-specific APIs (termios / SocketCAN) and are compiled only on Linux.
Install
CLI:
Library:
The bluetooth feature is enabled by default. On Linux it links libdbus (sudo apt install libdbus-1-dev). To build without it:
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
Async transport
Implement the async Transport trait for your link, then drive a session:
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