admin/goodwe-addon
1
0
Fork 0
Code Issues Pull Requests 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/validate.py
+81 -21
View File
@@ -132,7 +132,7 @@ NOT READY banner already names the problem, (b) does not apply.
installed base is on a fixed or static tariff. Refusing to start without a
price feed would lock those sites out of the add-on entirely.
8. `peak_soc_floor` at or below `bms_soc_floor`. [(a)]
8. `peak_soc_floor` at or below `bms_soc_floor`, ON ANY UNIT. [(a)]
SAFETY-24, and the same shape as 1, 4, 5 and 6. The peak guard can COMMAND
a discharge to hold a billed quarter down (SAFETY-07), and `peak_soc_floor`
is the EMS-side bound on how far down it may take the pack. The BMS has its
@@ -142,6 +142,12 @@ NOT READY banner already names the problem, (b) does not apply.
of binding while its status page reports one - rule 5's "a disarmed guard
that advertises itself as armed", on the guard whose failure mode is a pack
that is quietly never available when it is wanted.
⚠️ SAFETY-32: `bms_soc_floor` DESCRIBES A BATTERY, so at a roster it is a
per-entry key and this rule grades EVERY unit and NAMES the one it refuses.
One number for two packs of different models refuses the wrong config and
accepts the wrong one - cut-outs of 10 % and 30 % under `peak_soc_floor: 20`
used to start. A missing per-entry cut-out is refused here rather than
defaulted: a cut-out invented for a pack IS this defect.
⚠️ `<=`, NOT `<`, and the equality case is the interesting one. At exactly
equal, the EMS floor and the pack's cut-out act at the same percent, so the
@@ -386,6 +392,49 @@ def unit_caps_indexed(opts: dict) -> list[tuple[int, float]]:
return caps
def unit_bms_floors_indexed(opts: dict) -> list[tuple[int, object, object]]:
"""SAFETY-32. Each pack's OWN `bms_soc_floor`, carrying its ROSTER INDEX.
`(roster index, the raw value as configured, the parsed float or None)`, one
triple per unit. The raw value travels too because the refusal quotes what
the operator actually wrote, and `!r` of a re-read `opts` key is the wrong
string the moment the value came off a roster entry.
⚠️ THE INDEX IS THE ROSTER'S, NOT THIS LIST'S, AND THAT IS CFG-04'S BUG
WRITTEN DOWN. Rules 5 and 6 fed a CAPS-list index into `_unit_label()`,
which indexes the ROSTER, so on a roster whose first entry was malformed the
refusal named the WRONG INVERTER - an operator sent to the wrong device by
the very message that exists to stop that. `unit_caps_indexed()` exists
because of it. This function goes one step further and SKIPS NOTHING: every
entry produces a triple, including the ones with no usable floor, because a
missing cut-out is itself what rule 8 has to refuse BY NAME. There is
therefore no second list for an index to desynchronise from.
⚠️ AND NOTHING IS INHERITED. At a declared roster the FLAT `bms_soc_floor` is
not read at all - CFG-04's rule, and this card's subject: a pack that borrows
a sibling's cut-out is graded against a battery it is not. At the flat shape
the flat key IS this one pack's cut-out, defaulted from CFG-03's single
mirror exactly as `inverter._flat_bms_floor()` defaults it.
"""
entries = roster_entries(opts)
if not entries:
return [(0, opts.get("bms_soc_floor"),
_number(opts, "bms_soc_floor",
PEAK_OPTION_DEFAULTS["bms_soc_floor"]))]
out: list[tuple[int, object, object]] = []
for index, entry in enumerate(entries):
if not isinstance(entry, dict):
# Rule 9(a)/(b) already refuses a non-dict entry by index, and it
# runs FIRST. Naming it twice would hand the operator two sentences
# about one line of YAML.
continue
raw = entry.get("bms_soc_floor")
out.append((index, raw,
None if raw is None or raw == ""
else _number(entry, "bms_soc_floor", None)))
return out
def _unit_label(opts: dict, index: int) -> str:
""""" at a single-inverter config, " (inverter-b)" at a roster.
@@ -871,28 +920,39 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
# in-code mirror, pinned to config.yaml by test_peakguard.py, and main.py
# reads the same one - exactly as maintenance.MAINT_OPTION_DEFAULTS now is
# for the `maintenance_*` family.
#
# ⚠️ SAFETY-32 - GRADED ONCE PER UNIT, AND THE REFUSAL NAMES THE UNIT. One
# `bms_soc_floor` for two packs compares the EMS floor against whichever
# battery happened to be written into the flat key: a site with cut-outs of
# 10 % and 30 % and `peak_soc_floor: 20` STARTED, and the guard would then
# command a forced discharge that the second pack's BMS - not the operator's
# floor - is the thing that stops. That is the disarmed-backstop state this
# rule exists to refuse, reached through the rule itself. So the loop is over
# units, and `_unit_label()` is fed the ROSTER index the value came off (see
# `unit_bms_floors_indexed()`), because CFG-04 has just fixed the version of
# this that named the wrong inverter.
soc_floor = _number(opts, "peak_soc_floor",
PEAK_OPTION_DEFAULTS["peak_soc_floor"])
bms_floor = _number(opts, "bms_soc_floor",
PEAK_OPTION_DEFAULTS["bms_soc_floor"])
if soc_floor is None or bms_floor is None:
problems.append(
"peak_soc_floor and bms_soc_floor must both be numbers (got "
f"{opts.get('peak_soc_floor')!r} / {opts.get('bms_soc_floor')!r})")
elif soc_floor <= bms_floor:
problems.append(
f"peak_soc_floor is {soc_floor:.0f} % but the pack's own cut-out "
f"(bms_soc_floor) is {bms_floor:.0f} %, so SAFETY-07's forced "
"discharge has no EMS-side bound at all - THE BMS WINS, and it is "
"the pack's protection rather than yours. The guard would report a "
"SoC floor on its status page while being incapable of ever being "
"the thing that stops the discharge, and the symptom of that is a "
"battery repeatedly sitting at the BMS limit with no record of why "
f"- which looks exactly like the SoC drift the maintenance cycle "
f"exists to correct. Raise peak_soc_floor above {bms_floor:.0f} % "
f"(the shipped default is "
f"{PEAK_OPTION_DEFAULTS['peak_soc_floor']:.0f} %), or correct "
"bms_soc_floor if it does not match this pack.")
for _ix, _raw, bms_floor in unit_bms_floors_indexed(opts):
where = _unit_label(opts, _ix)
if soc_floor is None or bms_floor is None:
problems.append(
f"peak_soc_floor and bms_soc_floor{where} must both be numbers "
f"(got {opts.get('peak_soc_floor')!r} / {_raw!r})")
elif soc_floor <= bms_floor:
problems.append(
f"peak_soc_floor is {soc_floor:.0f} % but the pack's own cut-out "
f"(bms_soc_floor{where}) is {bms_floor:.0f} %, so SAFETY-07's forced "
"discharge has no EMS-side bound at all - THE BMS WINS, and it is "
"the pack's protection rather than yours. The guard would report a "
"SoC floor on its status page while being incapable of ever being "
"the thing that stops the discharge, and the symptom of that is a "
"battery repeatedly sitting at the BMS limit with no record of why "
f"- which looks exactly like the SoC drift the maintenance cycle "
f"exists to correct. Raise peak_soc_floor above {bms_floor:.0f} % "
f"(the shipped default is "
f"{PEAK_OPTION_DEFAULTS['peak_soc_floor']:.0f} %), or correct "
f"bms_soc_floor{where} if it does not match this pack.")
# --- warnings: real, but not worth refusing over -------------------------
integ = opts.get("integrator_max_w")