admin/goodwe-addon
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

SAFETY-32: bms_soc_floor per pack, rule 8 per unit

Browse Source 
`bms_soc_floor` describes A BATTERY, not a site. At two packs of different
models the cut-outs differ, and one number for both graded the shallower pack
against the deeper one's BMS - so a site with cut-outs of 10 % and 30 % under
`peak_soc_floor: 20` STARTED, and the guard would command a forced discharge
that pack B's BMS, not the operator's floor, is the thing that stops. That is
rule 8's own failure mode, reached through rule 8.

Scoped to the card's third bullet, per its PM PROOFREAD: the aggregate
anti-windup (DEV-02) and per-instance `achievable_w` (CFG-04) were verified as
already shipped and are untouched.

* config.yaml: `bms_soc_floor: int(0,50)` REQUIRED per `inverters:` entry.
  Nothing is inherited; the flat key stays the single-inverter shape's own
  cut-out. A per-entry DEFAULT was declined - a default is one number for every
  pack, which is this card's defect - and the decision is recorded.
* inverter.py: `Inverter.bms_soc_floor`; an entry that states none gets None,
  not a borrowed number and not 0.0 (the most permissive value the key has).
* peakguard.py: `Pack`, `pack_floor_pct()`, `pack_permissions()`,
  `binding_soc_floor()`. `discharge_permitted()` is unchanged and is still the
  one place the question is answered.
* validate.py: `unit_bms_floors_indexed()` carries the ROSTER index; rule 8
  grades EVERY unit and NAMES the one it refuses. Graded with the offender
  SECOND and with the same two numbers in the other order.
* main.py: `Controller.packs`; `decide(soc_floor=...)` is the per-pack
  reduction of the same option; the floor-limited notification names the pack
  that stopped the site. `pack_floor_soc` - the emptiest pack, and its
  None-on-missing behaviour - is untouched.
* tools/supervisor_shape_probe.py: RE-RUN and repaired. The required key broke
  §C and left §D printing PASS on a refusal about a different key. §D is now an
  isolated counterfactual over an accepted merged baseline, one key varied,
  asserting the key name. `all cases passed` on 2026.08.0.

Stated rather than hidden: under any config rule 8 accepts the per-pack FLOOR
reduces to `peak_soc_floor` for every pack. The reduction is written for
`unit_caps_indexed()`'s reason and graded on both sides - 1775 rule-8-valid
pairs answer the option, the pair rule 8 refuses answers the cut-out.
`peak_soc_floor` is still one number for the site, so the "deeper pack
needlessly withheld" half is filed as an open question, not closed.

Full 19-file suite green. Twelve source mutations through
tools/mutation_run.sh: eleven red, one argued survivor. The battery also found
`_flat_bms_floor()` defaulting in two places, each covering for the other.

