diff --git a/YamBMS_RP_BMS_EG4_RS485.yaml b/YamBMS_RP_BMS_EG4_RS485.yaml index be1e8a2..c64b567 100644 --- a/YamBMS_RP_BMS_EG4_RS485.yaml +++ b/YamBMS_RP_BMS_EG4_RS485.yaml @@ -1,4 +1,4 @@ -# Updated : 2026.08.11 +# Updated : 2026.08.29 # Version : 1.8.0 # GitHub : https://github.com/Sleeper85/esphome-yambms @@ -286,6 +286,7 @@ packages: bms_name: 'EG4-BMS 1' ## BMS address must start at 2 with EG4 LLV2, ID 1 is a special case and has different output. bms_address: 2 # BMS 1 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours 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_EG4_LLV2_RS485_bms_full.yaml' @@ -293,6 +294,7 @@ packages: bms_id: '2' # must be a number bms_name: 'EG4-BMS 2' bms_address: 3 # BMS 2 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable # BMS 3 - path: 'packages/bms/bms_combine_EG4_LLV2_RS485_bms_full.yaml' @@ -300,6 +302,7 @@ packages: bms_id: '3' # must be a number bms_name: 'EG4-BMS 3' bms_address: 4 # BMS 3 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable diff --git a/documents/README/Charging_logic.md b/documents/README/Charging_logic.md index a9e18f4..0ba6027 100644 --- a/documents/README/Charging_logic.md +++ b/documents/README/Charging_logic.md @@ -71,12 +71,22 @@ The Bulk or Cut-Off **conditions must hold continuously for 10s** before the cor Once the **Cut-Off phase** is entered: -- if the BMS reports that cells are **equalizing**, the cut-off timer is stopped: the charge is held so the balancer can work; +- if the cells are reported — or inferred — as **equalizing**, the cut-off timer is stopped: the charge is held so the balancer can work; - otherwise the **cut-off timer** starts (`180s` default): if the Cut-Off conditions still hold when it expires, the **EOC** (End Of Charge) is declared; - in parallel, if the `EOC timer` switch is enabled, the **EOC timer** (`30min` default) guarantees that the Cut-Off phase ends at the latest when it expires, even if cells are still equalizing. Returning to the Bulk phase stops both timers. +Some BMS balance their cells but never expose a balancing flag. YamBMS infers it for +them, from the max cell reaching the bulk setpoint together with a cell spread that has +reached `bms_balance_trigger_voltage`, the threshold at which that pack's own balancer +engages, so the cut-off timer is held exactly as it would be with a +BMS that reports the flag. A real external balancer, when one is online, always takes +priority over the inference. This is enabled by default for Seplos V3, Seplos V1/V2, +EG4 LL v2 and JK RS485 DISPLAY — see +[Changelog_Fake_Equalizing.md](changelog/Changelog_Fake_Equalizing.md) for the references +it uses and how to tune or disable it. + ## LFP Cut-Off Values - Nominal : 3.20 V diff --git a/documents/README/changelog/Changelog_Fake_Equalizing.md b/documents/README/changelog/Changelog_Fake_Equalizing.md new file mode 100644 index 0000000..1b44c76 --- /dev/null +++ b/documents/README/changelog/Changelog_Fake_Equalizing.md @@ -0,0 +1,249 @@ +# YamBMS - Changelog about the new Fake Equalizing + +[![Badge License: GPLv3](https://img.shields.io/badge/License-GPLv3-brightgreen.svg)](https://www.gnu.org/licenses/gpl-3.0) +[![Badge Version](https://img.shields.io/github/v/release/Sleeper85/esphome-yambms?include_prereleases&color=yellow&logo=DocuSign&logoColor=white)](https://github.com/Sleeper85/esphome-yambms/releases/latest) +![GitHub stars](https://img.shields.io/github/stars/Sleeper85/esphome-yambms) +![GitHub forks](https://img.shields.io/github/forks/Sleeper85/esphome-yambms) +![GitHub watchers](https://img.shields.io/github/watchers/Sleeper85/esphome-yambms) + +`packages/bms/bms_options_fake_equalizing.yaml` + +Original idea by [@haysdb](https://github.com/haysdb), who reported the problem and +proposed a first implementation. The package shipped here is a much smaller rewrite of +that idea — see [Why not the original pull request](#why-not-the-original-pull-request) +at the end. + +--- + +## 1. The problem + +Several BMS balance their cells but never expose a balancing flag over their protocol. +The YamBMS packages for those BMS had no choice but to declare the flag as a constant: + +```yaml + # equalizing + - platform: template + id: bms${bms_id}_bms_equalizing + lambda: return false; +``` + +That constant is not a neutral placeholder, it is a wrong value. Those packs *do* +balance, and `equalizing` is not a cosmetic entity: in `yambms_core.yaml`, while it is +true the **Cut-Off timer is stopped** and the charge is allowed to continue up to the EOC +timer. Reporting `false` during a real balancing phase means the charge is terminated +while the pack is still equalizing, cycle after cycle, and the user has no indication +that anything is wrong. + +## 2. What the package does + +It infers the flag from the pack itself, and — this is the part that matters — **it +hardcodes neither of the two references it needs**. Both are already in your +configuration. + +**The voltage reference** is the per-cell bulk setpoint: + +```cpp +cell_bulk_v = bulk_voltage / cell_count +``` + +the exact derivation `yambms_core.yaml` already uses for its own end-of-charge +comparison. It follows `yambms_battery_chemistry`, the cell count and the bulk voltage you +configured, with no per-chemistry constant to maintain. LFP, Li-ion and LTO work out of +the box. + +**The spread reference** is `bms_balance_trigger_voltage` — the very spread at which your +pack's own balancer engages. That number is not a matter of taste, and it is not the same +from one BMS to the next: **10 mV on a JK or a Seplos, 30 mV on an EG4 LL v2**. A fixed +constant would have fitted none of them — it would have reported balancing on a pack whose +balancer is idle, or stayed silent on one that is working. `bms_base_balancer.yaml` +already resolves this value to the external balancer's setting whenever one is online, and +to the BMS's own otherwise. + +A pack that reports no trigger voltage at all never starts. There is no basis to claim it +is balancing, and no threshold worth inventing for it: the inference simply stays out of +the way and the behaviour is the one you have today. + +``` + START when BOTH are true + max cell >= cell_bulk_v the pack is at the setpoint + AND (max - min) >= trigger voltage its own balancing threshold + + STOP when EITHER is true + max cell < cell_bulk_v - hysteresis the pack dropped off the setpoint + OR (max - min) < trigger - delta hyst. the spread closed back below it +``` + +The **spread condition is what keeps this honest**. A pack that reaches the setpoint +already balanced has nothing to equalize: it reports `false` and the Cut-Off timer does +its job normally. A plain voltage comparison, with no spread condition, would report +balancing forever and push every single charge to the EOC timer ceiling. + +The **two hysteresis margins** exist because both references are sat *on* at top of +charge: the max cell rests on the setpoint for a long time, and the spread hovers around +the trigger voltage. Without them the state would toggle on every tick. + +The spread and its threshold are compared as whole millivolts, the resolution the cells +are reported at. This is not cosmetic: `3.450f - 3.445f` evaluates to `0.005000114`, so a +raw float comparison against `0.005` would hold the spread above the threshold forever and +never release the Cut-Off timer. + +### Where it plugs in + +The package extends `bms${bms_id}_bms_equalizing`, the **raw** BMS flag, and not the +combined `bms${bms_id}_equalizing` sensor. Consequence: `bms_base_balancer.yaml` is +neither modified nor duplicated, and it keeps giving an **external balancer priority** +whenever one is online. If you run a NEEY or a Modbus balancer on that `bms_id`, its +reading wins; the inference only applies when no balancer reports for this pack. + +## 3. Which BMS are concerned + +The four BMS below shipped a hardcoded `return false;`. The package is now **included by +default** for them — there is nothing to add to your YAML: + +| BMS | Packages | +|---|---| +| EG4 LL V2 | `bms_combine_EG4_LLV2_RS485_bms_full.yaml`
`bms_modbus_EG4_LLV2_RS485_bms_full.yaml` | +| Seplos V1 V2 | `bms_combine_SEPLOS_V1_V2_RS485_bms_full.yaml`
`bms_modbus_SEPLOS_V1_V2_RS485_bms_full.yaml` | +| Seplos V3 | `bms_combine_SEPLOS_V3_RS485_bms_full.yaml`
`bms_modbus_SEPLOS_V3_RS485_bms_full.yaml` | +| JK RS485 DISPLAY | `bms_combine_JK_RS485_DISPLAY_full.yaml` | + +The `bms_modbus_*` variants are the multi-node server packages, so a secondary node +relays the inferred flag to the client exactly like a real one. + +The **Fake BMS** (`bms_combine_FAKE.yaml`, `_FAKE_extended.yaml`, `_DEMO.yaml`) also uses +it now. It previously carried an inline voltage comparison with no spread condition, +which the package replaces. + +### BMS that are *not* concerned + +- **JK** (BLE, RS485 Modbus, UART 4G-GPS), **JBD**, **Ecoworthy**, **PACE**, **Deye CAN** + and the YamBMS Modbus client node all report a real balancing flag. Nothing changes. +- **BASEN** already infers the flag inline, from its own `balance_starting_voltage` and + `balance_trigger_voltage` reported by the BMS. Those are a better source than a + derived anchor, so it is left as is. +- **KS BLE** derives the flag from the balanced-cell bitmask, which is real information. + +The package can be added manually to another BMS, once for each `bms_id`: + +```yaml + - path: packages/bms/bms_options_fake_equalizing.yaml + vars: + bms_id: '1' # must be a number +``` + +but only where `bms_bms_equalizing` is declared as a plain `platform: template` +binary_sensor, which is what it replaces the lambda of. A BMS that exposes the flag +through its own component — `jk_bms_ble`, `jbd_bms`, `modbus_controller` and the like — +cannot be extended this way: those platforms take no `lambda:`, and the configuration +will not validate. That is not a real limitation, since those are precisely the BMS that +already report a genuine flag. + +## 4. Tuning + +### The one setting that matters: `bms_balance_trigger_voltage` + +This is your BMS's own balancing threshold, and it is the spread the inference compares +against. Some BMS report it over their protocol; those that cannot expose it as a var to +declare at import — **Seplos V1/V2, Seplos V3, EG4 LL v2 and JK RS485 DISPLAY all work +that way**. It also feeds `Auto CVL`, so it was already worth getting right. + +EG4 LL v2 and JK RS485 DISPLAY used a hard-coded value. +They now expose it like the others with the following default values: + +| BMS | Default | +|---|---| +| EG4 LL V2 | 0.03 | +| SEPLOS V1 V2 | 0.01 | +| SEPLOS V3 | 0.01 | +| JK RS485 DISPLAY | 0.01 | + +```yaml + # BMS 1 + - path: 'packages/bms/bms_combine_your_BMS.yaml' + vars: + bms_id: '1' + # ... other vars of your BMS ... + bms_balance_trigger_voltage: '0.010' # V. Your BMS's balancing threshold + bms_fake_equalizing_enabled: 'true' # Optional : true/fasle, true by default + bms_fake_equalizing_hysteresis: '0.030' # Optional : 0.030 by default + bms_fake_equalizing_delta_hysteresis: '0.002' # Optional : 0.002 by default +``` + +Set it to what your BMS is actually configured for. On a JK you can read and change it in +the BMS itself; on an EG4 it may not be adjustable, in which case leave the default. + +### The rest + +An on/off switch and two margins around the references. No threshold among them, and the +defaults are fine for any pack. + +| Substitution | Default | Meaning | +|---|---|---| +| `bms_fake_equalizing_enabled` | `'true'` | set to `'false'` to turn the inference off for this BMS | +| `bms_fake_equalizing_hysteresis` | `0.030` | how far below the bulk setpoint the max cell may fall before balancing stops | +| `bms_fake_equalizing_delta_hysteresis` | `0.002` | how far below the trigger voltage the spread may fall before balancing stops | + +All of them can be passed per BMS as above, or set once for every BMS in the root +`substitutions:` block. The spread values are resolved to whole millivolts, the resolution +the cells are reported at, so a value finer than `0.001` has no effect. + +**To disable the inference** on a BMS without editing any package: + +```yaml + bms_fake_equalizing_enabled: 'false' +``` + +The flag then reports the constant `false` its package used to hardcode, which is the +behaviour you had before this release. Do *not* try to disable it by raising +`bms_balance_trigger_voltage` instead — that value also feeds `Auto CVL`, where it means +something else entirely: how far the highest cell may overshoot the per-cell setpoint +before the PI clamps. + +## 5. What changes for you on upgrade + +If you own one of the four BMS above, the `balancing` entity will now turn on at the top +of charge as soon as your cells are spread by as much as your BMS's own +`bms_balance_trigger_voltage` — 10 mV on a Seplos or a JK, 30 mV on an EG4 unless you +declared otherwise. The charge then runs until the spread closes back below that, or +until the EOC timer expires, instead of being cut short by the Cut-Off timer. That is the +intended fix, but it *is* a change in charge termination, so watch a couple of cycles +after updating. + +The risk is bounded on the safe side. A false positive can only extend the charge up to +the EOC timer, which exists for exactly that purpose. A false negative simply restores +the previous behaviour. + +## Why not the original pull request + +[@haysdb](https://github.com/haysdb) opened +[PR #304](https://github.com/Sleeper85/esphome-yambms/pull/304) with a *Fake Balancer* +package. The diagnosis was right and the idea is his. The implementation was shaped +around his own setup — a NEEY balancer that does not run every day — and carried more +than YamBMS needs: + +- **Absolute thresholds as entities.** Four `number` entities held the start / sleep / + trigger / stop-diff voltages, hardcoded to LFP values (3.45 / 3.42 V). They lived + alongside the bulk voltage the user had already configured, so the same physical + setpoint existed twice and could drift apart. Taking the voltage reference from + `bulk_voltage / cell_count` and the spread reference from + `bms_balance_trigger_voltage` removes the duplication entirely, and makes the + package track each BMS instead of a constant that fits none of them. +- **A companion stub package.** The lambda referenced `balancer${bms_id}_online_status` + and `balancer${bms_id}_equalizing`, which only exist when a balancer package is + included, so a second package had to declare two always-false sensors just to make it + compile without one. Reading the raw BMS flag instead makes the stub unnecessary. +- **A duplicated core lambda.** It extended the *combined* `bms${bms_id}_equalizing` and + recopied the branch from `bms_base_balancer.yaml` to add its OR. Extending the raw flag + keeps a single copy of that logic. +- **A side effect on another entity.** The interval wrote + `bms${bms_id}_var_ext_balancer_online = real_online || fake_eq`, which made + `bms_base_balancer.yaml` report the external balancer's trigger voltage — `0.000 V` + when no balancer had ever been online. +- **Eight entities and a sub-device per BMS**, for a function that needs none. + +The `Force` switch and the `Max Run Time` number were dropped as well: they answer the +need to launch a weekly top-balance by hand when the hardware balancer is idle, which is +a balancer feature rather than a BMS one. + +Thanks to @haysdb for finding the problem and for the threshold model — start and stop on +a spread with hysteresis is his, and it is the part that makes the inference trustworthy. diff --git a/examples/single-node/LP_BMS_example_EG4_LLV2_RS485_Modbus.yaml b/examples/single-node/LP_BMS_example_EG4_LLV2_RS485_Modbus.yaml index b23d152..a67c596 100644 --- a/examples/single-node/LP_BMS_example_EG4_LLV2_RS485_Modbus.yaml +++ b/examples/single-node/LP_BMS_example_EG4_LLV2_RS485_Modbus.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.02.16 -# Version : 1.1.4 +# Updated : 2026.08.29 +# Version : 1.1.5 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -39,6 +39,7 @@ packages: bms_name: 'EG4-BMS 1' ## BMS address must start at 2 with EG4 LLV2, ID 1 is a special case and has different output. bms_address: 2 # BMS 1 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable bms2: !include @@ -47,6 +48,7 @@ packages: bms_id: '2' # must be a number bms_name: 'EG4-BMS 2' bms_address: 3 # BMS 2 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable bms3: !include @@ -55,4 +57,5 @@ packages: bms_id: '3' # must be a number bms_name: 'EG4-BMS 3' bms_address: 4 # BMS 3 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable diff --git a/examples/single-node/RP_BMS_example_EG4_LLV2_RS485_Modbus.yaml b/examples/single-node/RP_BMS_example_EG4_LLV2_RS485_Modbus.yaml index 53e0dfa..5849961 100644 --- a/examples/single-node/RP_BMS_example_EG4_LLV2_RS485_Modbus.yaml +++ b/examples/single-node/RP_BMS_example_EG4_LLV2_RS485_Modbus.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.02.16 -# Version : 1.1.4 +# Updated : 2026.08.29 +# Version : 1.1.5 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -43,6 +43,7 @@ bms_name: 'EG4-BMS 1' ## BMS address must start at 2 with EG4 LLV2, ID 1 is a special case and has different output. bms_address: 2 # BMS 1 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours 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_EG4_LLV2_RS485_bms_full.yaml' @@ -50,6 +51,7 @@ bms_id: '2' # must be a number bms_name: 'EG4-BMS 2' bms_address: 3 # BMS 2 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable # BMS 3 - path: 'packages/bms/bms_combine_EG4_LLV2_RS485_bms_full.yaml' @@ -57,4 +59,5 @@ bms_id: '2' # must be a number bms_name: 'EG4-BMS 3' bms_address: 4 # BMS 3 modbus address + bms_balance_trigger_voltage: '0.030' # V. Cell spread at which the BMS balances, set yours bms_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable diff --git a/packages/bms/bms_combine_DEMO.yaml b/packages/bms/bms_combine_DEMO.yaml index 1cb4eae..f03140f 100644 --- a/packages/bms/bms_combine_DEMO.yaml +++ b/packages/bms/bms_combine_DEMO.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -20,6 +20,7 @@ packages: bms_sensors: !include bms_sensors_FAKE.yaml bms_numbers: !include bms_sensors_FAKE_extended.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_demo_cs: !include bms_demo_charge_simulation.yaml bms_combine: !include file: bms_combine.yaml diff --git a/packages/bms/bms_combine_EG4_LLV2_RS485_bms_full.yaml b/packages/bms/bms_combine_EG4_LLV2_RS485_bms_full.yaml index fb46268..148aa20 100644 --- a/packages/bms/bms_combine_EG4_LLV2_RS485_bms_full.yaml +++ b/packages/bms/bms_combine_EG4_LLV2_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.3 +# Updated : 2026.08.28 +# Version : 1.1.4 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -21,6 +21,7 @@ packages: bms_sensors: !include bms_sensors_EG4_LLV2_RS485_bms_full.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include file: bms_combine.yaml vars: diff --git a/packages/bms/bms_combine_FAKE.yaml b/packages/bms/bms_combine_FAKE.yaml index b0f1eee..ddd7dfc 100644 --- a/packages/bms/bms_combine_FAKE.yaml +++ b/packages/bms/bms_combine_FAKE.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,6 +19,7 @@ packages: bms_sensors: !include bms_sensors_FAKE.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include file: bms_combine.yaml vars: diff --git a/packages/bms/bms_combine_FAKE_extended.yaml b/packages/bms/bms_combine_FAKE_extended.yaml index ae9db17..987a65f 100644 --- a/packages/bms/bms_combine_FAKE_extended.yaml +++ b/packages/bms/bms_combine_FAKE_extended.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -20,6 +20,7 @@ packages: bms_sensors: !include bms_sensors_FAKE.yaml bms_numbers: !include bms_sensors_FAKE_extended.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include file: bms_combine.yaml vars: diff --git a/packages/bms/bms_combine_JK_RS485_DISPLAY_full.yaml b/packages/bms/bms_combine_JK_RS485_DISPLAY_full.yaml index 90fe836..1bbc555 100644 --- a/packages/bms/bms_combine_JK_RS485_DISPLAY_full.yaml +++ b/packages/bms/bms_combine_JK_RS485_DISPLAY_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.2.0 +# Updated : 2026.08.29 +# Version : 1.2.2 # GitHub : https://github.com/syssi/esphome-jk-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,6 +19,7 @@ packages: bms_base: !include bms_base.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include file: bms_combine.yaml vars: @@ -27,6 +28,13 @@ packages: bms_temperature_sensor: !include bms_temperature_sensor_2.yaml bms_battery_soh: !include bms_base_battery_soh.yaml +substitutions: + # (V) cell spread at which this BMS starts balancing. Not readable over the display + # port, so declare your unit's actual setting at import. Used by 'Auto CVL' and, when + # bms_options_fake_equalizing.yaml is included, as the spread reference for the + # inferred balancing flag. + bms_balance_trigger_voltage: '0.01' + # +--------------------------------------+ # | DISPLAY port schematic | # +--------------------------------------+ @@ -193,7 +201,7 @@ sensor: device_id: bms_${bms_id} # name: "state of charge" delta_cell_voltage: - device_id: bms_${bms_id} + device_id: bms_${bms_id} name: "delta cell voltage" mosfet_temperature: id: bms${bms_id}_temperature_sensor_1 @@ -384,7 +392,7 @@ sensor: - or: - throttle: 10s - delta: 0.001 - lambda: return 0.005; + lambda: return ${bms_balance_trigger_voltage}; # FAKE charging_cycles - platform: template diff --git a/packages/bms/bms_combine_SEPLOS_V1_V2_RS485_bms_full.yaml b/packages/bms/bms_combine_SEPLOS_V1_V2_RS485_bms_full.yaml index 7451793..367e2db 100644 --- a/packages/bms/bms_combine_SEPLOS_V1_V2_RS485_bms_full.yaml +++ b/packages/bms/bms_combine_SEPLOS_V1_V2_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/syssi/esphome-seplos-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,6 +19,7 @@ packages: bms_sensors: !include bms_sensors_SEPLOS_V1_V2_RS485_bms_full.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include file: bms_combine.yaml vars: diff --git a/packages/bms/bms_combine_SEPLOS_V3_RS485_bms_full.yaml b/packages/bms/bms_combine_SEPLOS_V3_RS485_bms_full.yaml index 37e374f..140394d 100644 --- a/packages/bms/bms_combine_SEPLOS_V3_RS485_bms_full.yaml +++ b/packages/bms/bms_combine_SEPLOS_V3_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/syssi/esphome-seplos-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,6 +19,7 @@ packages: bms_sensors: !include bms_sensors_SEPLOS_V3_RS485_bms_full.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include file: bms_combine.yaml vars: diff --git a/packages/bms/bms_demo_charge_simulation.yaml b/packages/bms/bms_demo_charge_simulation.yaml index d49f9e8..2793395 100644 --- a/packages/bms/bms_demo_charge_simulation.yaml +++ b/packages/bms/bms_demo_charge_simulation.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.06.29 -# Version : 1.1.3 +# Updated : 2026.08.29 +# Version : 1.1.4 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -38,6 +38,9 @@ substitutions: min_temperature: '4.8' max_temperature: '5.0' delta_cell_voltage: '0.005' + # Spread held during the two balancing steps. Must stay above this BMS's + # `bms_balance_trigger_voltage` for the inferred equalizing flag to assert. + delta_cell_voltage_balancing: '0.020' switch: # DEMO switch @@ -118,14 +121,14 @@ interval: // Step 4 : 98% (10sec) id(bms${bms_id}_state_of_charge).publish_state(98); id(bms${bms_id}_current).publish_state(5); - id(bms${bms_id}_min_cell_voltage).publish_state(requested_cvl / cell_count + 0.01 - ${delta_cell_voltage}); + id(bms${bms_id}_min_cell_voltage).publish_state(requested_cvl / cell_count + 0.01 - ${delta_cell_voltage_balancing}); id(bms${bms_id}_max_cell_voltage).publish_state(requested_cvl / cell_count + 0.01); // equalizing } else if (seconds <= 5 * step_sec) { // Entering Cut-off phase... // Step 5 : 99% (10sec) id(bms${bms_id}_state_of_charge).publish_state(99); id(bms${bms_id}_current).publish_state(3.5); - id(bms${bms_id}_min_cell_voltage).publish_state(requested_cvl / cell_count + 0.005 - ${delta_cell_voltage}); + id(bms${bms_id}_min_cell_voltage).publish_state(requested_cvl / cell_count + 0.005 - ${delta_cell_voltage_balancing}); id(bms${bms_id}_max_cell_voltage).publish_state(requested_cvl / cell_count + 0.005); // equalizing } else if (seconds <= 15 * step_sec) { // End of Cut-off phase... diff --git a/packages/bms/bms_modbus_EG4_LLV2_RS485_bms_full.yaml b/packages/bms/bms_modbus_EG4_LLV2_RS485_bms_full.yaml index 9e12bd1..6c5cb98 100644 --- a/packages/bms/bms_modbus_EG4_LLV2_RS485_bms_full.yaml +++ b/packages/bms/bms_modbus_EG4_LLV2_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.4 +# Updated : 2026.08.28 +# Version : 1.1.5 # GitHub : https://github.com/syssi/esphome-jk-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,4 +19,5 @@ packages: bms_sensors: !include bms_sensors_EG4_LLV2_RS485_bms_full.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include bms_modbus_server.yaml diff --git a/packages/bms/bms_modbus_SEPLOS_V1_V2_RS485_bms_full.yaml b/packages/bms/bms_modbus_SEPLOS_V1_V2_RS485_bms_full.yaml index 5a82e6f..4ad85cd 100644 --- a/packages/bms/bms_modbus_SEPLOS_V1_V2_RS485_bms_full.yaml +++ b/packages/bms/bms_modbus_SEPLOS_V1_V2_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/syssi/esphome-pace-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,4 +19,5 @@ packages: bms_sensors: !include bms_sensors_SEPLOS_V1_V2_RS485_bms_full.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include bms_modbus_server.yaml diff --git a/packages/bms/bms_modbus_SEPLOS_V3_RS485_bms_full.yaml b/packages/bms/bms_modbus_SEPLOS_V3_RS485_bms_full.yaml index d4eed66..93be0d9 100644 --- a/packages/bms/bms_modbus_SEPLOS_V3_RS485_bms_full.yaml +++ b/packages/bms/bms_modbus_SEPLOS_V3_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.14 -# Version : 1.1.2 +# Updated : 2026.08.28 +# Version : 1.1.3 # GitHub : https://github.com/syssi/esphome-pace-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -19,4 +19,5 @@ packages: bms_sensors: !include bms_sensors_SEPLOS_V3_RS485_bms_full.yaml + bms_fake_equalizing: !include bms_options_fake_equalizing.yaml bms_combine: !include bms_modbus_server.yaml diff --git a/packages/bms/bms_options_fake_equalizing.yaml b/packages/bms/bms_options_fake_equalizing.yaml new file mode 100644 index 0000000..e9f8b47 --- /dev/null +++ b/packages/bms/bms_options_fake_equalizing.yaml @@ -0,0 +1,214 @@ +# Updated : 2026.08.29 +# 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 . + + + +# +--------------------------------------------------------------------------------+ +# | Fake Equalizing - infer the balancing flag a BMS does not report | +# +--------------------------------------------------------------------------------+ +# | Some BMS balance their cells but never expose a balancing flag, so +# | `bms_equalizing` stays false and the core cannot tell a pack that is still +# | balancing from one that has finished. That matters : while equalizing is true +# | the core stops the Cut-Off timer (yambms_core.yaml) and lets the charge run to +# | the EOC timer instead of terminating early. +# | +# | This package infers that flag from the pack itself, and hardcodes neither of the +# | two references it needs : +# | +# | the voltage anchor is the per-cell bulk setpoint, `bulk voltage / cell count`, +# | the same derivation as cell_bulk_v in yambms_core.yaml, so it follows +# | `yambms_battery_chemistry`, the cell count and the configured bulk voltage ; +# | +# | the spread anchor is `bms${bms_id}_balance_trigger_voltage`, the very spread at +# | which this pack's own balancer engages. bms_base_balancer.yaml resolves it to +# | the external balancer's value whenever one is online, to the BMS's otherwise. +# | +# | START when BOTH are true : +# | max cell >= cell bulk setpoint the pack is at the setpoint +# | AND (max - min) >= trigger voltage the pack's own balancing threshold +# | +# | STOP when EITHER is true : +# | max cell < setpoint - hysteresis the pack dropped off the setpoint +# | OR (max - min) < trigger - delta hyst. the spread closed back below it +# | +# | Nothing is configurable but an on/off switch and the two hysteresis margins, so +# | the inference tracks the hardware instead of a constant that would fit no BMS in +# | particular : the +# | balance trigger voltage is 10 mV on a JK or a Seplos, 30 mV on an EG4. A pack that +# | reports none at all never starts - there is no threshold worth inventing for it. +# | +# | The spread condition is what keeps this honest : a pack that reaches the setpoint +# | already balanced has nothing to equalize, so it reports false and the Cut-Off +# | timer does its job. A plain voltage comparison would report balancing forever and +# | terminate the charge on the EOC timer every cycle. +# | +# | It extends `bms_equalizing`, the RAW BMS flag, not the combined +# | `bms${bms_id}_equalizing` sensor. So bms_base_balancer.yaml is untouched and +# | keeps giving an external balancer (NEEY, modbus client) priority whenever one +# | is online : the inference only applies when no balancer reports for this pack. +# | +# | REQUIRES the BMS package it is included alongside to expose : +# | +# | bms${bms_id}_bms_equalizing the raw flag, declared as a template +# | binary_sensor (extended here) +# | bms${bms_id}_max_cell_voltage +# | bms${bms_id}_min_cell_voltage +# | +# | plus, both always present : +# | +# | bms${bms_id}_balance_trigger_voltage from bms_base_balancer.yaml +# | yambms${yambms_id}_bulk_voltage from the core +# | yambms${yambms_id}_cell_count +# | +# | A BMS that cannot read its balancing threshold over its protocol exposes it as the +# | `bms_balance_trigger_voltage` var instead, to be set at import - Seplos V1/V2 and +# | V3, EG4 LL v2 and JK RS485 DISPLAY all work that way. Declare your unit's actual +# | setting there : it is what this package compares the spread against. +# +--------------------------------------------------------------------------------+ +# | Included by default - these BMS need nothing added to your YAML +# +--------------------------------------------------------------------------------+ +# | +# | EG4 LL V2 bms_combine_EG4_LLV2_RS485_bms_full.yaml +# | bms_modbus_EG4_LLV2_RS485_bms_full.yaml +# | Seplos V1 V2 bms_combine_SEPLOS_V1_V2_RS485_bms_full.yaml +# | bms_modbus_SEPLOS_V1_V2_RS485_bms_full.yaml +# | Seplos V3 bms_combine_SEPLOS_V3_RS485_bms_full.yaml +# | bms_modbus_SEPLOS_V3_RS485_bms_full.yaml +# | JK RS485 DISP. bms_combine_JK_RS485_DISPLAY_full.yaml +# | Fake BMS bms_combine_FAKE.yaml, _FAKE_extended.yaml, _DEMO.yaml +# | +# | The four real BMS above declared `bms_equalizing` as a hardcoded +# | `return false;` : they do balance, they just never say so. The Fake BMS used +# | to carry an inline voltage comparison, which this package replaces. +# +--------------------------------------------------------------------------------+ +# | Adding it to another BMS - once for each bms_id +# +--------------------------------------------------------------------------------+ +# +# - path: packages/bms/bms_options_fake_equalizing.yaml +# vars: +# bms_id: '1' # must be a number +# +# | Only where `bms${bms_id}_bms_equalizing` is declared as a plain +# | `platform: template` binary_sensor, since this replaces its lambda. A BMS that +# | exposes the flag through its own component - jk_bms_ble, jbd_bms, +# | modbus_controller and the like - cannot be extended this way : those platforms +# | take no `lambda:` and the configuration will not validate. No real loss, as those +# | are exactly the BMS that already report a genuine flag. +# +# +--------------------------------------------------------------------------------+ +# | Tuning - add the vars to your BMS include, they override the defaults below +# +--------------------------------------------------------------------------------+ +# +# # BMS 1 +# - path: 'packages/bms/bms_combine_your_BMS.yaml' +# vars: +# bms_id: '1' +# # ... other vars of your BMS ... +# bms_balance_trigger_voltage: '0.010' # V. Your BMS's balancing threshold +# bms_fake_equalizing_enabled: 'true' # Optional : true/fasle, true by default +# bms_fake_equalizing_hysteresis: '0.030' # Optional : 0.030 by default +# bms_fake_equalizing_delta_hysteresis: '0.002' # Optional : 0.002 by default +# +# | The one worth setting is `bms_balance_trigger_voltage` : it is your BMS's own +# | balancing threshold, it also feeds 'Auto CVL', and the rest is fine as it is. +# | +# | Or set them once for every BMS in the root `substitutions:` block. +# | To turn the inference off on one BMS : bms_fake_equalizing_enabled: 'false' +# +--------------------------------------------------------------------------------+ + + + +substitutions: + # +--------------------------------------------------------------------------------+ + # | Nothing here is a threshold : the two references come from elsewhere. + # | The voltage anchor is the per-cell bulk setpoint, from the core. + # | The spread anchor is `bms_balance_trigger_voltage`, from the BMS itself. + # | What is left is an on/off switch and the two hysteresis margins. + # +--------------------------------------------------------------------------------+ + # 'true' / 'false'. Set to 'false' to turn the inference off for this BMS : the flag + # goes back to the constant false its package used to report. Needed because the + # package is included by default for the BMS that cannot report the flag, and a + # Remote Packages user cannot edit a package to drop it. + bms_fake_equalizing_enabled: 'true' + # (V) how far below the bulk setpoint the max cell may fall before balancing stops. + # Without it the state toggles on every tick while the max cell sits on the setpoint. + bms_fake_equalizing_hysteresis: '0.030' + # (V) how far below the balance trigger voltage the spread may fall before balancing + # stops. Resolved to whole millivolts, the resolution the cells are reported at : + # a value finer than 0.001 has no effect. + bms_fake_equalizing_delta_hysteresis: '0.002' + +binary_sensor: + # equalizing (inferred) + - id: !extend bms${bms_id}_bms_equalizing + lambda: |- + static bool balancing = false; + + // Turned off : report the constant false this BMS package used to hardcode. + if (!${bms_fake_equalizing_enabled}) + return false; + + float cell_count = id(yambms${yambms_id}_cell_count).state; + float bulk_v = id(yambms${yambms_id}_bulk_voltage).state; + float max_cell_v = id(bms${bms_id}_max_cell_voltage).state; + float min_cell_v = id(bms${bms_id}_min_cell_voltage).state; + float trigger_v = id(bms${bms_id}_balance_trigger_voltage).state; + + // The spread reference is the balance trigger voltage : the very spread at which + // this pack's own balancer engages, so the inference tracks the hardware instead + // of a constant that would fit no BMS in particular. bms_base_balancer.yaml + // resolves it to the external balancer's value whenever one is online. + // + // Hold the last state while any reference is missing, rather than dropping out of + // balancing on a single missing reading and releasing the Cut-Off timer. A pack + // that never reports a trigger voltage never starts : there is no basis to claim + // it is balancing, and no threshold worth inventing for it. Some packages do + // publish 0 before their first read (PACE, the Modbus client node), which this + // covers as well. + if (isnan(cell_count) || cell_count <= 0 || isnan(bulk_v) || + isnan(max_cell_v) || isnan(min_cell_v) || + isnan(trigger_v) || trigger_v <= 0.0f) + return balancing; + + // Same derivation as cell_bulk_v in yambms_core.yaml + float cell_bulk_v = bulk_v / cell_count; + + // The spread and its threshold are compared as whole millivolts, which is the + // resolution the cells are reported at. A float subtraction of two mV-aligned + // readings lands a fraction of a uV off - 3.450 - 3.445 gives 0.005000114 - which + // would hold the spread just above the threshold forever and never release the + // Cut-Off timer. The voltage gates keep their float comparison : their margin is + // the hysteresis, orders of magnitude above that error. + int delta_mv = (int) roundf((max_cell_v - min_cell_v) * 1000.0f); + int trigger_mv = (int) roundf(trigger_v * 1000.0f); + int hyst_mv = (int) roundf(${bms_fake_equalizing_delta_hysteresis} * 1000.0f); + + if (!balancing) + { + // Start : at the setpoint AND spread up to what makes this BMS balance + balancing = (max_cell_v >= cell_bulk_v) && (delta_mv >= trigger_mv); + } + else + { + // Stop : fell off the setpoint OR the spread closed back below the trigger + balancing = (max_cell_v >= cell_bulk_v - ${bms_fake_equalizing_hysteresis}) && + (delta_mv >= trigger_mv - hyst_mv); + } + + return balancing; diff --git a/packages/bms/bms_sensors_EG4_LLV2_RS485_bms_full.yaml b/packages/bms/bms_sensors_EG4_LLV2_RS485_bms_full.yaml index 404e634..b3c1204 100644 --- a/packages/bms/bms_sensors_EG4_LLV2_RS485_bms_full.yaml +++ b/packages/bms/bms_sensors_EG4_LLV2_RS485_bms_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.15 -# Version : 2.0.4 +# Updated : 2026.08.29 +# Version : 2.0.5 # GitHub : https://github.com/RAR/esphome-eg4-bms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -22,6 +22,13 @@ packages: bms_temperature_sensor: !include bms_temperature_sensor_4.yaml bms_errors_bitmask: !include bms_errors_bitmask_EG4_LLV2_RS485_Modbus.yaml +substitutions: + # (V) cell spread at which this BMS starts balancing. Not readable over the protocol, + # so declare your unit's actual setting at import. Used by 'Auto CVL' and, when + # bms_options_fake_equalizing.yaml is included, as the spread reference for the + # inferred balancing flag. + bms_balance_trigger_voltage: '0.030' + # +--------------------------------------+ # | Component settings | # +--------------------------------------+ @@ -281,7 +288,7 @@ sensor: - or: - throttle: 10s - delta: 0.001 - lambda: return 0.030; + lambda: return ${bms_balance_trigger_voltage}; - platform: template id: bms${bms_id}_cell_ovp diff --git a/packages/bms/bms_sensors_FAKE.yaml b/packages/bms/bms_sensors_FAKE.yaml index fcd7804..57fa521 100644 --- a/packages/bms/bms_sensors_FAKE.yaml +++ b/packages/bms/bms_sensors_FAKE.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.06.29 -# Version : 1.3.0 +# Updated : 2026.08.28 +# Version : 1.3.1 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -66,7 +66,6 @@ interval: float current = id(bms${bms_id}_current).state; float battery_capacity = id(bms${bms_id}_battery_capacity).state; float battery_soc = id(bms${bms_id}_state_of_charge).state; - float bulk_v = id(yambms${yambms_id}_bulk_voltage).state; // Voltage float voltage = cell_count * (min_cell_v + max_cell_v) / 2; @@ -76,12 +75,6 @@ interval: float power = (voltage * current); id(bms${bms_id}_power).publish_state(power); - // Equalizing - bool equalizing = false; - if (max_cell_v > bulk_v / cell_count) - equalizing = true; - id(bms${bms_id}_bms_equalizing).publish_state(equalizing); - // Capacity Remaining id(bms${bms_id}_capacity_remaining_ah).publish_state(battery_capacity * battery_soc / 100);