Added KS BMS support #151

This commit is contained in:
Sleeper85 committed 2026-11-08 23:08:33 +01:00
1 parent b7bb2e93ea
commit 0f7bf94111
6 files changed
+649

No files matched your search

+1
View File
@@ -15,6 +15,7 @@
* `BASEN` BMS (RS485)
* `DEYE` BMS (CAN)
* `Ecoworthy` BMS (RS485)
* `KS` BMS (BLE)
**Note: other BMS brands already integrated with ESPhome can be added easily.**
@@ -0,0 +1,45 @@
# Updated : 2026.08.26
# Version : 1.1.0
# GitHub : https://github.com/Sleeper85/esphome-yambms
# YamBMS ( Yet another multi-BMS Merging Solution )
# This YAML is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation, either version 3
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
############################ Local Packages Example ############################
# This is not a working YAML but just code ready to copy into
# your main YAML below the `packages:` section.
################################################################################
packages:
bms1: !include
file: packages/bms/bms_combine_KS_BLE_standard.yaml
vars:
bms_id: '1' # must be a number
bms_name: 'KS-BMS 1'
bms_ble_mac_address: 'C8:47:8C:10:7E:AA' # Your MAC address
bms_ks_device_type: '1' # 1 = KS48100 / KS48300-Ho23, 2 = KS48200-Ho21_V2
bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable
bms2: !include
file: packages/bms/bms_combine_KS_BLE_standard.yaml
vars:
bms_id: '2' # must be a number
bms_name: 'KS-BMS 2'
bms_ble_mac_address: 'C8:47:8C:EE:16:EA' # Your MAC address
bms_ks_device_type: '1' # 1 = KS48100 / KS48300-Ho23, 2 = KS48200-Ho21_V2
bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable
@@ -0,0 +1,49 @@
# Updated : 2026.08.26
# Version : 1.1.0
# GitHub : https://github.com/Sleeper85/esphome-yambms
# YamBMS ( Yet another multi-BMS Merging Solution )
# This YAML is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation, either version 3
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
############################ Remote Packages Example ###########################
# This is not a working YAML but just code ready to copy into
# your main YAML below the `packages:` section.
# packages:
# remote_packages:
# url: https://github.com/Sleeper85/esphome-yambms
# ref: main
# refresh: 60s
# files:
################################################################################
# BMS 1
- path: 'packages/bms/bms_combine_KS_BLE_standard.yaml'
vars:
bms_id: '1' # must be a number
bms_name: 'KS-BMS 1'
bms_ble_mac_address: 'C8:47:8C:10:7E:AA' # Your MAC address
bms_ks_device_type: '1' # 1 = KS48100 / KS48300-Ho23, 2 = KS48200-Ho21_V2
bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable
# BMS 2
- path: 'packages/bms/bms_combine_KS_BLE_standard.yaml'
vars:
bms_id: '2' # must be a number
bms_name: 'KS-BMS 2'
bms_ble_mac_address: 'C8:47:8C:EE:16:EA' # Your MAC address
bms_ks_device_type: '1' # 1 = KS48100 / KS48300-Ho23, 2 = KS48200-Ho21_V2
bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable
@@ -0,0 +1,26 @@
# Updated : 2026.08.26
# Version : 1.1.0
# GitHub : https://github.com/syssi/esphome-ks-bms
# YamBMS ( Yet another multi-BMS Merging Solution )
# This YAML is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation, either version 3
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
packages:
bms_sensors: !include bms_sensors_KS_BLE_standard.yaml
bms_combine: !include
file: bms_combine.yaml
vars:
bms_model: "KS"
bms_protocol: "BLE"
+102
View File
@@ -0,0 +1,102 @@
# Updated : 2026.08.26
# Version : 1.1.0
# GitHub : https://github.com/syssi/esphome-ks-bms
# YamBMS ( Yet another multi-BMS Merging Solution )
# This YAML is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation, either version 3
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
# +--------------------------------------+
# | KS BLE Errors Bitmask (16bit) |
# +--------------------------------------+
# Bit 0 Over current protection 0000 0000 0000 0001 0x0001
# Bit 1 Under current protection 0000 0000 0000 0010 0x0002
# Bit 2 Over voltage protection 0000 0000 0000 0100 0x0004
# Bit 3 Under voltage protection 0000 0000 0000 1000 0x0008
# Bit 4 Over temperature charge protection 0000 0000 0001 0000 0x0010
# Bit 5 Under temperature charge protection 0000 0000 0010 0000 0x0020
# Bit 6 Over temperature discharge protection 0000 0000 0100 0000 0x0040
# Bit 7 Under temperature discharge protection 0000 0000 1000 0000 0x0080
# Bit 8 Over current charge protection 0000 0001 0000 0000 0x0100
# Bit 9 Over current discharge protection 0000 0010 0000 0000 0x0200
# Bit 10 Short circuit protection 0000 0100 0000 0000 0x0400
# Bit 11 Analog front-end error 0000 1000 0000 0000 0x0800
# Bit 12 Soft lock MOS 0001 0000 0000 0000 0x1000
# Bit 13 Charge MOSFET error 0010 0000 0000 0000 0x2000
# Bit 14 Discharge MOSFET error 0100 0000 0000 0000 0x4000
# Bit 15 Reserved 1000 0000 0000 0000 0x8000
# +--------------------------------------+
# | YamBMS Errors Bitmask (16bit) |
# +--------------------------------------+
# Bit 0 General alarm 0000 0000 0000 0001 0x0001
# Bit 1 Battery high voltage alarm 0000 0000 0000 0010 0x0002
# Bit 2 Battery low voltage alarm 0000 0000 0000 0100 0x0004
# Bit 3 Battery high temperature alarm 0000 0000 0000 1000 0x0008
# Bit 4 Battery low temperature alarm 0000 0000 0001 0000 0x0010
# Bit 5 Battery high temperature charge alarm 0000 0000 0010 0000 0x0020
# Bit 6 Battery low temperature charge alarm 0000 0000 0100 0000 0x0040
# Bit 7 Battery high discharge current alarm 0000 0000 1000 0000 0x0080
# Bit 8 Battery high charge current alarm 0000 0001 0000 0000 0x0100
# Bit 9 Contactor alarm 0000 0010 0000 0000 0x0200
# Bit 10 Short circuit alarm 0000 0100 0000 0000 0x0400
# Bit 11 BMS internal alarm 0000 1000 0000 0000 0x0800
# Bit 12 Cell imbalance alarm 0001 0000 0000 0000 0x1000
# Bit 13 Reserved 0010 0000 0000 0000 0x2000
# Bit 14 Reserved 0100 0000 0000 0000 0x4000
# Bit 15 Reserved 1000 0000 0000 0000 0x8000
# KS bits 0 and 1 are the generic over/under current protections, they carry no
# charge/discharge direction, so they are reported as a general alarm. The
# directional overcurrents are bits 8 and 9.
sensor:
- platform: template
id: bms${bms_id}_yambms_errors_bitmask
device_id: bms_${bms_id}
name: "YamBMS Errors Bitmask"
update_interval: ${bms_update_interval}
accuracy_decimals: 0
icon: mdi:alert-circle-outline
filters:
- or:
- throttle: 10s
- delta: 1
lambda: |-
uint16_t bms_errors_bitmask = id(bms${bms_id}_errors_bitmask).state;
uint16_t yambms_errors_bitmask = 0;
if (bms_errors_bitmask > 0)
{
if (bms_errors_bitmask & 0x0001) yambms_errors_bitmask |= 0x0001;
if (bms_errors_bitmask & 0x0002) yambms_errors_bitmask |= 0x0001;
if (bms_errors_bitmask & 0x0004) yambms_errors_bitmask |= 0x0002;
if (bms_errors_bitmask & 0x0008) yambms_errors_bitmask |= 0x0004;
if (bms_errors_bitmask & 0x0010) yambms_errors_bitmask |= 0x0020;
if (bms_errors_bitmask & 0x0020) yambms_errors_bitmask |= 0x0040;
if (bms_errors_bitmask & 0x0040) yambms_errors_bitmask |= 0x0008;
if (bms_errors_bitmask & 0x0080) yambms_errors_bitmask |= 0x0010;
if (bms_errors_bitmask & 0x0100) yambms_errors_bitmask |= 0x0100;
if (bms_errors_bitmask & 0x0200) yambms_errors_bitmask |= 0x0080;
if (bms_errors_bitmask & 0x0400) yambms_errors_bitmask |= 0x0400;
if (bms_errors_bitmask & 0x0800) yambms_errors_bitmask |= 0x0800;
if (bms_errors_bitmask & 0x1000) yambms_errors_bitmask |= 0x0800;
if (bms_errors_bitmask & 0x2000) yambms_errors_bitmask |= 0x0200;
if (bms_errors_bitmask & 0x4000) yambms_errors_bitmask |= 0x0200;
if (bms_errors_bitmask & 0x8000) yambms_errors_bitmask |= 0x0000;
}
return yambms_errors_bitmask;
@@ -0,0 +1,426 @@
# Updated : 2026.08.26
# Version : 1.1.0
# GitHub : https://github.com/syssi/esphome-ks-bms
# YamBMS ( Yet another multi-BMS Merging Solution )
# This YAML is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation, either version 3
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
packages:
bms_base: !include bms_base.yaml
bms_temperature_sensor: !include bms_temperature_sensor_4.yaml
bms_errors_bitmask: !include bms_errors_bitmask_KS_BLE.yaml
substitutions:
# KS BMS device type : selects the status command the component polls with,
# 0x01 for type 1 and 0x61 for type 2. Everything else (UUIDs, frame decoding,
# scaling) is identical.
# 1 = default, KS48100 and KS48300-Ho23
# 2 = KS48200-Ho21_V2
# Wrong value : the settings and identification frames still answer, so the
# numbers and text sensors fill in, but every status sensor stays empty and
# 'Can be combined' never turns on.
bms_ks_device_type: '1'
ota:
on_begin:
then:
- switch.turn_off: bms${bms_id}_enable_bluetooth_connection
- logger.log: "BLE shutdown for flashing"
# +--------------------------------------+
# | Component settings |
# +--------------------------------------+
external_components:
- source: github://syssi/esphome-ks-bms@main
refresh: 0s
esp32_ble_tracker:
scan_parameters:
active: false
ble_client:
- id: ble_client${bms_id}
mac_address: ${bms_ble_mac_address}
ks_bms_ble:
- id: ks_bms_ble${bms_id}
ble_client_id: ble_client${bms_id}
device_type: ${bms_ks_device_type}
update_interval: ${bms_update_interval}
# +--------------------------------------+
# | Component entities |
# +--------------------------------------+
binary_sensor:
- platform: ks_bms_ble
ks_bms_ble_id: ks_bms_ble${bms_id}
charging:
id: bms${bms_id}_charging_allowed
device_id: bms_${bms_id}
name: "charging"
discharging:
id: bms${bms_id}_discharging_allowed
device_id: bms_${bms_id}
name: "discharging"
limiting_current:
device_id: bms_${bms_id}
name: "limiting current"
online_status:
id: bms${bms_id}_online_status
device_id: bms_${bms_id}
name: "online status"
trigger_on_initial_state: true
on_state:
then:
- lambda: |-
// Pass the current state to the update function
id(global_update_fault)(${CAT_BMS}, ${bms_id}, !x);
# Required sensors cannot be retrieved from BMS
# equalizing : the KS BMS only reports which cells are being balanced
# Internal : only specifying an id without a name will implicitly set this to true.
- platform: template
id: bms${bms_id}_bms_equalizing
device_id: bms_${bms_id}
lambda: return (id(bms${bms_id}_balanced_cell_bitmask).state > 0);
switch:
- platform: ks_bms_ble
ks_bms_ble_id: ks_bms_ble${bms_id}
charging:
id: bms${bms_id}_charge_switch
device_id: bms_${bms_id}
name: "Charge switch"
discharging:
id: bms${bms_id}_discharge_switch
device_id: bms_${bms_id}
name: "Discharge switch"
# +--------------------------------------+
- platform: ble_client
ble_client_id: ble_client${bms_id}
id: bms${bms_id}_enable_bluetooth_connection
device_id: bms_${bms_id}
name: "Enable Bluetooth connection"
# +--------------------------------------+
sensor:
- platform: ks_bms_ble
ks_bms_ble_id: ks_bms_ble${bms_id}
min_cell_voltage:
id: bms${bms_id}_min_cell_voltage
device_id: bms_${bms_id}
name: "min cell voltage"
max_cell_voltage:
id: bms${bms_id}_max_cell_voltage
device_id: bms_${bms_id}
name: "max cell voltage"
min_voltage_cell:
id: bms${bms_id}_min_voltage_cell
device_id: bms_${bms_id}
name: "min voltage cell"
max_voltage_cell:
id: bms${bms_id}_max_voltage_cell
device_id: bms_${bms_id}
name: "max voltage cell"
delta_cell_voltage:
id: bms${bms_id}_delta_cell_voltage
device_id: bms_${bms_id}
name: "delta cell voltage"
average_cell_voltage:
id: bms${bms_id}_average_cell_voltage
device_id: bms_${bms_id}
name: "average cell voltage"
total_voltage:
id: bms${bms_id}_total_voltage
device_id: bms_${bms_id}
name: "total voltage"
current:
id: bms${bms_id}_current
device_id: bms_${bms_id}
name: "current"
power:
id: bms${bms_id}_power
device_id: bms_${bms_id}
name: "power"
charging_power:
id: bms${bms_id}_charging_power
device_id: bms_${bms_id}
name: "charging power"
discharging_power:
id: bms${bms_id}_discharging_power
device_id: bms_${bms_id}
name: "discharging power"
mosfet_temperature:
device_id: bms_${bms_id}
name: "mosfet temperature"
ambient_temperature:
device_id: bms_${bms_id}
name: "ambient temperature"
average_temperature:
device_id: bms_${bms_id}
name: "average temperature"
temperature_1:
id: bms${bms_id}_temperature_sensor_1
device_id: bms_${bms_id}
name: "temperature sensor 1"
temperature_2:
id: bms${bms_id}_temperature_sensor_2
device_id: bms_${bms_id}
name: "temperature sensor 2"
temperature_3:
id: bms${bms_id}_temperature_sensor_3
device_id: bms_${bms_id}
name: "temperature sensor 3"
temperature_4:
id: bms${bms_id}_temperature_sensor_4
device_id: bms_${bms_id}
name: "temperature sensor 4"
state_of_charge:
id: bms${bms_id}_state_of_charge
device_id: bms_${bms_id}
# name: "state of charge"
state_of_health:
id: bms${bms_id}_battery_soh
device_id: bms_${bms_id}
name: "Battery SoH"
capacity_remaining:
id: bms${bms_id}_capacity_remaining_ah
device_id: bms_${bms_id}
# name: "capacity remaining"
full_charge_capacity:
id: bms${bms_id}_battery_capacity
device_id: bms_${bms_id}
name: "full charge capacity"
nominal_capacity:
device_id: bms_${bms_id}
name: "nominal capacity"
charging_cycles:
id: bms${bms_id}_charging_cycles_raw
device_id: bms_${bms_id}
# name: "charging cycles"
balanced_cell:
device_id: bms_${bms_id}
name: "balanced cell"
balanced_cell_bitmask:
id: bms${bms_id}_balanced_cell_bitmask
device_id: bms_${bms_id}
name: "balanced cell bitmask"
error_bitmask:
id: bms${bms_id}_errors_bitmask
device_id: bms_${bms_id}
name: "errors bitmask"
voltage_protection_bitmask:
device_id: bms_${bms_id}
name: "voltage protection bitmask"
current_protection_bitmask:
device_id: bms_${bms_id}
name: "current protection bitmask"
temperature_protection_bitmask:
device_id: bms_${bms_id}
name: "temperature protection bitmask"
cell_voltage_1:
id: bms${bms_id}_cell_v_01
device_id: bms_${bms_id}
name: "cell voltage 01"
cell_voltage_2:
id: bms${bms_id}_cell_v_02
device_id: bms_${bms_id}
name: "cell voltage 02"
cell_voltage_3:
id: bms${bms_id}_cell_v_03
device_id: bms_${bms_id}
name: "cell voltage 03"
cell_voltage_4:
id: bms${bms_id}_cell_v_04
device_id: bms_${bms_id}
name: "cell voltage 04"
cell_voltage_5:
id: bms${bms_id}_cell_v_05
device_id: bms_${bms_id}
name: "cell voltage 05"
cell_voltage_6:
id: bms${bms_id}_cell_v_06
device_id: bms_${bms_id}
name: "cell voltage 06"
cell_voltage_7:
id: bms${bms_id}_cell_v_07
device_id: bms_${bms_id}
name: "cell voltage 07"
cell_voltage_8:
id: bms${bms_id}_cell_v_08
device_id: bms_${bms_id}
name: "cell voltage 08"
cell_voltage_9:
id: bms${bms_id}_cell_v_09
device_id: bms_${bms_id}
name: "cell voltage 09"
cell_voltage_10:
id: bms${bms_id}_cell_v_10
device_id: bms_${bms_id}
name: "cell voltage 10"
cell_voltage_11:
id: bms${bms_id}_cell_v_11
device_id: bms_${bms_id}
name: "cell voltage 11"
cell_voltage_12:
id: bms${bms_id}_cell_v_12
device_id: bms_${bms_id}
name: "cell voltage 12"
cell_voltage_13:
id: bms${bms_id}_cell_v_13
device_id: bms_${bms_id}
name: "cell voltage 13"
cell_voltage_14:
id: bms${bms_id}_cell_v_14
device_id: bms_${bms_id}
name: "cell voltage 14"
cell_voltage_15:
id: bms${bms_id}_cell_v_15
device_id: bms_${bms_id}
name: "cell voltage 15"
cell_voltage_16:
id: bms${bms_id}_cell_v_16
device_id: bms_${bms_id}
name: "cell voltage 16"
# Charging cycle capacity - Calculated from charging cycles and battery capacity
- platform: template
id: bms${bms_id}_cycle_capacity_raw
device_id: bms_${bms_id}
# name: "charging cycle capacity"
update_interval: ${bms_update_interval}
unit_of_measurement: Ah
state_class: total
icon: mdi:car-battery
accuracy_decimals: 0
filters:
- or:
- throttle: 10s
- delta: 1
lambda: return id(bms${bms_id}_charging_cycles_raw).state * id(bms${bms_id}_battery_capacity).state;
number:
- platform: ks_bms_ble
ks_bms_ble_id: ks_bms_ble${bms_id}
cell_overvoltage_protection:
id: bms${bms_id}_cell_ovp
device_id: bms_${bms_id}
name: "cell voltage overvoltage protection"
cell_overvoltage_recovery:
id: bms${bms_id}_cell_ovpr
device_id: bms_${bms_id}
name: "cell voltage overvoltage recovery"
cell_undervoltage_protection:
id: bms${bms_id}_cell_uvp
device_id: bms_${bms_id}
name: "cell voltage undervoltage protection"
cell_undervoltage_recovery:
id: bms${bms_id}_cell_uvpr
device_id: bms_${bms_id}
name: "cell voltage undervoltage recovery"
balance_open_voltage:
id: bms${bms_id}_balance_starting_voltage
device_id: bms_${bms_id}
name: "balancing start voltage"
balance_open_voltage_diff:
id: bms${bms_id}_bms_balance_trigger_voltage
device_id: bms_${bms_id}
# name: "balance trigger voltage"
cell_full_voltage:
device_id: bms_${bms_id}
name: "cell full voltage"
cell_cutoff_voltage:
device_id: bms_${bms_id}
name: "cell cutoff voltage"
nominal_capacity:
device_id: bms_${bms_id}
name: "nominal capacity setting"
full_charge_capacity:
device_id: bms_${bms_id}
name: "full charge capacity setting"
# The KS BMS has no dedicated charge / discharge current limit setting,
# its overcurrent protection thresholds are what YamBMS reads as the
# maximum charge and discharge currents of the pack.
charge_overcurrent_protection:
id: bms${bms_id}_max_charge_current
device_id: bms_${bms_id}
name: "max charge current"
discharge_overcurrent_protection:
id: bms${bms_id}_max_discharge_current
device_id: bms_${bms_id}
name: "max discharge current"
charge_overtemperature_protection:
device_id: bms_${bms_id}
name: "charge overtemperature protection"
charge_overtemperature_recovery:
device_id: bms_${bms_id}
name: "charge overtemperature recovery"
charge_undertemperature_protection:
device_id: bms_${bms_id}
name: "charge undertemperature protection"
charge_undertemperature_recovery:
device_id: bms_${bms_id}
name: "charge undertemperature recovery"
discharge_overtemperature_protection:
device_id: bms_${bms_id}
name: "discharge overtemperature protection"
discharge_overtemperature_recovery:
device_id: bms_${bms_id}
name: "discharge overtemperature recovery"
discharge_undertemperature_protection:
device_id: bms_${bms_id}
name: "discharge undertemperature protection"
discharge_undertemperature_recovery:
device_id: bms_${bms_id}
name: "discharge undertemperature recovery"
text_sensor:
- platform: ks_bms_ble
ks_bms_ble_id: ks_bms_ble${bms_id}
errors:
device_id: bms_${bms_id}
name: "errors"
voltage_protection:
device_id: bms_${bms_id}
name: "voltage protection"
current_protection:
device_id: bms_${bms_id}
name: "current protection"
temperature_protection:
device_id: bms_${bms_id}
name: "temperature protection"
balancer_status:
device_id: bms_${bms_id}
name: "balancer status"
# The BLE advertised name identifies the bluetooth module, not the BMS.
# 'model type' and 'device model' are what tell you which pack you have,
# and so whether bms_ks_device_type should be 1 or 2.
device_model:
device_id: bms_${bms_id}
name: "device model"
model_type:
device_id: bms_${bms_id}
name: "model type"
serial_number:
device_id: bms_${bms_id}
name: "serial number"
software_version:
device_id: bms_${bms_id}
name: "software version"
hardware_version:
device_id: bms_${bms_id}
name: "hardware version"