A high-performance, real-time telemetry streaming and fleet control platform for Jikong (JK) BMS units. This platform enables concurrent monitoring and parameter configuration over both Bluetooth Low Energy (BLE) and Wired RS485 (Modbus RTU) interfaces.
- WebSocket Real-Time Telemetry Streaming (
/ws/telemetry): Low-latency, reactive broadcast loop streaming live pack metrics (voltage, current, SOC, capacity, temperatures, cell delta) to all connected clients every 2 seconds. - Rich Fleet Dashboard & UI Widgets: Dynamic State-of-Charge (SOC) progress indicators, color-coded health pills, cell min/max highlights, and collapsible raw data payloads.
- Auto-Discovery of Serial Ports & BLE MACs: Dynamic serial port detection (
/dev/ttyUSB0,COM3, etc.) and one-click BLE device scanning with auto-populated MAC addresses. - Bulk Parameter Write with Safe Preview Modal: Dry-run preview modal showing target battery packs and proposed parameter changes before committing bulk writes.
- RS485 Wired Inspector: Ad-hoc diagnostic interrogation tool for inspecting unlisted or offline packs directly over serial.
- Battery Chemistry Detection Engine: Automated battery chemistry classifier analyzing cell voltage spreads and protection thresholds (LiFePO4, NMC, LTO) with confidence scores and diagnostic rationale.
- Single-File Cross-Platform Executables: Bundled PyInstaller script for generating zero-dependency
.exe(Windows) and ELF (Linux) binaries.
- Backend Framework: Python 3.10+ & FastAPI
- Real-time Protocol: WebSockets (
websockets) & asyncio background broadcast worker - Hardware Drivers:
bleakfor concurrent Bluetooth Low Energy connectionspyserial& custom sliding-window Modbus RTU frame parser for RS485 serial communication
- Frontend: HTML5, Vanilla CSS3, ES6 JavaScript
- Database & Persistence: JSON-backed local device registry (
devices.json)
- Python 3.10 or higher
- USB-to-RS485 adapter (for wired Modbus communication) and/or Bluetooth 4.0+ BLE adapter
-
Clone the repository:
git clone https://github.com/Nyaigoti/BMS.git cd BMS -
Install dependencies:
pip install -r requirements.txt
-
Run the server:
uvicorn main:app --reload
-
Access the web interface: Open your browser and navigate to
http://127.0.0.1:8000.
To generate a single-file executable for distribution without Python dependencies:
python3 build_exe.pyThe output binary will be created in the dist/ directory:
- Linux:
dist/Songa_BMS - Windows:
dist/Songa_BMS.exe
WS /ws/telemetry: Real-time JSON telemetry stream for all connected BMS units.
GET /api/bms: List all registered battery packs and their live status.POST /api/bms/new: Add a new battery pack to the fleet registry.GET /api/bms/ports: Dynamically list connected serial COM ports (/dev/ttyUSB0,COM3, etc.).GET /api/bms/wired/read: Ad-hoc read of a wired pack connected to a specific serial port.
GET /api/bms/{id}/settings: Fetch full protection and system settings from a pack.POST /api/bms/{id}/settings: Write individual settings to a pack (with read-back verification).POST /api/bms/bulk_settings: Perform verified bulk settings update across selected packs.POST /api/bms/{id}/transport: Hot-swap transport mode between BLE and RS485.
Collins Nyaigoti Date: 3/8/2026