Docs: The CCL/DCL divider counts declared links
Document that every declared CAN or RS485 inverter link divides the requested CCL/DCL, including a link whose protocol is `Disabled` or left on `Automatic` with no brand, and that only links actually wired to an inverter should be declared. Design_decisions.md records why the divider must not be restricted to active links: a disabled link usually still has an inverter drawing from the bank, an unconfigured link is the state every link starts in after 1.8.0, and a lost link must never raise the current sent to the remaining inverters. YamBMS_functions.md: fix the RS485 package name (`yambms_rs485.yaml`).
This commit is contained in:
1 parent
00e04df04b
commit
cb9638653d
2 files changed
+37
-3
No files matched your search
@@ -132,17 +132,22 @@ The final CCL/DCL sent to the inverter is always the **lowest** value among all
|
||||
|
||||
`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 interfaces** :
|
||||
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_pylon.yaml` package increments an interface 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.
|
||||
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, the total current drawn from the battery will be lower than the calculated limit — never higher.
|
||||
> 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
|
||||
|
||||
|
||||
@@ -384,6 +384,35 @@ This is why the Schneider XW Pro extended ACK needs no configuration, and why th
|
||||
`canbus_extended_ack` substitution was removed. Both triggers call the same script so the handler
|
||||
is not duplicated.
|
||||
|
||||
## The CCL/DCL divider counts declared links, not active ones
|
||||
|
||||
**Files:** `packages/yambms/yambms_core.yaml`, `packages/yambms/yambms_canbus.yaml`,
|
||||
`packages/yambms/yambms_rs485.yaml`
|
||||
|
||||
Each inverter link increments `yambms${yambms_id}_var_comm_interfaces_count` once, in its
|
||||
`on_boot` at priority `-100`, and the requested CCL and DCL are divided by that counter. The
|
||||
counter never goes down. A link whose `Protocol` is `Disabled`, a link left on `Automatic` with no
|
||||
brand, and a link whose inverter stopped answering all keep dividing.
|
||||
|
||||
Do not make it count only the active links. In every case where a declared link is not active, the
|
||||
inverter behind it may still be drawing from the bank:
|
||||
|
||||
- `Disabled` is meant to cut a link temporarily. The inverter is usually still connected to the
|
||||
bank and running on its own settings, and the share the others are not given is the margin it
|
||||
uses.
|
||||
- `Automatic` with no brand is an unfinished configuration, and every link starts there after the
|
||||
1.8.0 breaking change. Excluding it would hand the full current to the first link configured.
|
||||
- A lost link must never raise the current, or a transient communication loss would double the
|
||||
limit sent to the remaining inverters.
|
||||
|
||||
A link that is not wired to anything has no business in the YAML, so the divider is changed by
|
||||
changing what is declared. This is why `YamBMS_Local_Packages_example.yaml` ships its RS485 link
|
||||
commented out, like the Remote Packages template.
|
||||
|
||||
If this is ever revisited, count the excluded links and subtract them, never count the active ones.
|
||||
A mask of active links is empty until the resolution script has run, which gives a divider of `1`
|
||||
and the full current; a mask of excluded links defaults to the declared count.
|
||||
|
||||
## A UART is declared by the package that consumes it
|
||||
|
||||
**Files:** `packages/board/board_options_itf_uart_*.yaml`, every package taking a `*_uart_id`
|
||||
|
||||
Reference in new issue
Block a user