# fl4p/batmon-ha architecture

> Architecture diagram of the GitHub repository fl4p/batmon-ha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fl4p/batmon-ha
- Repository: https://github.com/fl4p/batmon-ha

## Overview

BatMON discovers and polls configured battery-management systems, normalizes readings, derives pack and energy metrics, then publishes them to Home Assistant over MQTT or to InfluxDB; it also exposes live state through a GUI. The README documents broad BLE and experimental serial support, battery groups, charge algorithms, and control operations. Sampled code confirms the runtime entry point, BLE handling, selected protocol decoding, proxy setup, and GUI serialization; some subsystem links are therefore shown only where documented or directly supported.

Main entry points: [`bmslib/sampling.py`](https://github.com/fl4p/batmon-ha/blob/master/bmslib/sampling.py) (Sample scheduling), [`main.py`](https://github.com/fl4p/batmon-ha/blob/master/main.py) (Runtime coordinator), [`bmslib/bt.py`](https://github.com/fl4p/batmon-ha/blob/master/bmslib/bt.py) (Bluetooth transport), [`bmslib/mqtt_util.py`](https://github.com/fl4p/batmon-ha/blob/master/bmslib/mqtt_util.py) (MQTT publishing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Device acquisition"]
  node_discovery["Bluetooth discovery<br/>[scan.py]"]
  node_bt["Bluetooth transport<br/>[bt.py]"]
  node_proxy["ESPHome proxy<br/>[bootstrap.py]"]
  node_blemodels["BLE device drivers<br/>[BLE_BMS_wrap.py]"]
  node_jk["JK protocol driver<br/>[jikong.py]"]
  node_serial["Serial transport<br/>[transport.py]"]
  node_serialmodels["Serial BMS drivers<br/>[jikong_uart.py]"]
end

subgraph group_processing["Battery processing"]
  node_sample["Sample scheduling<br/>[sampling.py]"]
  node_grouping["Battery groups<br/>[group.py]"]
  node_algorithms["Charge algorithms<br/>[algorithm.py]"]
  node_meters["Energy meters<br/>[tracker.py]"]
  node_ambient["Ambient temperature"]
end

subgraph group_delivery["State delivery"]
  node_mqtt["MQTT publishing<br/>[mqtt_util.py]"]
  node_influx["InfluxDB sink<br/>[sinks.py]"]
  node_gui["GUI server<br/>[server.py]"]
  node_wire["GUI state format<br/>[model.py]"]
end

subgraph group_operations["Control and operations"]
  node_main["Runtime coordinator<br/>[main.py]"]
end

node_operator(("Operator configures"))
node_bms(("Battery systems"))
node_ha(("Home Assistant"))
node_influxservice[("InfluxDB service")]

node_operator -->|"configures"| node_main
node_main -->|"starts discovery"| node_discovery
node_main -.->|"starts proxies"| node_proxy
node_main -->|"starts sampling"| node_sample
node_discovery -->|"scans devices"| node_bt
node_sample -->|"polls BLE"| node_blemodels
node_sample -->|"polls serial"| node_serialmodels
node_blemodels -->|"uses transport"| node_bt
node_jk -->|"uses transport"| node_bt
node_serialmodels -->|"uses transport"| node_serial
node_bms -->|"BLE data"| node_bt
node_bms -->|"serial data"| node_serial
node_sample -->|"aggregates batteries"| node_grouping
node_sample -->|"evaluates control"| node_algorithms
node_sample -->|"integrates energy"| node_meters
node_sample -->|"publishes readings"| node_mqtt
node_sample -.->|"writes readings"| node_influx
node_mqtt -->|"sends MQTT"| node_ha
node_influx -.->|"writes points"| node_influxservice
node_sample -->|"updates state"| node_gui
node_gui -->|"serializes state"| node_wire
node_ha -->|"views live state"| node_gui
node_main -->|"configures estimator"| node_ambient
node_ambient -->|"registers topics"| node_mqtt

click node_main "https://github.com/fl4p/batmon-ha/blob/master/main.py"
click node_discovery "https://github.com/fl4p/batmon-ha/blob/master/bmslib/scan.py"
click node_bt "https://github.com/fl4p/batmon-ha/blob/master/bmslib/bt.py"
click node_proxy "https://github.com/fl4p/batmon-ha/blob/master/bmslib/esphome_proxy/bootstrap.py"
click node_blemodels "https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/BLE_BMS_wrap.py"
click node_jk "https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/jikong.py"
click node_serial "https://github.com/fl4p/batmon-ha/blob/master/bmslib/wired/transport.py"
click node_serialmodels "https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/jikong_uart.py"
click node_sample "https://github.com/fl4p/batmon-ha/blob/master/bmslib/sampling.py"
click node_grouping "https://github.com/fl4p/batmon-ha/blob/master/bmslib/group.py"
click node_algorithms "https://github.com/fl4p/batmon-ha/blob/master/bmslib/algorithm.py"
click node_meters "https://github.com/fl4p/batmon-ha/blob/master/bmslib/tracker.py"
click node_mqtt "https://github.com/fl4p/batmon-ha/blob/master/bmslib/mqtt_util.py"
click node_influx "https://github.com/fl4p/batmon-ha/blob/master/bmslib/sinks.py"
click node_gui "https://github.com/fl4p/batmon-ha/blob/master/bmslib/gui/server.py"
click node_wire "https://github.com/fl4p/batmon-ha/blob/master/bmslib/wire/model.py"
click node_ambient "https://github.com/fl4p/batmon-ha/blob/master/bmslib/pack_temp_publisher.py"

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_discovery,node_bt,node_proxy,node_blemodels,node_jk,node_serial,node_serialmodels toneBlue
class node_sample,node_grouping,node_algorithms,node_meters,node_ambient,node_influxservice toneAmber
class node_mqtt,node_influx,node_gui,node_wire toneMint
class node_main toneRose
class node_operator,node_bms,node_ha toneIndigo
```

## Components

### Device acquisition

- [Bluetooth discovery](https://github.com/fl4p/batmon-ha/blob/master/bmslib/scan.py): `bmslib/scan.py`
- [Bluetooth transport](https://github.com/fl4p/batmon-ha/blob/master/bmslib/bt.py): `bmslib/bt.py`
- [ESPHome proxy](https://github.com/fl4p/batmon-ha/blob/master/bmslib/esphome_proxy/bootstrap.py): `bmslib/esphome_proxy/bootstrap.py`
- [BLE device drivers](https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/BLE_BMS_wrap.py): `bmslib/models/BLE_BMS_wrap.py`
- [JK protocol driver](https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/jikong.py): `bmslib/models/jikong.py`
- [Serial transport](https://github.com/fl4p/batmon-ha/blob/master/bmslib/wired/transport.py): `bmslib/wired/transport.py`
- [Serial BMS drivers](https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/jikong_uart.py): `bmslib/models/jikong_uart.py`

### Battery processing

- [Sample scheduling](https://github.com/fl4p/batmon-ha/blob/master/bmslib/sampling.py): `bmslib/sampling.py`
- [Battery groups](https://github.com/fl4p/batmon-ha/blob/master/bmslib/group.py): `bmslib/group.py`
- [Charge algorithms](https://github.com/fl4p/batmon-ha/blob/master/bmslib/algorithm.py): `bmslib/algorithm.py`
- [Energy meters](https://github.com/fl4p/batmon-ha/blob/master/bmslib/tracker.py): `bmslib/tracker.py`
- [Ambient temperature](https://github.com/fl4p/batmon-ha/blob/master/bmslib/pack_temp_publisher.py): `bmslib/pack_temp_publisher.py`

### State delivery

- [MQTT publishing](https://github.com/fl4p/batmon-ha/blob/master/bmslib/mqtt_util.py): `bmslib/mqtt_util.py`
- [InfluxDB sink](https://github.com/fl4p/batmon-ha/blob/master/bmslib/sinks.py): `bmslib/sinks.py`
- [GUI server](https://github.com/fl4p/batmon-ha/blob/master/bmslib/gui/server.py): `bmslib/gui/server.py`
- [GUI state format](https://github.com/fl4p/batmon-ha/blob/master/bmslib/wire/model.py): `bmslib/wire/model.py`

### Control and operations

- [Runtime coordinator](https://github.com/fl4p/batmon-ha/blob/master/main.py): `main.py`

### Other components

- **Operator configures**
- **Battery systems**
- **Home Assistant**
- **InfluxDB service**

## Connections

- Operator configures → Runtime coordinator: configures
- Runtime coordinator → Bluetooth discovery: starts discovery
- Runtime coordinator → ESPHome proxy: starts proxies
- Runtime coordinator → Sample scheduling: starts sampling
- Bluetooth discovery → Bluetooth transport: scans devices
- Sample scheduling → BLE device drivers: polls BLE
- Sample scheduling → Serial BMS drivers: polls serial
- BLE device drivers → Bluetooth transport: uses transport
- JK protocol driver → Bluetooth transport: uses transport
- Serial BMS drivers → Serial transport: uses transport
- Battery systems → Bluetooth transport: BLE data
- Battery systems → Serial transport: serial data
- Sample scheduling → Battery groups: aggregates batteries
- Sample scheduling → Charge algorithms: evaluates control
- Sample scheduling → Energy meters: integrates energy
- Sample scheduling → MQTT publishing: publishes readings
- Sample scheduling → InfluxDB sink: writes readings
- MQTT publishing → Home Assistant: sends MQTT
- InfluxDB sink → InfluxDB service: writes points
- Sample scheduling → GUI server: updates state
- GUI server → GUI state format: serializes state
- Home Assistant → GUI server: views live state
- Runtime coordinator → Ambient temperature: configures estimator
- Ambient temperature → MQTT publishing: registers topics