No measurement of inverter B appears anywhere: it does not exist yet. Every
second-pack figure is simulated and labelled.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU
This commit is contained in:
admin
2026-09-05 03:01:57 +02:00
committed by glenn schrooyen
co-authored by Claude Opus 5
parent 67e649ad6b
commit f9e7fbf86d
12 changed files with 1193 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
goodwe_controller/app/inverter.py
+80 -5
View File
@@ -15,6 +15,11 @@ The scalars, and what each one was silently asserting:
SAFETY-24's pack floor and arbitrage's bounds. An
average lets the emptier pack be driven below its own
floor; a maximum parks the fuller one.
`bms_soc_floor` SAFETY-32. ONE cut-out percent for every pack, and it
describes A BATTERY. Two packs of different models
have different cut-outs, so the flat key graded the
shallower pack against the deeper one's BMS - wrong
in the direction that empties a pack.
`batt` ONE battery power into the anti-windup saturation
detector - see the SITE/UNIT note at the bottom of
this docstring, because this one goes the OTHER WAY.
@@ -117,6 +122,12 @@ import math
from datetime import datetime
from .clamp import ClampResult
# CFG-03's ONE in-code mirror of config.yaml's SAFETY-24 defaults. Imported
# rather than retyped: the flat-keys path below needs `bms_soc_floor`'s
# shipped default and a literal here would be the fourth defaults site that
# ticket exists to prevent. peakguard imports arbiter/control/tariff and none
# of those imports this module, so the direction is one-way.
from .peakguard import PEAK_OPTION_DEFAULTS
from .store import unit_key
from .watchdog import SignWatchdog, SignWatchdogConfig
@@ -170,7 +181,7 @@ class Inverter:
def __init__(self, name, *, setpoint_entity="", soc_entity="",
batt_entity="", batt_invert=False, max_w=2000.0,
store=None, sign_cfg=None):
bms_soc_floor=None, store=None, sign_cfg=None):
self.name = str(name)
self.setpoint_entity = str(setpoint_entity or "")
self.soc_entity = str(soc_entity or "")
@@ -179,6 +190,19 @@ class Inverter:
# The supervised cap on what may be written to THIS setpoint entity.
# See the module docstring on why this is a number and not a `Tuning`.
self.max_w = float(max_w)
# SAFETY-32. THIS PACK'S OWN BMS CUT-OUT, in percent, or None when the
# roster entry did not state one.
#
# ⚠️ NOT DEFAULTED HERE, AND None RATHER THAN A NUMBER. A cut-out is a
# property of the battery in the cupboard; inventing one for a pack that
# did not state it is precisely this card's defect - a pack graded
# against a floor that belongs to a different battery - rebuilt in the
# constructor. `peakguard.pack_floor_pct()` treats None as an unknown
# floor and `discharge_permitted()` treats an unknown floor as NO
# permission, so the absence costs a shave; validate.py rule 8 refuses
# the config by name long before that, at startup.
self.bms_soc_floor = (None if bms_soc_floor is None
else float(bms_soc_floor))
# --- the device's own reported range, read from its own entity -------
# None until `hass.limits()` has answered. NOT guessed at: ESPHome is
@@ -339,8 +363,9 @@ def build_roster(opts: dict, store, sign_cfg=None) -> list:
TWO SHAPES, AND WHICH ONE IS IN FORCE IS DECIDED BY ONE TEST: is
`inverters:` empty?
EMPTY the five flat keys - `setpoint_entity`, `soc_entity`,
`batt_entity`, `batt_invert`, `max_w` - describe the ONE inverter,
EMPTY the six flat keys - `setpoint_entity`, `soc_entity`,
`batt_entity`, `batt_invert`, `max_w`, `bms_soc_floor` (SAFETY-32)
- describe the ONE inverter,
exactly as the shipped scalars did. This is what every install
that upgrades into this version reads, without an operator
touching anything, and it is byte-identical to what DEV-02
@@ -353,8 +378,8 @@ def build_roster(opts: dict, store, sign_cfg=None) -> list:
`soc_entity` has no SoC sensor; it does NOT borrow the flat one,
because "this unit's number came from somewhere else" is the
defect DEV-02 spent a card removing and a fallback here would
rebuild it in three lines. `name`, `setpoint_entity` and `max_w`
are required of every entry - the schema enforces it on the
rebuild it in three lines. `name`, `setpoint_entity`, `max_w` and
`bms_soc_floor` (SAFETY-32) are required of every entry - the schema enforces it on the
Supervisor path, `validate.py` rule 9 enforces it for sim/inject.py
and the checks, which reach this function with any dict at all.
@@ -380,6 +405,12 @@ def build_roster(opts: dict, store, sign_cfg=None) -> list:
batt_entity=opts.get("batt_entity", ""),
batt_invert=bool(opts.get("batt_invert")),
max_w=float(opts.get("max_w", 2000)),
# SAFETY-32. THE FLAT KEY, because this IS the single-inverter shape
# - the one pack the flat options describe is the one pack whose
# cut-out `bms_soc_floor` states. Defaulted from CFG-03's single
# mirror exactly as validate.py rule 8 defaults it, so an install
# that never set the key reads the same 10 % in both places.
bms_soc_floor=_flat_bms_floor(opts),
store=store, sign_cfg=sign_cfg)]
roster = []
@@ -401,10 +432,54 @@ def build_roster(opts: dict, store, sign_cfg=None) -> list:
# ⚠️ NOT `opts["max_w"]`. See the docstring: a rating an entry did
# not state is not the flat one, it is a rating rule 9 refuses.
max_w=_entry_max_w(entry),
# ⚠️ NOT `opts["bms_soc_floor"]`, FOR `max_w`'S REASON AND THIS
# CARD'S. An entry that omits its cut-out has NOT got the flat one;
# it has none, and rule 8 refuses it by name. Borrowing here would be
# SAFETY-32's own defect written in three lines - the shallower pack
# graded against the deeper pack's BMS.
bms_soc_floor=_entry_bms_floor(entry),
store=store, sign_cfg=sign_cfg))
return roster
def _flat_bms_floor(opts: dict):
"""The single-inverter shape's own cut-out, or None if it is unparseable.
Defaulted from `PEAK_OPTION_DEFAULTS` when the key is absent or blank, which
is `validate._number()`'s behaviour on the same key - the two have to agree
or the validator would grade a number the roster does not build.
"""
# ⚠️ ONE defaulting line, not two. The first cut wrote the fallback into the
# `.get()` AND into the blank test below it, and a mutation that deleted
# either one survived - each was covering for the other, which is
# MUTATION.md's masking section in three lines of configuration reading.
raw = opts.get("bms_soc_floor")
if raw is None or raw == "":
return float(PEAK_OPTION_DEFAULTS["bms_soc_floor"])
try:
return float(raw)
except (TypeError, ValueError):
return None
def _entry_bms_floor(entry: dict):
"""One entry's OWN cut-out, or None when it did not state a usable one.
None rather than a borrowed number and rather than 0.0 - `_entry_max_w()`
can answer 0.0 because a zero rating commands nothing, but a zero FLOOR is
the most permissive value the key has and would read as "this pack may be
emptied". Rule 8 refuses the missing key by name; until it does, None
withholds.
"""
raw = entry.get("bms_soc_floor")
if raw is None or raw == "":
return None
try:
return float(raw)
except (TypeError, ValueError):
return None
def _entry_max_w(entry: dict) -> float:
"""One entry's supervised cap, or 0.0 when it did not state a usable one.