# kairui1108/cuktech-ble-ha architecture

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

- Interactive diagram: https://gitdiagram.com/kairui1108/cuktech-ble-ha
- Repository: https://github.com/kairui1108/cuktech-ble-ha

## Overview

The repository provides three ways to connect a CUKTECH charger to Home Assistant: a Python BLE gateway, an ESP32 bridge, and the Home Assistant integration that consumes gateway MQTT data. The main Python flow is charger telemetry and commands through BLE management into shared state, then HTTP/MQTT and the web interface; the ESP32 offers a standalone alternative. The README documents these product capabilities, while edges between unsampled subsystems are omitted or marked unverified rather than inferred.

Main entry points: [`ble_server/ha_server.py`](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/ha_server.py) (HTTP and MQTT server), [`ble_server/ble_manager.py`](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/ble_manager.py) (BLE manager), [`esp32_ble/main/main.c`](https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/main.c) (Firmware runtime), [`ha_integration/custom_components/cuktech_charger/__init__.py`](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/__init__.py) (Integration coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python BLE gateway"]
  node_ble_mgr["BLE manager<br/>[ble_manager.py]"]
  node_ble_ctrl["BLE controller<br/>[controller.py]"]
  node_ble_proto["BLE protocol<br/>[protocol.py]"]
  node_state["Charger state<br/>[state.py]"]
  node_energy["Energy tracking<br/>[energy.py]"]
  node_history[("SQLite history<br/>[history.py]")]
  node_server["HTTP and MQTT server<br/>[ha_server.py]"]
  node_xiaomi["Xiaomi Cloud setup<br/>[xiaomi_cloud.py]"]
  node_bemfa["Bemfa cloud client<br/>[bemfa_client.py]"]
end

subgraph group_esp["ESP32 bridge"]
  node_esp_main["Firmware runtime<br/>[main.c]"]
  node_esp_ble["BLE manager<br/>[ble_manager.c]"]
  node_esp_http["HTTP server<br/>[http_server.c]"]
  node_esp_bemfa["Bemfa client<br/>[bemfa.c]"]
end

subgraph group_ha["Home Assistant integration"]
  node_integration["Integration coordinator<br/>[__init__.py]"]
  node_ha_energy["Charge limit engine<br/>[energy_engine.py]"]
  node_ha_sensor["Sensors<br/>[sensor.py]"]
  node_ha_switch["Switch controls<br/>[switch.py]"]
end

subgraph group_web["Web management"]
  node_webui["Web UI<br/>[app.js]"]
  node_webhistory["Charge history UI<br/>[charge_history.js]"]
  node_web_limit["Charge limit UI<br/>[charge_limit.js]"]
end

node_charger(("CUKTECH charger"))
node_mqtt(("MQTT broker"))
node_ha_actor(("Home Assistant"))

node_charger -->|"BLE connects"| node_ble_mgr
node_ble_mgr -->|"uses"| node_ble_ctrl
node_ble_mgr -->|"updates"| node_state
node_ble_mgr -->|"uses"| node_energy
node_ble_mgr -->|"records"| node_history
node_ble_ctrl -->|"uses"| node_ble_proto
node_server -->|"commands"| node_ble_mgr
node_server -->|"reads"| node_state
node_server -->|"queries"| node_history
node_server -->|"uses"| node_xiaomi
node_server -->|"uses"| node_bemfa
node_server -->|"serves"| node_webui
node_webui -.->|"calls API"| node_server
node_webhistory -.->|"requests history"| node_server
node_web_limit -.->|"sets limits"| node_server
node_esp_main -->|"dispatches"| node_esp_ble
node_esp_main -->|"uses"| node_esp_http
node_esp_main -->|"uses"| node_esp_bemfa
node_esp_ble -->|"BLE connects"| node_charger
node_esp_main -->|"publishes"| node_mqtt
node_mqtt -->|"delivers data"| node_integration
node_integration -->|"feeds samples"| node_ha_energy
node_integration -.->|"updates entities"| node_ha_sensor
node_integration -.->|"updates entities"| node_ha_switch
node_ha_actor -.->|"controls"| node_ha_switch
node_ha_actor -.->|"views"| node_ha_sensor
node_server -->|"publishes"| node_mqtt

click node_ble_mgr "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/ble_manager.py"
click node_ble_ctrl "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/src/cuktech_ble/controller.py"
click node_ble_proto "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/src/cuktech_ble/protocol.py"
click node_state "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/state.py"
click node_energy "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/energy.py"
click node_history "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/history.py"
click node_server "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/ha_server.py"
click node_xiaomi "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/xiaomi_cloud.py"
click node_bemfa "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/bemfa_client.py"
click node_webui "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/web/static/app.js"
click node_webhistory "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/web/static/charge_history.js"
click node_web_limit "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/web/static/charge_limit.js"
click node_esp_main "https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/main.c"
click node_esp_ble "https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/ble_manager.c"
click node_esp_http "https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/http_server.c"
click node_esp_bemfa "https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/bemfa.c"
click node_integration "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/__init__.py"
click node_ha_energy "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/energy_engine.py"
click node_ha_sensor "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/sensor.py"
click node_ha_switch "https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/switch.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_ble_mgr,node_ble_ctrl,node_ble_proto,node_state,node_energy,node_history,node_server,node_xiaomi,node_bemfa toneBlue
class node_esp_main,node_esp_ble,node_esp_http,node_esp_bemfa toneAmber
class node_integration,node_ha_energy,node_ha_sensor,node_ha_switch toneMint
class node_webui,node_webhistory,node_web_limit toneRose
class node_charger,node_mqtt,node_ha_actor toneIndigo
```

## Components

### Python BLE gateway

- [BLE manager](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/ble_manager.py): `ble_server/ble_manager.py`
- [BLE controller](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/src/cuktech_ble/controller.py): `ble_server/src/cuktech_ble/controller.py`
- [BLE protocol](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/src/cuktech_ble/protocol.py): `ble_server/src/cuktech_ble/protocol.py`
- [Charger state](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/state.py): `ble_server/state.py`
- [Energy tracking](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/energy.py): `ble_server/energy.py`
- [SQLite history](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/history.py): `ble_server/history.py`
- [HTTP and MQTT server](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/ha_server.py): `ble_server/ha_server.py`
- [Xiaomi Cloud setup](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/xiaomi_cloud.py): `ble_server/xiaomi_cloud.py`
- [Bemfa cloud client](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/bemfa_client.py): `ble_server/bemfa_client.py`

### ESP32 bridge

- [Firmware runtime](https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/main.c): `esp32_ble/main/main.c`
- [BLE manager](https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/ble_manager.c): `esp32_ble/main/ble_manager.c`
- [HTTP server](https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/http_server.c): `esp32_ble/main/http_server.c`
- [Bemfa client](https://github.com/kairui1108/cuktech-ble-ha/blob/main/esp32_ble/main/bemfa.c): `esp32_ble/main/bemfa.c`

### Home Assistant integration

- [Integration coordinator](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/__init__.py): `ha_integration/custom_components/cuktech_charger/__init__.py`
- [Charge limit engine](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/energy_engine.py): `ha_integration/custom_components/cuktech_charger/energy_engine.py`
- [Sensors](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/sensor.py): `ha_integration/custom_components/cuktech_charger/sensor.py`
- [Switch controls](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ha_integration/custom_components/cuktech_charger/switch.py): `ha_integration/custom_components/cuktech_charger/switch.py`

### Web management

- [Web UI](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/web/static/app.js): `ble_server/web/static/app.js`
- [Charge history UI](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/web/static/charge_history.js): `ble_server/web/static/charge_history.js`
- [Charge limit UI](https://github.com/kairui1108/cuktech-ble-ha/blob/main/ble_server/web/static/charge_limit.js): `ble_server/web/static/charge_limit.js`

### Other components

- **CUKTECH charger**
- **MQTT broker**
- **Home Assistant**

## Connections

- CUKTECH charger → BLE manager: BLE connects (evidence: `README.md`)
- BLE manager → BLE controller: uses (evidence: `ble_server/ble_manager.py`)
- BLE manager → Charger state: updates (evidence: `ble_server/ble_manager.py`)
- BLE manager → Energy tracking: uses (evidence: `ble_server/ble_manager.py`)
- BLE manager → SQLite history: records (evidence: `ble_server/ble_manager.py`)
- BLE controller → BLE protocol: uses (evidence: `ble_server/src/cuktech_ble/controller.py`)
- HTTP and MQTT server → BLE manager: commands (evidence: `ble_server/ha_server.py`)
- HTTP and MQTT server → Charger state: reads (evidence: `ble_server/ha_server.py`)
- HTTP and MQTT server → SQLite history: queries (evidence: `ble_server/ha_server.py`)
- HTTP and MQTT server → Xiaomi Cloud setup: uses (evidence: `ble_server/ha_server.py`)
- HTTP and MQTT server → Bemfa cloud client: uses (evidence: `ble_server/ha_server.py`)
- HTTP and MQTT server → Web UI: serves (evidence: `README.md`)
- Web UI → HTTP and MQTT server: calls API
- Charge history UI → HTTP and MQTT server: requests history
- Charge limit UI → HTTP and MQTT server: sets limits
- Firmware runtime → BLE manager: dispatches (evidence: `esp32_ble/main/main.c`)
- Firmware runtime → HTTP server: uses (evidence: `esp32_ble/main/main.c`)
- Firmware runtime → Bemfa client: uses (evidence: `esp32_ble/main/main.c`)
- BLE manager → CUKTECH charger: BLE connects (evidence: `README.md`)
- Firmware runtime → MQTT broker: publishes (evidence: `README.md`)
- MQTT broker → Integration coordinator: delivers data (evidence: `README.md`)
- Integration coordinator → Charge limit engine: feeds samples (evidence: `ha_integration/custom_components/cuktech_charger/__init__.py`)
- Integration coordinator → Sensors: updates entities (evidence: `ha_integration/custom_components/cuktech_charger/sensor.py`)
- Integration coordinator → Switch controls: updates entities (evidence: `ha_integration/custom_components/cuktech_charger/switch.py`)
- Home Assistant → Switch controls: controls
- Home Assistant → Sensors: views
- HTTP and MQTT server → MQTT broker: publishes (evidence: `README.md`)