# patman15/bms_ble-ha architecture

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

- Interactive diagram: https://gitdiagram.com/patman15/bms_ble-ha
- Repository: https://github.com/patman15/bms_ble-ha

## Overview

BMS_BLE is a Home Assistant integration that discovers compatible BLE battery systems, initializes a device-specific aiobmsble implementation, periodically collects battery data, and exposes it as Home Assistant entities. The main user workflow is automatic Bluetooth discovery and configuration, followed by live readings through sensor and binary-sensor platforms; diagnostics provide a separate troubleshooting view. The coordinator is the central runtime layer between the BMS device and entity platforms. Edges reflect shown calls or documented capabilities; the aiobmsble library internals and unsampled platform wiring are not represented.

Main entry points: [`custom_components/bms_ble/__init__.py`](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/__init__.py) (Entry setup), [`custom_components/bms_ble/coordinator.py`](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/coordinator.py) (BMS coordinator), [`custom_components/bms_ble/config_flow.py`](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/config_flow.py) (Device configuration), [`custom_components/bms_ble/sensor.py`](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/sensor.py) (Battery sensors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Discovery and setup"]
  node_config["Device configuration<br/>[config_flow.py]"]
  node_integration["Entry setup<br/>[__init__.py]"]
  node_constants["Integration constants<br/>[const.py]"]
end

subgraph group_runtime["BLE data runtime"]
  node_ble{{"BLE battery BMS"}}
  node_coordinator["BMS coordinator<br/>[coordinator.py]"]
  node_aiobmsble["aiobmsble device driver"]
  node_ha_bluetooth["Home Assistant Bluetooth"]
end

subgraph group_entities["Home Assistant entities"]
  node_sensors["Battery sensors<br/>[sensor.py]"]
  node_binary["Status sensors<br/>[binary_sensor.py]"]
  node_ha_entities["Home Assistant entities"]
end

subgraph group_support["Diagnostics and metadata"]
  node_diagnostics["Diagnostic snapshot<br/>[diagnostics.py]"]
end

node_user(("Home Assistant user"))

node_user -->|"configures device"| node_config
node_config -->|"scans advertisements"| node_ha_bluetooth
node_config -->|"identifies compatible BMS"| node_ble
node_integration -->|"resolves device"| node_ha_bluetooth
node_integration -->|"loads device driver"| node_aiobmsble
node_integration -->|"creates and refreshes"| node_coordinator
node_coordinator -->|"requests device updates"| node_aiobmsble
node_aiobmsble -.->|"communicates over BLE"| node_ble
node_integration -->|"forwards platform setup"| node_sensors
node_integration -->|"forwards platform setup"| node_binary
node_sensors -->|"reads battery data"| node_coordinator
node_binary -->|"reads status data"| node_coordinator
node_sensors -.->|"exposes readings"| node_ha_entities
node_binary -.->|"exposes statuses"| node_ha_entities
node_diagnostics -->|"reads runtime state"| node_coordinator
node_diagnostics -->|"reads adapter details"| node_ha_bluetooth
node_constants -->|"supplies configuration"| node_integration

click node_config "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/config_flow.py"
click node_integration "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/__init__.py"
click node_constants "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/const.py"
click node_coordinator "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/coordinator.py"
click node_sensors "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/sensor.py"
click node_binary "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/binary_sensor.py"
click node_diagnostics "https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/diagnostics.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_config,node_integration,node_constants,node_user toneBlue
class node_ble,node_coordinator,node_aiobmsble,node_ha_bluetooth toneAmber
class node_sensors,node_binary,node_ha_entities toneMint
class node_diagnostics toneRose
```

## Components

### Discovery and setup

- [Device configuration](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/config_flow.py): `custom_components/bms_ble/config_flow.py`
- [Entry setup](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/__init__.py): `custom_components/bms_ble/__init__.py`
- [Integration constants](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/const.py): `custom_components/bms_ble/const.py`

### BLE data runtime

- **BLE battery BMS**
- [BMS coordinator](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/coordinator.py): `custom_components/bms_ble/coordinator.py`
- **aiobmsble device driver**
- **Home Assistant Bluetooth**

### Home Assistant entities

- [Battery sensors](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/sensor.py): `custom_components/bms_ble/sensor.py`
- [Status sensors](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/binary_sensor.py): `custom_components/bms_ble/binary_sensor.py`
- **Home Assistant entities**

### Diagnostics and metadata

- [Diagnostic snapshot](https://github.com/patman15/bms_ble-ha/blob/main/custom_components/bms_ble/diagnostics.py): `custom_components/bms_ble/diagnostics.py`

### Other components

- **Home Assistant user**

## Connections

- Home Assistant user → Device configuration: configures device (evidence: `README.md`)
- Device configuration → Home Assistant Bluetooth: scans advertisements (evidence: `custom_components/bms_ble/config_flow.py`)
- Device configuration → BLE battery BMS: identifies compatible BMS (evidence: `custom_components/bms_ble/config_flow.py`)
- Entry setup → Home Assistant Bluetooth: resolves device (evidence: `custom_components/bms_ble/__init__.py`)
- Entry setup → aiobmsble device driver: loads device driver (evidence: `custom_components/bms_ble/__init__.py`)
- Entry setup → BMS coordinator: creates and refreshes (evidence: `custom_components/bms_ble/__init__.py`)
- BMS coordinator → aiobmsble device driver: requests device updates (evidence: `custom_components/bms_ble/coordinator.py`)
- aiobmsble device driver → BLE battery BMS: communicates over BLE
- Entry setup → Battery sensors: forwards platform setup (evidence: `custom_components/bms_ble/__init__.py`)
- Entry setup → Status sensors: forwards platform setup (evidence: `custom_components/bms_ble/__init__.py`)
- Battery sensors → BMS coordinator: reads battery data (evidence: `custom_components/bms_ble/sensor.py`)
- Status sensors → BMS coordinator: reads status data (evidence: `custom_components/bms_ble/binary_sensor.py`)
- Battery sensors → Home Assistant entities: exposes readings
- Status sensors → Home Assistant entities: exposes statuses
- Diagnostic snapshot → BMS coordinator: reads runtime state (evidence: `custom_components/bms_ble/diagnostics.py`)
- Diagnostic snapshot → Home Assistant Bluetooth: reads adapter details (evidence: `custom_components/bms_ble/diagnostics.py`)
- Integration constants → Entry setup: supplies configuration (evidence: `custom_components/bms_ble/__init__.py`)