Improved Cut-Off charging logic equation and documentation (PR #143)

This commit is contained in:
Sleeper85 committed 2025-12-29 15:36:57 +01:00
1 parent f3e77c327f
commit 0caee3801c
10 files changed
+51 -29

No files matched your search

+11 -3
View File
@@ -19,11 +19,13 @@ The charging voltage and current correspond to the default values in the YAML sc
Source: [Charging Marine Lithium Battery Banks](https://nordkyndesign.com/charging-marine-lithium-battery-banks)
Special thanks to [@shvmm](https://github.com/shvmm) for creating the equations.
Special thanks to [@shvmm](https://github.com/shvmm) for deriving the equations.
Note: The equations below are valid for other chemistries like Li-ion and LTO but with other CVmin and CVmax values.
Note: The equations below can be adopted for other chemistries like Li-ion and LTO with specific CVmin and CVmax values.
![Image](../../images/YamBMS_Cut-Off_Charging_Logic_for_LFP_Equation.png "JK-BMS-CAN Cut-Off Charging Logic_for LFP Equation")
<img src="../..//images/YamBMS_Cut-Off_Charging_Logic_Equation.png" width="500">
<img src="../..//images/YamBMS_Cut-Off_Charging_Logic_Plot.png" width="500">
## Cut-Off Charging Logic Diagram (what's happening in the yellow diamond)
@@ -37,6 +39,8 @@ Note: The diagram below is valid for other chemistries like Li-ion and LTO but w
- CV min : 3.37 V
- CV max : 3.65 V
To enter the **Cut-Off phase** the only condition is that **cutoff_voltage > cv_min**.
![Image](../../images/YamBMS_LFP_Cut-Off_Values.png "LFP Cut-Off Values")
## Li-ion Cut-Off Values
@@ -45,6 +49,8 @@ Note: The diagram below is valid for other chemistries like Li-ion and LTO but w
- CV min : 3.90 V
- CV max : 4.20 V
To enter the **Cut-Off phase** the only condition is that **cutoff_voltage > cv_min**.
![Image](../../images/YamBMS_Li-ion_Cut-Off_Values.png "Li-ion Cut-Off Values")
## LTO Cut-Off Values
@@ -53,4 +59,6 @@ Note: The diagram below is valid for other chemistries like Li-ion and LTO but w
- CV min : 2.55 V
- CV max : 2.85 V
To enter the **Cut-Off phase** the only condition is that **cutoff_voltage > cv_min**.
![Image](../../images/YamBMS_LTO_Cut-Off_Values.png "LTO Cut-Off Value")
Binary file not shown.

Before

Width:  |  Height:  |  Size: 190 KiB

After

Width:  |  Height:  |  Size: 177 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 175 KiB

After

Width:  |  Height:  |  Size: 207 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 92 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 35 KiB

+40 -26
View File
@@ -1,4 +1,4 @@
# Updated : 2025.12.17
# Updated : 2025.12.26
# Version : 1.6.0
# GitHub : https://github.com/Sleeper85/esphome-yambms
@@ -32,7 +32,7 @@ esphome:
{
// LFP
id(${yambms_id}_cell_nominal_v) = 3.20;
id(${yambms_id}_cell_min_charge_v) = 3.375; // Fully charged at rest
id(${yambms_id}_cell_min_charge_v) = 3.37; // Fully charged at rest
id(${yambms_id}_cell_max_charge_v) = 3.65;
id(${yambms_id}_cell_max_discharge_v) = 3.00; // Not used
}
@@ -573,19 +573,16 @@ text_sensor:
// Variables
float cell_bulk_v = (id(${yambms_id}_bulk_voltage).state / id(${yambms_id}_cell_count).state);
float cell_rebulk_v = (id(${yambms_id}_rebulk_voltage).state / id(${yambms_id}_cell_count).state);
float cutoff_offset_v = 0.005;
float max_cell_v = id(${yambms_id}_max_cell_voltage).state;
// +-----------------------------------------------+
// | Force Bulk Logic |
// +-----------------------------------------------+
if (id(${yambms_id}_switch_force_bulk).state)
{
// Stop Force Bulk when the BMS starts to equalize the cells
if (id(${yambms_id}_equalizing).state)
{
id(${yambms_id}_charge_status) = "Balancing";
// Stop Force Bulk when entering the Cut-Off phase
if (id(${yambms_id}_charge_status) == "Cut-Off")
id(${yambms_id}_switch_force_bulk).turn_off();
}
// Force Bulk
else id(${yambms_id}_charge_status) = "Force Bulk";
}
@@ -594,7 +591,7 @@ text_sensor:
// | Rebulk Logic |
// +-----------------------------------------------+
// Max Cell V. <= 3.3V (default value)
else if (id(${yambms_id}_max_cell_voltage).state <= cell_rebulk_v) id(${yambms_id}_charge_status) = "Bulk";
else if (max_cell_v <= cell_rebulk_v) id(${yambms_id}_charge_status) = "Bulk";
// SoC <= 85% (default value)
else if (id(${yambms_id}_battery_soc).state <= id(${yambms_id}_rebulk_soc).state) id(${yambms_id}_charge_status) = "Bulk";
// Force Charge requested
@@ -605,21 +602,31 @@ text_sensor:
// +-----------------------------------------------+
if ((id(${yambms_id}_charge_status) != "EOC") && (id(${yambms_id}_charge_status) != "Float"))
{
float cv_min = id(${yambms_id}_cell_min_charge_v);
float cv_max = id(${yambms_id}_cell_max_charge_v);
float current = id(${yambms_id}_current).state;
float cutoff_resistance = ((cv_max - cv_min) / id(${yambms_id}_battery_capacity).state / 0.05);
static int cutoff_counter = 0;
// +-----------------------------------------------+
// | Cut-Off Charging Logic |
// +-----------------------------------------------+
if (id(${yambms_id}_current).state >= 0)
if (current >= 0)
{
float cv_min = id(${yambms_id}_cell_min_charge_v);
float cv_max = id(${yambms_id}_cell_max_charge_v);
float cutoff_current = (id(${yambms_id}_battery_capacity).state * 0.05 * (cell_bulk_v - cv_min) / (cv_max - cv_min));
float cutoff_voltage = (cv_min + (cv_max - cv_min)/(0.05 + cutoff_offset_v) * (id(${yambms_id}_current).state / id(${yambms_id}_battery_capacity).state));
float cutoff_voltage = (max_cell_v - cutoff_resistance * current);
// Stop Charging
if ((id(${yambms_id}_current).state <= cutoff_current) & (id(${yambms_id}_max_cell_voltage).state >= cutoff_voltage))
if(cutoff_voltage > cv_min)
cutoff_counter++;
else
cutoff_counter = 0;
// Entering the Cut-Off phase
// The criteria check must succeed 5 times in a row to ensure
// that these are not random/erroneous/false readings of the BMS
if (cutoff_counter > 4)
{
ESP_LOGI("yambms", "Cut-Off Current : %f", cutoff_current);
ESP_LOGI("yambms", "Cut-Off Voltage : %f", cutoff_voltage);
ESP_LOGI("yambms", "Entering the Cut-Off phase...");
// Cut-Off : the end of charging is near
id(${yambms_id}_charge_status) = "Cut-Off";
@@ -627,21 +634,25 @@ text_sensor:
// If the EOC Timer switch is enabled
if (id(${yambms_id}_switch_eoc_timer).state)
{
// Start EOC timer : the charging process ends at the latest at the end of this timer (30min by default)
if (!id(${yambms_id}_script_eoc_timer).is_running()) id(${yambms_id}_script_eoc_timer).execute();
// Start EOC timer
// The charging process ends at the latest at the end of this timer (30min by default)
if (!id(${yambms_id}_script_eoc_timer).is_running())
id(${yambms_id}_script_eoc_timer).execute();
}
// End Of Charge
// Equalizing
if (id(${yambms_id}_equalizing).state)
{
// Stop cut-off timer
if (id(${yambms_id}_script_cutoff_timer).is_running()) id(${yambms_id}_script_cutoff_timer).stop();
if (id(${yambms_id}_script_cutoff_timer).is_running())
id(${yambms_id}_script_cutoff_timer).stop();
}
// Not Equalizing
// Start cut-off timer : if the conditions continue to be respected the charging process will stop in 60s (default value)
else if (!id(${yambms_id}_script_cutoff_timer).is_running()) id(${yambms_id}_script_cutoff_timer).execute();
// Not Equalizing => Start cut-off timer
// If the conditions continue to be respected the charging process will stop in 60s (default value)
else if (!id(${yambms_id}_script_cutoff_timer).is_running())
id(${yambms_id}_script_cutoff_timer).execute();
}
// Start Charging
// Continue charging
else
{
// Stop timer
@@ -654,8 +665,11 @@ text_sensor:
}
}
// Discharging (!= "EOC" | != "Float")
else if (id(${yambms_id}_max_cell_voltage).state < (cell_bulk_v - cutoff_offset_v))
// Condition for not exiting the Cut-Off phase too quickly if the discharge current is minimal
else if (max_cell_v < (cell_bulk_v - cutoff_resistance))
{
// Reset cut-off counter
cutoff_counter = 0;
// Stop timer
if (id(${yambms_id}_script_eoc_timer).is_running()) id(${yambms_id}_script_eoc_timer).stop();
if (id(${yambms_id}_script_cutoff_timer).is_running()) id(${yambms_id}_script_cutoff_timer).stop();