Files
esphome-yambms/documents/README/YamBMS_functions.md
T
Sleeper85 c9502bd196 Fix Requested Force Charge turning on while no BMS is combined (#346)
The binary sensor lambda was evaluated on every loop, including while no
BMS was combined (boot, BMS dropout). The SoC was NaN then, and
`int soc = NaN` is undefined: the request could turn on, and with a real
SoC between Start and Stop it stayed on until Stop SoC once the packs came
back.

The rule now runs in STEP 3, inside the "At least one BMS combined" block,
and publishes the sensor. While no BMS is combined it is not evaluated, so
the request keeps its last state. The SoC is read as a float: a NaN fails
both comparisons and keeps the current state too. The "Request force
charge" switch clears the request at once with an on_turn_off, even while
no BMS is combined.

Reported in #346, first fix proposed in #347.
2026-11-10 22:02:11 +01:00

38 KiB
Raw Blame History

YamBMS functions

Badge License: GPLv3 Badge Version GitHub stars GitHub forks GitHub watchers

Inverter Brand and Protocol

Important

Select your inverter brand and leave Protocol on Automatic. If your inverter is supported, the dashboard then shows how to configure it: the battery mode to set on the inverter and any note specific to your brand.

Image

Setup in three steps

  1. Set Inverter brand to the brand of your inverter. If it is not in the list, select Other and see Forcing a protocol.
  2. Leave Protocol on Automatic. YamBMS selects the best protocol known for your brand, following the mapping below.
  3. Configure your inverter as shown in the Inverter active protocol card: set the battery mode it gives you, and read the note if there is one.

As long as the brand is Not defined, nothing is sent on the bus and your inverter reports a BMS communication fault. This is deliberate, so that a node is never left talking a protocol nobody chose.

The inverter models confirmed by users are listed in supported inverters.

Brand to protocol mapping

In Automatic, YamBMS applies the protocol below for your brand. This mapping is a sensible default, not a rule: a manufacturer may use a different protocol depending on the model. Don't hesitate to share what works well for you.

Inverter Battery mode Bus Protocol
Deye Lithium 00 CAN PYLON V1
Deye Lithium 12 RS485 PYLON
EG4 Lithium 6 CAN LuxPower
Epever BPRO 21 RS485 PYLON
GoodWe LX U5.4-L CAN PYLON V2
Growatt CAN L52 CAN PYLON V1
LuxPower Lithium 6 CAN LuxPower
MidNite Solar PYLON CAN PYLON V1
MPP Solar PYL RS485 PYLON
MPP Solar LIB RS485 LIB
Schneider Voltage Control Li-Ion CAN PYLON V2
SMA - CAN SMA
Sofar Automatic CAN PYLON V1
Sol-Ark Lithium 00 CAN PYLON V1
Sol-Ark Lithium 12 RS485 PYLON
Solis AoBo CAN SMA
SRNE UZE CAN PYLON V2
Studer Pylontech CAN PYLON V2
Sunsynk Lithium 00 CAN PYLON V1
Sunsynk Lithium 12 RS485 PYLON
Victron CAN-bus BMS LV (500 kbit/s) CAN Victron
Voltronic PYL RS485 PYLON
Voltronic LIB RS485 LIB

Any other brand of the list, or a listed brand on the other bus, uses PYLON V2 on CAN by default, and the protocol compiled on the node on RS485. Such a combination has not been validated, and the Note entity says so.

RS485

On RS485 the protocol is chosen in your YAML with rs485_protocol (pylon or voltronic), and the brand does not change it. LIB only works with Voltronic and MPP Solar: in Automatic, a node compiled for LIB stays silent for any other brand. Rebranded Voltronic inverters must select Voltronic. The protocols offered by parameter 05 depend on the inverter firmware, see its user manual.

Forcing a protocol

Only change Protocol if your inverter does not communicate with the automatic choice, or if you selected Other. A forced protocol always takes priority over the brand, so an inverter that does not follow the usual mapping can still be driven. Disabled turns the link off without raising a fault.

The Inverter link protocol diagnostic entity always reports what the link is actually doing.

A few couples outside the default mapping are known to work, and YamBMS reports the right battery mode for them too: EG4 on PYLON V1 (Lithium 2, 6000XP only) and Solis on PYLON V2 (Pylon LV, requires a 3.3V CAN transceiver).

Charging settings

Image

The Charging status represents the current charging phase, see the Charging logic.

The Charging instruction is defined based on the Charging status and allows the correct Requested Charge Values ​​to be sent.

The Float charge enabled switch allows the battery to be kept fully charged at the end of the Bulk charge. The voltage used will be that of the Float voltage slider.

The EOC timer enabled switch ensures that the Cut-Off phase lasts maximum 30 min (default value) even if your cells are still being equalized. If your cells are equalized, the Cut-Off phase will end at the earliest after 60s (default value). This prevents the risk of staying in the Cut-Off phase for many hours if you have several batteries and they are poorly equalized.

Important

If you have totally unbalanced batteries and want to fix this problem, you can disable the EOC timer and let YamBMS balance your batteries, this can take hours. A well balanced battery does not need this timer enabled as the equalization phase will finish in less than 30 minutes.

The Bulk voltage slider allows you to set the voltage used during the Bulk, Balancing and Cut-Off phases.

The Float voltage slider allows you to set the voltage used after charging is complete if the Float charge enabled switch is enabled.

The Charger Offset V. slider allows you to correct the inverter charge voltage, either because it does not respect the requested value or because your inverter is far from your batteries and there is a voltage drop. This allows you to reach the target Bulk or Float charge voltage by adding an offset.

The Cut-Off Cell Voltage select defines which cell voltage is used by the Cut-Off detection, see the Charging logic.

  • Max Cell Voltage (default): the end of charge depends on the highest cell. This is the conservative option, recommended for most installations.
  • Average Cell Voltage: the end of charge reflects the state of the whole pack (battery voltage / cell count), giving a more consistent charge termination voltage from one day to the next. This option can help with batteries built from unmatched cells (different internal resistances), batteries with a runner cell, or a BMS that does not report its equalizing status.

Warning

With Average Cell Voltage, the highest cell no longer stops the charge and can be pushed above its maximum voltage. Only use this option with the Auto CVL and/or Auto CCL enabled, the BMS OVP protection remaining the last resort. If your inverter does not respect the requested charge voltage, only the current derating is effective.

Max Requested Current

Image

The requested charge/discharge current is calculated from three maximum values :

  1. You define a maximum current that can never be exceeded
  2. YamBMS calculates the maximum current accepted by your BMS (total of OCP values * 0.9)
  3. YamBMS calculates the nominal current of your battery bank based on the battery capacity and the C-Rate you have configured (default : 0.5C for charge and discharge, as recommended by most LFP cell datasheets, e.g. EVE MB31)

The current requested by YamBMS will be the lowest of these three values.

This result can then be further reduced by the active functions acting on the CCL and DCL :

Functions acting on the CCL (charge) :

  • Auto Temp-Based Current : reduces the charge current according to the temperature and the charging_rate_table
  • Auto CCL : reduces the charge current when a cell approaches the BMS OVP threshold
  • Auto CCL Current Taper : reduces the charge current along a knee→bulk curve based on pack voltage
  • Auto SoC Limit : clamps the charge current when the target SoC is reached
  • Auto EOC : slows down the charge so the battery reaches full charge at the chosen time

Functions acting on the DCL (discharge) :

  • Auto Temp-Based Current : reduces the discharge current according to the temperature and the discharging_rate_table
  • Auto DCL : reduces the discharge current when a cell approaches the BMS UVP threshold

The final CCL/DCL sent to the inverter is always the lowest value among all these functions. The CCL/DCL derating reason sensor shows which function is currently limiting the current.

Multi-inverter / multi-charger

YamBMS supports several inverters/chargers connected to the same battery bank. Each inverter/charger declared in your YAML has its own CAN or RS485 package, and each one receives the same Requested Charge/Discharge Current.

To prevent the battery bank from being charged/discharged at N times the calculated limit, YamBMS divides the CCL and DCL by the number of declared inverter/charger links :

Example : a CCL of 150 A with 2 inverters declared → each inverter receives 75 A

Each declared yambms_canbus.yaml / yambms_rs485.yaml package increments a link counter at boot, and the final CCL/DCL is divided by this counter, then rounded. The division is applied after all the limiting functions above, so it always applies to the final value.

Warning

Only declare the links that are actually wired to an inverter/charger. The counter is based on the declared links, not on the active ones: a link whose Protocol is Disabled, or left on Automatic with no Inverter brand, still divides the CCL/DCL. With a CAN link in use and an unused RS485 link left in your YAML, your inverter receives half the calculated current. Comment out the package of any link you don't use.

This is deliberate. Disabled is meant to cut a link temporarily, while the inverter behind it is usually still connected to the battery bank and running on its own settings. Keeping it in the divider leaves room for the current it draws.

Note

The counter is only incremented by the inverter/charger packages. A node with no inverter link declared keeps a divider of 1, so the CCL/DCL are left unchanged.

Important

The division assumes your inverters/chargers share the load evenly. This is the case for identical units working in parallel on the same bank. If your units have different power ratings, or if one of them is offline or its link is Disabled, the total current drawn from the battery will be lower than the calculated limit — never higher.

Requested Values

Image

These 4 sensors allow you to see what is being requested of your inverter.

In the example below, we are in the Float phase at a voltage of 53.6V and an Charger Offset V. of 0.1V. The Requested Charge Voltage is therefore 53.7V.

The Requested Discharge Voltage is the UVP + 0.2 value of your BMS multiplied by the number of cells, in this example (3V * 16).

ReBulk

Image

There are three parameters to start a new Bulk phase. You can set a Rebulk SoC, a Rebulk V. value or the Rebulk Days (since last full charge), only one of these conditions must be met. Rebulk Days can be disabled by setting them to 0.

If needed you can also force a Bulk charge with the Force Bulk (top bal) switch. The switch will automatically deactivate when your cells enter the Balancing phase.

Request Force Charge

Image

This function allows you to force a charge from GRID :

  • when SoC <= Start SoC the forced charge start
  • when SoC >= Stop SoC the forced charge stop

The request is only evaluated while at least one BMS is combined. During a reboot or a BMS dropout the SoC is not a real value, so the request keeps its last state. Turning the switch off clears it at once.

Works only with PYLON, LuxPower and Victron protocols.

Auto functions

Thanks to @MrPabloUK for developing Auto CVL, Auto CCL, Auto DCL and Auto Temp-Based Current functions.

A reference spreadsheet has been created that shows how the Auto CCL & DCL works.

Thanks to @GHswitt for developing Auto Float, Auto EOC and Auto SoC Limit functions.

Auto Temp-Based Current

Image

Lithium cells cannot safely accept the same current at all temperatures. Charging an LFP cell below 0°C causes lithium plating, a permanent and dangerous degradation, and both charging and discharging must be reduced or stopped at high temperature. Most BMS only offer an ON/OFF protection (charge allowed or blocked at a fixed threshold), which either cuts the charge completely or lets full current flow into a cold battery.

Auto Temp-Based Current fills this gap : it continuously adjusts the maximum charge and discharge current according to the battery temperature, following two configurable temperature/C-Rate tables.

This function can be disabled via the "Temperature-based current limitation" switch.

How it works

YamBMS monitors the temperature sensors of all connected BMS and uses the coldest/hottest values to look up the allowed C-Rate in the tables below. The resulting factor is applied to the battery capacity (Ah), not to the maximum charge/discharge current :

Example : 280 Ah battery at 20°C with a rate of 0.5 → 280 x 0.5 = 140 A

The resulting limit is one of the values used to calculate the final CCL/DCL : the current requested by YamBMS is always the lowest of all active limits (see Max Requested Current). When this function is the one limiting the current, it is displayed by the CCL/DCL derating reason sensor.

Configuration

The two tables are defined in the substitutions of your YAML. Each line is a pair { temperature °C, C-Rate } with a rate from 0.0 (current blocked) to 1.0 (1C).

# +-------------------------------------------------------------------------
# | Temperature-based current limitation
# | Can be disabled via the switch "Temperature-based current limitation"
# | This factor is applied to the battery capacity (Ah), not the current
# | maximum charge/discharge current. For example : 280Ah x 0.5 = 140A
# +-------------------------------------------------------------------------
# Temperature °C -> Charge Rate (0.0C to 1.0C)
yambms_charging_rate_table: |
  {
    { -0.1, 0.00 },
    {  0.0, 0.05 },
    {  5.0, 0.12 },
    { 10.0, 0.30 },
    { 20.0, 0.50 },
    { 25.0, 0.50 },
    { 45.0, 0.50 },
    { 50.0, 0.50 },
    { 55.0, 0.50 },
    { 60.0, 0.00 }
  }
# Temperature °C -> Discharge Rate (0.0C to 1.0C)
yambms_discharging_rate_table: |
  {
    {-30.0, 0.00 },
    {-20.0, 0.50 },
    {-10.0, 0.50 },
    { -5.0, 0.50 },
    {  0.0, 0.50 },
    {  5.0, 0.50 },
    { 45.0, 0.50 },
    { 50.0, 0.50 },
    { 55.0, 0.50 },
    { 60.0, 0.00 }
  }

Default values explained

The default tables are designed for LFP cells and follow the typical manufacturer recommendations :

Charge : no charge below freezing (-0.1°C -> 0.00), then a progressive ramp as the battery warms up — a trickle at 0°C (0.05C), increasing through 5°C and 10°C, reaching the nominal 0.5C at 20°C. The rate stays at 0.5C up to 55°C and charging stops at 60°C. The low-temperature ramp is deliberately conservative : charging a cold battery at reduced current also warms it up, which progressively unlocks higher rates.

Discharge : LFP cells tolerate discharge at much lower temperatures than charge, so the default allows 0.5C from -20°C up to 55°C, with a cut-off below -30°C and above 60°C.

Customizing the tables

  • Adjust the plateau value if your cells are rated differently (e.g. 0.3C for a high-capacity storage cell, 1.0C for power cells)
  • If your battery has a self-heating function or is installed in a heated enclosure, the low-temperature charge ramp can be relaxed
  • Keep the 0.00 end points : they act as hard cut-offs at the temperature extremes and are your last software protection before the BMS protections trip

Auto CVL

Image

Important

In Bulk, the Auto CVL function uses the Balance Trig. Volt. value of your BMS. e.g. for LFP : BTG=0.010V

Note

Auto CVL was reworked in YamBMS 1.8.0 by @Sleeper85, see release note.

When enabled, the Automatic Charge Voltage Limit function automatically reduces the Requested Charge Voltage (CVL) sent to the inverter when a cell starts to exceed the Bulk Voltage target. The runner cell is maintained at or near that target, the balancer can start to bring up the lagging cells, and the runner cell never climbs to the OVP threshold.

Auto CVL tracks the highest cell (max_cell_v) against the Bulk Voltage target, with the BMS Balance Trig. Volt. as deadband, and floors at the chemistry's Min Charge V. (the cv_min "fully charged at rest" value).

Think of charging as filling a tank with water : the voltage is the pressure pushing the water in, the current is the flow. Where Auto CCL is a valve on the pipe, Auto CVL acts directly on the pump pressure. When the pressure inside one compartment of the tank (the runner cell) rises too fast, YamBMS turns the pump down so the source pressure matches what that compartment can accept. With the source pressure lowered, over-pressurizing the compartment becomes physically impossible — no matter how the downstream equipment behaves, there is simply no excess pressure left to push. This is why voltage control is inherently the safest way to terminate a charge, and the preferred option according to Victron and others.

Its effectiveness, however, depends on how well your inverter follows CVL commands. Some inverters regulate their output voltage poorly or slowly (e.g. some Solis models), in which case the pump doesn't respond to the command to turn down — this is where Auto CCL, acting on the valve instead, takes over as a complementary protection.

Boost Charge V. allows you to increase the charging voltage to charge your battery faster : the pump is deliberately set to a higher pressure to fill the tank faster. Auto CVL will then reduce the charging voltage by itself at the end of the charge, so that the runner cell does not exceed the Bulk Voltage target — the pump pressure is automatically brought back down as the tank approaches full.

Auto CCL & DCL

Image

Auto CCL

Important

The Auto CCL function uses the OVP value of your BMS.

The Auto Charge Current Limit function has been introduced to prevent OVP alarms.

When enabled, Auto CCL automatically reduces the Requested Charge Current (CCL) sent to the inverter when a cell starts to exceed the bulk target. This should prevent the runner cell from reaching the max voltage cutoff — it doesn't hold the cell at bulk voltage, but keeps it just below the OVP threshold.

Think of charging as filling a tank with water : the voltage is the pressure pushing the water in, the current is the flow. Auto CCL is a valve on the pipe : when the pressure inside one compartment of the tank (the runner cell) rises too fast, the valve progressively closes to reduce the flow — even if the pump keeps pushing at full pressure. Less water entering means less pressure build-up, and the compartment never reaches the point where the safety relief (OVP) would trip.

Because it acts on the current rather than the voltage, this protection works with any inverter that uses CAN/RS485 control — including those that follow CVL commands poorly. It is the perfect complement to Auto CVL, which acts on the pump pressure itself.

Auto DCL

Important

The Auto DCL function uses the UVP value of your BMS.

The Auto Discharge Current Limit function has been introduced to prevent UVP alarms.

When enabled, Auto DCL automatically reduces the Requested Discharge Current (DCL) sent to the inverter when a cell approaches UVP + 0.2 V. This should prevent the weakest cell from reaching the low voltage cutoff and tripping the BMS protection.

In the water analogy, discharging is draining the tank : the cell voltage is the water level, the discharge current is the outgoing flow. Auto DCL is a valve on the drain : when the level in one compartment (the weakest cell) gets close to the bottom, the valve progressively closes to slow down the outflow. A strong draw on a nearly empty compartment makes its level dip sharply (voltage sag under load) ; reducing the flow lets the level stabilize just above the point where the safety cutoff (UVP) would trip, instead of slamming the system to a hard stop.

Because it acts on the current rather than the voltage, this protection works with any inverter that uses CAN/RS485 control.

Auto Float Voltage

Image

When switching from Bulk to Float, therefore lowering the Requested Charge Voltage (CVL), some inverters (e.g. Deye SUN-12K) will start to discharge the battery (into the grid) with up to max. discharge current until the Requested Charge Voltage (CVL) is reached. The reason behind this is that the inverter sees this as battery overvoltage and wants to counter it. As workaround, by enabling Automatic Float Voltage, it will lower the Requested Charge Voltage (CVL) gradually in small steps until the float voltage is reached, allowing the battery more time to settle down. There are two modes available: Follow and Immediately.

  • Follow: Waits until the battery voltage itself is below the current Requested Charge Voltage (CVL) before lowering Requested Charge Voltage (CVL) further. It follows the battery voltage until the target float voltage is reached.
  • Immediately: Immediately start lowering the Requested Charge Voltage (CVL), independent of the current battery voltage. That means it can go below the current battery voltage.

This feature might not work with all inverters as good or is not required if these do not discharge the battery.

The voltage steps can be configured (default 0.1V) with Auto Float Voltage Step. The update interval can be configured (default 3 minutes) with Auto Float Update Interval.

Auto EOC

Image

When to use: Your battery would be full early in the day and then be idle for the rest of the day. You want to charge it slowly and have it full at a specified time, for example in the evening. Or you charge from the grid at night and want the battery full at the end of the cheap tariff, for example at 06:00.

This function allows to set a charging window when Bulk charging. It limits the Requested Charge Current (CCL) so the battery should reach full charge at the target time. As the algorithm is quite simple there are some requirements for it to work correctly:

  • The time of the ESPHome device must be correct and available.
  • The Battery Capacity must be correct.
  • The charger/inverter can deliver the Requested Charge Current (CCL) during the charging window (sun or grid).

There are some configuration options to adjust the behaviour:

  • Automatic EOC Current: This switch enables or disables the function. When disabled, it will not limit the Requested Charge Current (CCL).
  • Auto EOC Start Hour: This selects the hour at which the charging window starts (default 0).
  • Auto EOC Start Minute: This selects the minute at which the charging window starts (default 0).
  • Auto EOC Target Hour: This selects the hour of the desired target time (0 to 23).
  • Auto EOC Target Minute: This selects the minute of the desired target time.
  • Auto EOC Correction: This increases or decreases the Requested Charge Current (CCL) and allows for correcting charger/inverter differences, for example if the inverter delivers less current than requested.
  • Auto EOC Capacity Modifier: This allows to lower the target capacity for the calculation. If your battery Capacity Remaining does not reach Battery Capacity when 100% full, you can adjust the value here.
  • Auto EOC Increase Stop Hours: When nearing the target time but the charge current can not be reached, the Requested Charge Current (CCL) will increase until it reaches the max. charge current. To avoid this, a time frame bevor the target time can be chosen in which the current will not be increased. E.g. if this option is set to 1 hour, the Requested Charge Current (CCL) is 40A and the time is between Target Hour - 1 hour and Target Hour, it will stay at 40A.
  • Auto EOC Increase Stop SoC: Similar to Auto EOC Increase Stop Hours, this stops increasing the Requested Charge Current (CCL) when the SoC is equal or above the specified SoC. The maximum value is 98% because the Battery SoC is clamped to 98% until end-of-charge (this keeps some inverters from stopping charging when the SoC reaches 100%), so a higher threshold could never be reached before end-of-charge and the stop condition would never trigger.

Charging window: the function is active from the start time to the next target time. The window may cross midnight:

Start Target Window
0:00 (default) 18:00 0:00 to 18:00, daylight charging
22:00 6:00 22:00 to 6:00 the next morning, night charging from the grid
6:00 6:00 Start = target: 24 hours, always active

Outside the window the Requested Charge Current (CCL) is not limited by this function. The times follow the local time of the ESPHome device, including daylight saving time: a 22:00 to 6:00 window lasts 9 hours in the night the clocks go back.

The text sensor Auto EOC Status will show the current status of the function:

  • Stop: Disabled: Function is disabled or capacity not available.
  • Stop: Float: YamBMS currently in Float mode, not Bulk.
  • Stop: Time not valid: The ESPHome device time is not valid.
  • Wait: Starts at hh:mm: The current time is outside the charging window (and the grace period does not apply, see below).
  • Stop: Current above limit: The required charge current is above the current charge limit.
  • Run: Current increase stopped: Running, but no current increase because of Auto EOC Increase Stop Hours or Auto EOC Increase Stop SoC.
  • Run: Working normally.
  • Run: Auto SoC Limit xx%: Enabled, but reduced the target capacity by the value selected for Auto SoC Limit.
  • ... (Grace period): Appended to a Run status when the target time has passed but the grace period is active (see below), e.g. Run (Grace period).

Holding the current: The function never releases the Requested Charge Current (CCL) limit to the maximum while it still has a current to hold, as this would let the current spike back up. The last limited current is held instead in two situations:

  • Grace period: normally the limit would be released as soon as the target time has passed. Instead, as long as there is a current being held, a one hour grace period applies: the function keeps holding the current at its last value for up to one hour past the target time so a battery that has not quite finished charges gently instead of spiking to the maximum. During this period the status is suffixed with (Grace period). The grace period ends one hour after the target time, after which the status changes to Wait: Starts at hh:mm, or to Run if the next charging window has already started. The grace period has priority over a window starting within this hour.
  • Target capacity reached: when the battery has reached the target capacity (Battery Capacity adjusted by Auto EOC Capacity Modifier, and by Auto SoC Limit if active) before the target time, the calculated current would drop to 0A and normally release the limit. Instead the last limited current is held until the charger switches to Float. Note that if the Auto EOC Capacity Modifier targets a capacity below 100%, the function considers the battery "done" at that lower capacity.

The sensor Auto EOC Current will show the calculated charging current. Note that it is filtered by an EWMA filter with a default 3 minute delay. That means that changes to the options or parameters are not immediately visible. This avoids that the Requested Charge Current (CCL) will fluctuate too much. It will show 0A when the function is disabled/stopped or there is no solution.

The function used to calculate the required charging current is very basic. The missing battery capacity (difference between Battery Capacity and Capacity Remaining) divided by the remaining hours. If Auto SoC Limit is active, the configured limit value will be used to calculate the target capacity. It will be updated every minute, but afterwards filtered before it is used for Requested Charge Current (CCL). That means it will adapt, but not take into account any special circumstances. For example if Auto CCL is enabled and required, the charge current may further be limited by Auto CCL. The target time may then not be reached exactly. To account for this, the parameter Auto EOC Correction can be used to increase the overall current a little to compensate for the lower end current.

Here is an example when the target time is set to 18:00. Starting at 00:00, the required current increases as the battery is discharged. When the battery starts charging as the sun is up, the required current stabilizes around 14A. The current is increased at the end as it does not exactly hit its required charge, but at 17:30, the required current is stable because the parameter Auto EOC Increase Stop Hours was set to 0.5 hours, so it will not be increased anymore. At about 18:08 the battery is 100% after a short balancing period.

Image

Auto SoC Limit

Image

When to use: You want to charge your battery up to a specific SoC value.

This function allows to set a target SoC when charging. Upon reaching this limit, it can either switch to Float, limit the Requested Charge Current (CCL) or both.

There are some configuration options to adjust the behaviour:

  • Automatic SoC Limit: This switch enables or disables the function.
  • Auto SoC Limit: The SoC limit value.
  • Auto SoC Limit Mode: The mode to use when the limit is reached.
  • Auto SoC Hysteresis: Configurable hysteresis value when to stop limiting Requested Charge Current (CCL).
  • Auto SoC Limit CCL: The value that will be used for Requested Charge Current (CCL) when the limit is reached and Auto SoC Limit is set to CCL or Float + CCL.

The text sensor Auto SoC Limit Status will show the current status of the function:

  • Stop: Disabled: Function is disabled.
  • Stop: Force Bulk active: The Force Bulk switch is enabled, this function will not be enabled
  • Stop: Rebulk Days active: Rebulk Days is > 0 and last full charge was longer ago than the specified number of days, this function will not be enabled.
  • Stop: Not in Bulk/Float: Charging status is not Bulk or Float, this function will not be enabled during Cut-Off or Balancing.
  • Stop: SoC limit reached: The configured SoC limit was reached.
  • Wait: Reactivating at xx%: The configured SoC limit was reached, now it waits until the SoC goes down to Auto SoC Limit - Auto SoC Hysteresis.
  • Run: Function enabled, SoC limit not reached.

Modes:

  • Float: Will set the charging mode from Bulk to Float. If already at Float, nothing will happen.
  • CCL: Limits the Requested Charge Current (CCL) to the value set by Auto SoC Limit CCL. The limit will be removed once the SoC is below Auto SoC Limit - Auto SoC Hysteresis.
  • Float + CCL: Will use both previously described methods. However while the Requested Charge Current (CCL) will be removed, the charging mode will not be reset to Bulk. For this, Rebulk SoC is available.

Note: Some inverters may not like 0A for Requested Charge Current (CCL). Auto SoC Limit CCL allows to set a small value to effectively limit the charging process.

Example:

  • Auto SoC Limit is set to 80%
  • Auto SoC Limit Mode is set to CCL
  • Auto SoC Hysteresis is set to 5%

The current SoC is 70%. When it reaches 80% during charging, Requested Charge Current (CCL) is set to Auto SoC Limit CCL. Afterwards the battery is then discharged, however Requested Charge Current (CCL) will stay at Auto SoC Limit CCL until SoC reaches Auto SoC Limit - Auto SoC Hysteresis = 80% - 5% = 75%. Without this, the SoC would oscillate between 79% and 80%, stressing components unnecessary.

Auto CCL Current Taper

Optional Auto CCL package (yambms_auto_ccl_current_taper.yaml).

1. Reach Bulk cleanly
Your inverter may stop short of or overshoot the configured Bulk voltage. Current Taper reduces Requested Charge Current (CCL) along a knee→bulk curve so the pack reaches bulk more cleanly.

2. Hold at Bulk for balancing
At first bulk touch, CCL drops to Balance Current (e.g. 2A–3A) and stays there while the session is active, so absorption is not allowed to race to zero and cut the balance window short. Absorption is moved ahead of Bulk (the knee→bulk curve) so enough amp-hours remain when Bulk is hit for a low-current balance hold.

The sweet spot is to charge hard enough that the pack is not yet full when Bulk is reached, but not so hard that it never gets fully charged at Balance Current. That takes some experimentation; a stable curve makes the result more repeatable day to day.

This package participates in the Auto CCL STEP pipeline and writes var_auto_ccl_current_taper (its own dedicated CCL slot). From the knee voltage to Bulk voltage, CCL is reduced along a curve from a starting C-rate to an ending C-rate (both × Battery Capacity). Knee Voltage min/max are set at boot from cell count × chemistry (same pattern as Bulk voltage); the 16S LFP placeholder default is 54.4V.

By default the taper is linear with pack voltage. Optional YAML substitution auto_ccl_ct_curve_exp (default 1.0) shapes the knee→bulk curve: >1 drops faster early then longer tail; <1 delays the taper then sharpens near bulk. Override at package include — compile-time only, no HA entity.

Important

Unlike Auto CCL (max cell vs BMS OVP), Current Taper uses pack voltage vs a user knee and YamBMS Bulk voltage.

Behaviour:

  1. Below Knee Voltage: inactive — CCL unchanged (auto_ccl_current_taper = 0).
  2. At knee (active): CCL follows the curve from Knee C-Rate × Battery Capacity down to Bulk C-Rate × Battery Capacity.
  3. At first bulk touch, or if EOC occurs earlier: CCL drops to Balance Current (default 2A) and stays there while the session is active.
  4. Session ends when pack voltage falls 0.2V below the knee (hysteresis), then the curve can start again on the next charge.

Configuration options (entities card names):

  • Current Taper: Enables or disables the function.
  • Knee Voltage: Pack voltage where tapering starts.
  • Knee C-Rate: C-rate at the knee; × Battery Capacity for the starting CCL.
  • Knee Amps: Capacity × Knee C-Rate (read-only).
  • Bulk C-Rate: C-rate at bulk.
  • Bulk Amps: Capacity × Bulk C-Rate (read-only).
  • Balance Current: CCL while latched at bulk or after EOC (default 2A). Keep this above 0.005C × Battery Capacity (the Cut-Off current deadband) so the classic compensated Cut-Off path stays available; at or below that band, charge completion relies on the fully charged at rest signature only.

Other diagnostic sensors:

  • Auto CCL CT Voltage: Smoothed pack voltage used by the curve. This minimizes how much CCL jumps around with changes in voltage.
  • Auto CCL CT Delta: Pipeline CCL reduction applied (≤ 0A).

Notes:

  • Requires a correct Battery Capacity.
  • Writes its own var_auto_ccl_current_taper slot.
  • Can run alongside other Auto CCL functions; the pipeline takes the most restrictive reduction.
  • If you taper toward near zero, you may also need a higher cut-off voltage or a longer cut-off timer to avoid an early Cut-Off.
  • Pair with Charger Offset V. when the inverter undershoots bulk.

Inverter Heartbeat Monitoring

Image

This feature allows you to monitor the heartbeat of your inverter (time between two ACK 0x305). This is useful for troubleshooting purposes and should not remain enabled continuously.

This heartbeat must be regular and depends on the selected CAN protocol and the behavior of the inverter. If the heartbeat is not regular this can show a problem on the inverter side or an overloaded ESP32.

The Deye inverter sends an ACK 0x305 in response to the reception of a CAN frame 0x356. Knowing that CAN frames are sent every 100ms and that the CAN protocol PYLON V1 has 6 CAN frames, the heartbeat of the Deye inverter is 600ms.

Important

Every 2h Deye takes more than 3s to respond and more than 5s at midnight. This is what the CANBUS Status looks like when the canbus_link_timer is set to 3s.

Image

Diagnostic

Useful information for troubleshooting.

Image Image