{"id":18041621,"url":"https://github.com/katyo/ubmsc-rs","last_synced_at":"2025-07-20T00:32:33.522Z","repository":{"id":256389187,"uuid":"855142692","full_name":"katyo/ubmsc-rs","owner":"katyo","description":"Tool for interacting with Battery Management Systems (BMS).","archived":false,"fork":false,"pushed_at":"2024-09-12T15:38:27.000Z","size":39,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-18T01:30:28.249Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-10T11:38:46.000Z","updated_at":"2025-07-01T19:20:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"980b9398-701b-4320-8567-7a0a8e38bc7e","html_url":"https://github.com/katyo/ubmsc-rs","commit_stats":null,"previous_names":["katyo/ubmsc-rs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/katyo/ubmsc-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fubmsc-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fubmsc-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fubmsc-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fubmsc-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katyo","download_url":"https://codeload.github.com/katyo/ubmsc-rs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fubmsc-rs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266048588,"owners_count":23868742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T16:11:03.178Z","updated_at":"2025-07-20T00:32:33.513Z","avatar_url":"https://github.com/katyo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BMS BLE tool\n\n[![github](https://img.shields.io/badge/github-katyo/ubmsc--rs-8da0cb.svg?style=for-the-badge\u0026logo=github)](https://github.com/katyo/ubmsc-rs)\n[![crate](https://img.shields.io/crates/v/ubmsc.svg?style=for-the-badge\u0026color=fc8d62\u0026logo=rust)](https://crates.io/crates/ubmsc)\n[![docs](https://img.shields.io/badge/docs.rs-ubmsc-66c2a5?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/ubmsc)\n[![MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)\n[![CI](https://img.shields.io/github/actions/workflow/status/katyo/ubmsc-rs/ci.yml?branch=master\u0026style=for-the-badge\u0026logo=github-actions\u0026logoColor=white)](https://github.com/katyo/ubmsc-rs/actions?query=workflow%3ARust)\n\nThis is a tool for interacting with some customer-grade Battery Management\nSystems (BMS).\n\n## Inplemented features\n\n- Discovering compatible BLE devices\n- Identifying devices by address or name\n- Querying device info\n- Fetching cells data\n- Command-line interface\n- Prometheus exporter\n- Prometheus push gateway client\n\n## Supported models and firmware versions\n\n| Vendor     | Model    | HW Version | SW Version |\n|------------|----------|------------|------------|\n| JiKong BMS | BD4A8S4P | 15A        | 15.26      |\n\nI'm happy to add support for other models in the future.\nPlease open PR or create issue.\n\n## Crate usage examples\n\nGet device info and cells data by device name:\n```rust,no_run\nuse btleplug::{api::Manager as _, platform::Manager};\nuse ubmsc::Client;\n\n#[tokio::main(flavor = \"current_thread\")]\npub async fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let manager = Manager::new().await?;\n\n    let adapter = manager\n        .adapters()\n        .await?\n        .into_iter()\n        .next()\n        .ok_or(\"No adapters found\")?;\n\n    let client = Client::new(\u0026adapter, \u0026\"UPS_BMS\".into(), \u0026Default::default());\n\n    let info = client.device_info().await?;\n    println!(\"{info:?}\");\n\n    let data = client.cell_data().await?;\n    println!(\"{data:?}\");\n\n    client.close().await?;\n\n    Ok(())\n}\n```\n\nFind available BMS devices and print device info:\n```rust,no_run\nuse btleplug::{api::Manager as _, platform::Manager};\nuse ubmsc::Client;\n\n#[tokio::main(flavor = \"current_thread\")]\npub async fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let manager = Manager::new().await?;\n\n    let adapter = manager\n        .adapters()\n        .await?\n        .into_iter()\n        .next()\n        .ok_or(\"No adapters found\")?;\n\n    for device in Client::find(\u0026adapter, \u0026Default::default()).await? {\n        let client = Client::new(\u0026adapter, \u0026\"UPS_BMS\".into(), \u0026Default::default());\n\n        let name = client.device_name().await?;\n        let info = client.device_info().await?;\n        println!(\"{name}\");\n        println!(\"{info:?}\");\n\n        client.close().await?;\n    }\n\n    Ok(())\n}\n```\n\n## Command-line usage examples\n\nShow help:\n```plain\n$ ubmsc --help`\n```\n```plain\nUsage: ubmsc [-v] [-l \u003cfilter\u003e] [-j] [-t \u003cseconds\u003e] [-r \u003cseconds\u003e] [-d \u003caddress...\u003e]\n             [-f \u003cformat\u003e] [-i] [-c] [-e] [-p] [-u \u003curl\u003e] [-s \u003cseconds\u003e]\n\nBattery Management Systems (BMS) interface.\n\nWhen passed both -e and -p options push client will be run in continuous mode with specified interval.\n\nOptions:\n  -v, --version                    Show version and exit.\n  -l, --log \u003cfilter\u003e               Logging filter (example: jk_bms=debug)\n  -j, --journal                    Enable log to journald (log to stderr by default)\n  -t, --scan-timeout \u003cseconds\u003e     Bluetooth scanning timeout in seconds (30 by default)\n  -r, --request-timeout \u003cseconds\u003e  Bluetooth request timeout in seconds (5 by default)\n  -d, --devices \u003caddress\u003e          Device addresses or names (will try to scan if nothing passed)\n  -f, --format \u003cformat\u003e            Data format: rust(r) (by default) rust-pretty(R) json(j)\n                                   json-pretty(J) yaml(y) toml(t) toml-pretty(T) metrics(m)\n  -i, --device-info                Show device info\n  -c, --cell-data                  Show cell data\n  -e, --exporter                   Run prometheus exporter\n  -p, --push                       Run prometheus push gateway client\n  -u, --url \u003curl\u003e                  Prometheus exporter URL to listen/connect\n  -s, --scrape-interval \u003cseconds\u003e  Metrics scraping interval (60s by default)\n  -h, --help                       Show this help message and exit.\n```\n\nGet device info by device name and output in JSON format:\n```plain\n$ ubmsc -f J -i -d UPS_BMS\n```\n```json\n{\n  \"device_info\": [\n    {\n      \"device_model\": \"JK_BD4A8S4P\",\n      \"hardware_version\": \"15A\",\n      \"software_version\": \"15.26\",\n      \"up_time\": 1709100,\n      \"poweron_times\": 1,\n      \"device_name\": \"UPS_BMS\",\n      \"device_passcode\": \"1234\",\n      \"manufacturing_date\": \"240818\",\n      \"serial_number\": \"40531310629\",\n      \"passcode\": \"000\",\n      \"userdata\": \"JK-BMS\",\n      \"setup_passcode\": \"123456789\",\n      \"userdata2\": \"JK-BMS\"\n    }\n  ]\n}\n```\n\nScan BLE to find devices and print device info and cells data in TOML format:\n```plain\n$ ubmsc -f t -i -c\n```\n```toml\n[[device_info]]\ndevice_model = \"JK_BD4A8S4P\"\nhardware_version = \"15A\"\nsoftware_version = \"15.26\"\nup_time = 1707500\npoweron_times = 1\ndevice_name = \"UPS_BMS\"\ndevice_passcode = \"1234\"\nmanufacturing_date = \"240818\"\nserial_number = \"40531310629\"\npasscode = \"000\"\nuserdata = \"JK-BMS\"\nsetup_passcode = \"123456789\"\nuserdata2 = \"JK-BMS\"\n[[cell_data]]\ncell_voltage = [2.384000062942505, 2.384000062942505, 2.383000135421753, 2.384000062942505, 2.384000062942505, 2.384000062942505]\naverage_cell_voltage = 2.384000062942505\ndelta_cell_voltage = 0.0010000000474974513\nbalance_current = 1.0240000486373901\ncell_resistance = [0.1380000114440918, 0.13700000941753387, 0.14000000059604645, 0.1380000114440918, 0.13900001347064972, 0.13900001347064972]\nbattery_voltage = 14.304000854492188\nbattery_power = 2.2310001850128174\nbattery_current = 0.15600000321865082\nbattery_temperature = [23.200000762939453, 23.600000381469727]\nmosfet_temperature = 25.399999618530273\nremain_percent = 100\nremain_capacity = 12.000000953674316\nnominal_capacity = 12.000000953674316\ncycle_count = 1\ncycle_capacity = 18.464000701904297\nup_time = 1707600\n```\n\nShow BMS cell data in Prometheus metrics format:\n```plain\n$ ubmsc -f metrics -c -d UPS_BMS\n```\n```shell\n# HELP average_cell_voltage Average voltage of cells, V\n# TYPE average_cell_voltage gauge\naverage_cell_voltage{device=\"UPS_BMS\"} 2.385000228881836\n# HELP balance_current Cells balance current, A\n# TYPE balance_current gauge\nbalance_current{device=\"UPS_BMS\"} 0\n# HELP battery_current Current of battery, A\n# TYPE battery_current gauge\nbattery_current{device=\"UPS_BMS\"} 0.07800000160932541\n# HELP battery_power Power of battery, W\n# TYPE battery_power gauge\nbattery_power{device=\"UPS_BMS\"} 1.1160000562667847\n# HELP battery_temperature Temperatures of battery, ℃\n# TYPE battery_temperature gauge\nbattery_temperature{cell=\"0\",device=\"UPS_BMS\"} 22.80000114440918\nbattery_temperature{cell=\"1\",device=\"UPS_BMS\"} 23.200000762939453\n# HELP battery_voltage Voltage of battery, V\n# TYPE battery_voltage gauge\nbattery_voltage{device=\"UPS_BMS\"} 14.308000564575195\n# HELP cell_resistance Resistances of cells, Ω\n# TYPE cell_resistance gauge\ncell_resistance{cell=\"0\",device=\"UPS_BMS\"} 0.1380000114440918\ncell_resistance{cell=\"1\",device=\"UPS_BMS\"} 0.13700000941753387\ncell_resistance{cell=\"2\",device=\"UPS_BMS\"} 0.14000000059604645\ncell_resistance{cell=\"3\",device=\"UPS_BMS\"} 0.1380000114440918\ncell_resistance{cell=\"4\",device=\"UPS_BMS\"} 0.13900001347064972\ncell_resistance{cell=\"5\",device=\"UPS_BMS\"} 0.13900001347064972\n# HELP cell_voltage Voltages of cells, V\n# TYPE cell_voltage gauge\ncell_voltage{cell=\"0\",device=\"UPS_BMS\"} 2.386000156402588\ncell_voltage{cell=\"1\",device=\"UPS_BMS\"} 2.384000062942505\ncell_voltage{cell=\"2\",device=\"UPS_BMS\"} 2.384000062942505\ncell_voltage{cell=\"3\",device=\"UPS_BMS\"} 2.384000062942505\ncell_voltage{cell=\"4\",device=\"UPS_BMS\"} 2.384000062942505\ncell_voltage{cell=\"5\",device=\"UPS_BMS\"} 2.384000062942505\n# HELP cycle_capacity Cycle capacity, A·h\n# TYPE cycle_capacity counter\ncycle_capacity{device=\"UPS_BMS\"} 19.117000579833984\n# HELP cycle_count Number of battery cicles\n# TYPE cycle_count counter\ncycle_count{device=\"UPS_BMS\"} 1\n# HELP delta_cell_voltage Delta voltage of cells, V\n# TYPE delta_cell_voltage gauge\ndelta_cell_voltage{device=\"UPS_BMS\"} 0\n# HELP mosfet_temperature Temperature of mosfet, ℃\n# TYPE mosfet_temperature gauge\nmosfet_temperature{device=\"UPS_BMS\"} 24.899999618530273\n# HELP poweron_times Number of poweron cicles\n# TYPE poweron_times counter\npoweron_times{device=\"UPS_BMS\"} 1\n# HELP remain_capacity Remain capacity of battery, A·h\n# TYPE remain_capacity gauge\nremain_capacity{device=\"UPS_BMS\"} 12.000000953674316\n# HELP remain_percent Remain capacity of battery, %\n# TYPE remain_percent gauge\nremain_percent{device=\"UPS_BMS\"} 100\n# HELP up_time Time since last poweron, S\n# TYPE up_time counter\nup_time{device=\"UPS_BMS\"} 1770773\n```\n\nRun prometheus exporter for specified devices (with logging to journald):\n```plain\n$ ubmsc -e -u http://127.0.0.1:9898/metrics -l ubmsc=debug -j -d UPS_BMS -d SOLAR_BMS\n```\n\nRun prometheus pushgateway client continuously to export to VictoriaMetrics:\n```plain\n$ ubmsc -e -p -u http://127.0.0.1:8428/api/v1/import/prometheus -l ubmsc=info -j -d UPS_BMS -d SOLAR_BMS\n```\n\n## Alternative solutions\n\n- [MPP-Solar](https://github.com/jblance/mpp-solar)\n  Python module and command-line tools to work with BMS.\n  Has support several models of different vendors.\n  Doesn't work with JK-BMS with latest firmwares (\u003e11.x).\n- [esphome-jk-bms](https://github.com/syssi/esphome-jk-bms)\n  Component for ESPHome to interact with JK-BMS.\n  Not tested.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatyo%2Fubmsc-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatyo%2Fubmsc-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatyo%2Fubmsc-rs/lists"}