# v0l/battery-control architecture

> Architecture diagram of the GitHub repository v0l/battery-control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/v0l/battery-control
- Repository: https://github.com/v0l/battery-control

## Overview

battery_control unifies battery, BMS, monitor, and power-station devices behind an async Battery trait and normalized status, capability, and command types. The primary workflow discovers or identifies a device, uses a backend adapter to obtain status or execute supported controls, then presents results through the CLI or bench UI. The README documents the breadth of backends and UI capabilities; several backend implementations are unsampled, so their internal protocol flows are not expanded here.

Main entry points: [`src/battery.rs`](https://github.com/v0l/battery-control/blob/main/src/battery.rs) (Battery Trait), [`src/types.rs`](https://github.com/v0l/battery-control/blob/main/src/types.rs) (Status and Commands), [`src/bin/battery/main.rs`](https://github.com/v0l/battery-control/blob/main/src/bin/battery/main.rs) (Battery CLI), [`crates/ui/src/worker.rs`](https://github.com/v0l/battery-control/blob/main/crates/ui/src/worker.rs) (Device Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_battery_cli["Battery CLI<br/>[main.rs]"]
  node_cli_output["CLI Output<br/>[output.rs]"]
end

subgraph group_core["Unified Battery API"]
  node_discovery["Device Discovery<br/>[discovery.rs]"]
  node_battery_trait["Battery Trait<br/>[battery.rs]"]
  node_capabilities["Capabilities<br/>[capabilities.rs]"]
  node_data_model["Status and Commands<br/>[types.rs]"]
  node_auth["Pairing State<br/>[auth.rs]"]
end

subgraph group_adapters["Backend Adapters"]
  node_anker_adapter["Anker Adapter<br/>[anker.rs]"]
  node_jk_adapter["JK Adapter<br/>[jk.rs]"]
  node_jbd_adapter["JBD Adapter<br/>[jbd.rs]"]
  node_pylon_adapter["Pylontech CAN<br/>[pylontech.rs]"]
  node_victron_adapter["Victron Adapter<br/>[victron.rs]"]
  node_other_adapters["Other Adapters"]
end

subgraph group_protocols["Device Protocols"]
  node_jk_pack["JK Pack Model<br/>[pack.rs]"]
  node_jk_bms["JK BMS Logic<br/>[bms.rs]"]
  node_ecoflow_packet["EcoFlow Packets<br/>[packet.rs]"]
  node_ecoflow_crypto["EcoFlow Curve Crypto<br/>[secp160r1.rs]"]
end

subgraph group_bench["Bench UI"]
  node_bench_ui["Bench Window<br/>[main.rs]"]
  node_ui_worker["Device Worker<br/>[worker.rs]"]
  node_demo_battery["Demo Battery<br/>[demo.rs]"]
end

node_user(("User"))

node_user -->|"runs commands"| node_battery_cli
node_battery_cli -->|"discovers devices"| node_discovery
node_battery_cli -->|"reads or controls"| node_battery_trait
node_battery_cli -->|"formats results"| node_cli_output
node_battery_trait -->|"uses normalized types"| node_data_model
node_battery_trait -->|"gates controls"| node_capabilities
node_anker_adapter -->|"implements"| node_battery_trait
node_anker_adapter -->|"maps telemetry"| node_data_model
node_anker_adapter -->|"handles pairing"| node_auth
node_jk_adapter -->|"implements"| node_battery_trait
node_jk_adapter -->|"maps device state"| node_data_model
node_jbd_adapter -->|"implements"| node_battery_trait
node_jbd_adapter -->|"maps device state"| node_data_model
node_pylon_adapter -->|"implements"| node_battery_trait
node_pylon_adapter -->|"normalizes readings"| node_data_model
node_victron_adapter -->|"implements"| node_battery_trait
node_other_adapters -->|"adapt device families"| node_battery_trait
node_jk_pack -->|"models pack for"| node_jk_bms
node_ecoflow_packet -.->|"supports session protocol"| node_ecoflow_crypto
node_user -->|"uses bench window"| node_bench_ui
node_bench_ui -->|"dispatches commands"| node_ui_worker
node_ui_worker -->|"scans devices"| node_discovery
node_ui_worker -->|"reads and controls"| node_battery_trait
node_ui_worker -->|"uses demo mode"| node_demo_battery

click node_battery_cli "https://github.com/v0l/battery-control/blob/main/src/bin/battery/main.rs"
click node_cli_output "https://github.com/v0l/battery-control/blob/main/src/bin/battery/output.rs"
click node_discovery "https://github.com/v0l/battery-control/blob/main/src/discovery.rs"
click node_battery_trait "https://github.com/v0l/battery-control/blob/main/src/battery.rs"
click node_capabilities "https://github.com/v0l/battery-control/blob/main/src/capabilities.rs"
click node_data_model "https://github.com/v0l/battery-control/blob/main/src/types.rs"
click node_auth "https://github.com/v0l/battery-control/blob/main/src/auth.rs"
click node_anker_adapter "https://github.com/v0l/battery-control/blob/main/src/backends/anker.rs"
click node_jk_adapter "https://github.com/v0l/battery-control/blob/main/src/backends/jk.rs"
click node_jbd_adapter "https://github.com/v0l/battery-control/blob/main/src/backends/jbd.rs"
click node_pylon_adapter "https://github.com/v0l/battery-control/blob/main/src/backends/pylontech.rs"
click node_victron_adapter "https://github.com/v0l/battery-control/blob/main/src/backends/victron.rs"
click node_other_adapters "https://github.com/v0l/battery-control/tree/main/src/backends"
click node_jk_pack "https://github.com/v0l/battery-control/blob/main/crates/jk_bms/src/pack.rs"
click node_jk_bms "https://github.com/v0l/battery-control/blob/main/crates/jk_bms/src/bms.rs"
click node_ecoflow_packet "https://github.com/v0l/battery-control/blob/main/crates/ecoflow/src/packet.rs"
click node_ecoflow_crypto "https://github.com/v0l/battery-control/blob/main/crates/ecoflow/src/secp160r1.rs"
click node_bench_ui "https://github.com/v0l/battery-control/blob/main/crates/ui/src/main.rs"
click node_ui_worker "https://github.com/v0l/battery-control/blob/main/crates/ui/src/worker.rs"
click node_demo_battery "https://github.com/v0l/battery-control/blob/main/crates/ui/src/demo.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_battery_cli,node_cli_output,node_user toneBlue
class node_discovery,node_battery_trait,node_capabilities,node_data_model,node_auth toneAmber
class node_anker_adapter,node_jk_adapter,node_jbd_adapter,node_pylon_adapter,node_victron_adapter,node_other_adapters toneMint
class node_jk_pack,node_jk_bms,node_ecoflow_packet,node_ecoflow_crypto toneRose
class node_bench_ui,node_ui_worker,node_demo_battery toneIndigo
```

## Components

### User Interfaces

- [Battery CLI](https://github.com/v0l/battery-control/blob/main/src/bin/battery/main.rs): `src/bin/battery/main.rs`
- [CLI Output](https://github.com/v0l/battery-control/blob/main/src/bin/battery/output.rs): `src/bin/battery/output.rs`

### Unified Battery API

- [Device Discovery](https://github.com/v0l/battery-control/blob/main/src/discovery.rs): `src/discovery.rs`
- [Battery Trait](https://github.com/v0l/battery-control/blob/main/src/battery.rs): `src/battery.rs`
- [Capabilities](https://github.com/v0l/battery-control/blob/main/src/capabilities.rs): `src/capabilities.rs`
- [Status and Commands](https://github.com/v0l/battery-control/blob/main/src/types.rs): `src/types.rs`
- [Pairing State](https://github.com/v0l/battery-control/blob/main/src/auth.rs): `src/auth.rs`

### Backend Adapters

- [Anker Adapter](https://github.com/v0l/battery-control/blob/main/src/backends/anker.rs): `src/backends/anker.rs`
- [JK Adapter](https://github.com/v0l/battery-control/blob/main/src/backends/jk.rs): `src/backends/jk.rs`
- [JBD Adapter](https://github.com/v0l/battery-control/blob/main/src/backends/jbd.rs): `src/backends/jbd.rs`
- [Pylontech CAN](https://github.com/v0l/battery-control/blob/main/src/backends/pylontech.rs): `src/backends/pylontech.rs`
- [Victron Adapter](https://github.com/v0l/battery-control/blob/main/src/backends/victron.rs): `src/backends/victron.rs`
- [Other Adapters](https://github.com/v0l/battery-control/tree/main/src/backends): `src/backends`

### Device Protocols

- [JK Pack Model](https://github.com/v0l/battery-control/blob/main/crates/jk_bms/src/pack.rs): `crates/jk_bms/src/pack.rs`
- [JK BMS Logic](https://github.com/v0l/battery-control/blob/main/crates/jk_bms/src/bms.rs): `crates/jk_bms/src/bms.rs`
- [EcoFlow Packets](https://github.com/v0l/battery-control/blob/main/crates/ecoflow/src/packet.rs): `crates/ecoflow/src/packet.rs`
- [EcoFlow Curve Crypto](https://github.com/v0l/battery-control/blob/main/crates/ecoflow/src/secp160r1.rs): `crates/ecoflow/src/secp160r1.rs`

### Bench UI

- [Bench Window](https://github.com/v0l/battery-control/blob/main/crates/ui/src/main.rs): `crates/ui/src/main.rs`
- [Device Worker](https://github.com/v0l/battery-control/blob/main/crates/ui/src/worker.rs): `crates/ui/src/worker.rs`
- [Demo Battery](https://github.com/v0l/battery-control/blob/main/crates/ui/src/demo.rs): `crates/ui/src/demo.rs`

### Other components

- **User**

## Connections

- User → Battery CLI: runs commands (evidence: `README.md`)
- Battery CLI → Device Discovery: discovers devices (evidence: `src/bin/battery/main.rs`)
- Battery CLI → Battery Trait: reads or controls (evidence: `src/bin/battery/main.rs`)
- Battery CLI → CLI Output: formats results (evidence: `src/bin/battery/main.rs`)
- Battery Trait → Status and Commands: uses normalized types (evidence: `src/lib.rs`)
- Battery Trait → Capabilities: gates controls (evidence: `src/lib.rs`)
- Anker Adapter → Battery Trait: implements (evidence: `src/backends/anker.rs`)
- Anker Adapter → Status and Commands: maps telemetry (evidence: `src/backends/anker.rs`)
- Anker Adapter → Pairing State: handles pairing (evidence: `src/backends/anker.rs`)
- JK Adapter → Battery Trait: implements (evidence: `src/backends/jk.rs`)
- JK Adapter → Status and Commands: maps device state (evidence: `src/backends/jk.rs`)
- JBD Adapter → Battery Trait: implements (evidence: `src/backends/jbd.rs`)
- JBD Adapter → Status and Commands: maps device state (evidence: `src/backends/jbd.rs`)
- Pylontech CAN → Battery Trait: implements (evidence: `README.md`)
- Pylontech CAN → Status and Commands: normalizes readings (evidence: `README.md`)
- Victron Adapter → Battery Trait: implements (evidence: `README.md`)
- Other Adapters → Battery Trait: adapt device families (evidence: `README.md`)
- JK Pack Model → JK BMS Logic: models pack for (evidence: `crates/jk_bms/src/module.rs`)
- EcoFlow Packets → EcoFlow Curve Crypto: supports session protocol
- User → Bench Window: uses bench window (evidence: `README.md`)
- Bench Window → Device Worker: dispatches commands (evidence: `crates/ui/src/main.rs`)
- Device Worker → Device Discovery: scans devices (evidence: `crates/ui/src/worker.rs`)
- Device Worker → Battery Trait: reads and controls (evidence: `crates/ui/src/worker.rs`)
- Device Worker → Demo Battery: uses demo mode (evidence: `crates/ui/src/worker.rs`)
