# chipsi/esphome-jk-bms architecture

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

- Interactive diagram: https://gitdiagram.com/chipsi/esphome-jk-bms
- Repository: https://github.com/chipsi/esphome-jk-bms

## Overview

This ESPHome external component monitors JK-BMS devices over RS485 or BLE and exposes readings as ESPHome entities; BLE also provides configurable controls. The RS485 path parses Modbus frames and dispatches them to the BMS decoder, while the BLE implementation decodes protocol frames. The excerpts show these parsing and dispatch responsibilities, but do not expose all entity wiring or the BLE runtime call chain, so those connections are omitted or marked unverified.

Main entry points: [`components/jk_bms_ble/jk_bms_ble.cpp`](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/jk_bms_ble.cpp) (BLE client and decoder), [`components/jk_bms/jk_bms.cpp`](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/jk_bms.cpp) (RS485 BMS decoder), [`components/jk_modbus/jk_modbus.cpp`](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_modbus/jk_modbus.cpp) (Modbus frame handler), [`components/jk_bms/__init__.py`](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/__init__.py) (RS485 component setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rs485["RS485 monitoring"]
  node_modbus["Modbus frame handler<br/>[jk_modbus.cpp]"]
  node_modbus_device["Modbus device registration<br/>[__init__.py]"]
  node_rs485_config["RS485 component setup<br/>[__init__.py]"]
  node_rs485_decoder["RS485 BMS decoder<br/>[jk_bms.cpp]"]
end

subgraph group_ble["BLE monitoring"]
  node_ble_config["BLE component setup<br/>[__init__.py]"]
  node_ble_client["BLE client and decoder<br/>[jk_bms_ble.cpp]"]
end

subgraph group_entities["ESPHome entities"]
  node_rs485_entities["RS485 entity setup<br/>[sensor.py]"]
  node_rs485_binary["RS485 binary sensors<br/>[binary_sensor.py]"]
  node_rs485_text["RS485 text sensors<br/>[text_sensor.py]"]
  node_ble_sensors["BLE sensor setup<br/>[sensor.py]"]
  node_ble_binary["BLE binary sensors<br/>[binary_sensor.py]"]
  node_ble_text["BLE text sensors<br/>[text_sensor.py]"]
  node_ble_buttons["BLE buttons<br/>[jk_button.cpp]"]
  node_ble_numbers["BLE number controls<br/>[jk_number.cpp]"]
  node_ble_switches["BLE switches<br/>[jk_switch.cpp]"]
end

node_user(("ESPHome user"))
node_bms["JK-BMS"]
node_uart["UART interface"]
node_ble_device["BLE device"]

node_user -->|"configures"| node_rs485_config
node_user -->|"configures"| node_ble_config
node_bms -->|"sends frames"| node_uart
node_uart -->|"supplies bytes"| node_modbus
node_rs485_config -->|"registers device"| node_modbus_device
node_modbus -->|"dispatches data"| node_rs485_decoder
node_rs485_decoder -->|"publishes readings"| node_rs485_entities
node_rs485_decoder -.->|"publishes states"| node_rs485_binary
node_rs485_decoder -.->|"publishes text"| node_rs485_text
node_bms -->|"communicates via BLE"| node_ble_device
node_ble_device -.->|"provides frames"| node_ble_client
node_ble_config -->|"configures client"| node_ble_client
node_ble_client -.->|"publishes readings"| node_ble_sensors
node_ble_client -.->|"publishes states"| node_ble_binary
node_ble_client -.->|"publishes text"| node_ble_text
node_ble_buttons -.->|"requests actions"| node_ble_client
node_ble_numbers -.->|"writes settings"| node_ble_client
node_ble_switches -.->|"writes settings"| node_ble_client

click node_modbus "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_modbus/jk_modbus.cpp"
click node_modbus_device "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_modbus/__init__.py"
click node_rs485_config "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/__init__.py"
click node_rs485_decoder "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/jk_bms.cpp"
click node_rs485_entities "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/sensor.py"
click node_rs485_binary "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/binary_sensor.py"
click node_rs485_text "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/text_sensor.py"
click node_ble_config "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/__init__.py"
click node_ble_client "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/jk_bms_ble.cpp"
click node_ble_sensors "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/sensor.py"
click node_ble_binary "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/binary_sensor.py"
click node_ble_text "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/text_sensor.py"
click node_ble_buttons "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/button/jk_button.cpp"
click node_ble_numbers "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/number/jk_number.cpp"
click node_ble_switches "https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/switch/jk_switch.cpp"

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_modbus,node_modbus_device,node_rs485_config,node_rs485_decoder,node_user toneBlue
class node_ble_config,node_ble_client toneAmber
class node_rs485_entities,node_rs485_binary,node_rs485_text,node_ble_sensors,node_ble_binary,node_ble_text,node_ble_buttons,node_ble_numbers,node_ble_switches toneMint
class node_bms,node_uart,node_ble_device toneIndigo
```

## Components

### RS485 monitoring

- [Modbus frame handler](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_modbus/jk_modbus.cpp): `components/jk_modbus/jk_modbus.cpp`
- [Modbus device registration](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_modbus/__init__.py): `components/jk_modbus/__init__.py`
- [RS485 component setup](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/__init__.py): `components/jk_bms/__init__.py`
- [RS485 BMS decoder](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/jk_bms.cpp): `components/jk_bms/jk_bms.cpp`

### BLE monitoring

- [BLE component setup](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/__init__.py): `components/jk_bms_ble/__init__.py`
- [BLE client and decoder](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/jk_bms_ble.cpp): `components/jk_bms_ble/jk_bms_ble.cpp`

### ESPHome entities

- [RS485 entity setup](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/sensor.py): `components/jk_bms/sensor.py`
- [RS485 binary sensors](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/binary_sensor.py): `components/jk_bms/binary_sensor.py`
- [RS485 text sensors](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms/text_sensor.py): `components/jk_bms/text_sensor.py`
- [BLE sensor setup](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/sensor.py): `components/jk_bms_ble/sensor.py`
- [BLE binary sensors](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/binary_sensor.py): `components/jk_bms_ble/binary_sensor.py`
- [BLE text sensors](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/text_sensor.py): `components/jk_bms_ble/text_sensor.py`
- [BLE buttons](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/button/jk_button.cpp): `components/jk_bms_ble/button/jk_button.cpp`
- [BLE number controls](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/number/jk_number.cpp): `components/jk_bms_ble/number/jk_number.cpp`
- [BLE switches](https://github.com/chipsi/esphome-jk-bms/blob/main/components/jk_bms_ble/switch/jk_switch.cpp): `components/jk_bms_ble/switch/jk_switch.cpp`

### Other components

- **ESPHome user**
- **JK-BMS**
- **UART interface**
- **BLE device**

## Connections

- ESPHome user → RS485 component setup: configures (evidence: `README.md`)
- ESPHome user → BLE component setup: configures (evidence: `README.md`)
- JK-BMS → UART interface: sends frames (evidence: `README.md`)
- UART interface → Modbus frame handler: supplies bytes (evidence: `components/jk_modbus/jk_modbus.cpp`)
- RS485 component setup → Modbus device registration: registers device (evidence: `components/jk_bms/__init__.py`)
- Modbus frame handler → RS485 BMS decoder: dispatches data (evidence: `components/jk_modbus/jk_modbus.cpp`)
- RS485 BMS decoder → RS485 entity setup: publishes readings (evidence: `components/jk_bms/jk_bms.cpp`)
- RS485 BMS decoder → RS485 binary sensors: publishes states
- RS485 BMS decoder → RS485 text sensors: publishes text
- JK-BMS → BLE device: communicates via BLE (evidence: `README.md`)
- BLE device → BLE client and decoder: provides frames
- BLE component setup → BLE client and decoder: configures client (evidence: `components/jk_bms_ble/__init__.py`)
- BLE client and decoder → BLE sensor setup: publishes readings
- BLE client and decoder → BLE binary sensors: publishes states
- BLE client and decoder → BLE text sensors: publishes text
- BLE buttons → BLE client and decoder: requests actions
- BLE number controls → BLE client and decoder: writes settings
- BLE switches → BLE client and decoder: writes settings
