goodwe-addon/goodwe_controller/DECISIONS/SAFETY-85-no-false-not-keeping-up.md

SAFETY-85 - no false "not keeping up" while another owner sets the battery

Status: implemented 2026-10-01, for review. Tests: test_safety85.py.

The defect. "Battery is not keeping up" (SAFETY-40, goodwe_integrator_bound) fired about every 2.5 min during maintenance (drain, charge, HOLD) and under the peak guard, while the battery gave exactly what it was told. Each warning re-created the HA notification. Rig counts: 24 in an hour (SAFETY-83 F1), 43 in 7 episodes (SAFETY-86), 35 in 16 (SAFETY-87), 12 in 6 (SAFETY-84). The page counter counted cycles (861), not episodes.

Cause, measured on the real Controller.

• N=1: when a higher claim decides, cycle() re-seeds the integrator from the target each cycle, then compute() adds gain * error for a grid error the loop does not own. Target + kick crosses the rail and sets i_clamped. The carried integrator is not wound (SAFETY-48 caps the lead at one slew step), so control comes back one slew step at a time.
• N>=2: a maintenance pin is a unit claim. The loop stays the site winner and winds to its rail for watts the pinned battery may not give. When the pin lifts, the site jumps: 2500 W in one cycle when a HOLD ends under a 4500 W house, 1390 W when a charge pin lifts (s84 n2_charge_dear, t=1800 s).

Decision. Three rules; the alarm, its text and its id are unchanged.

1. The loop's clamp counts only on a cycle the loop decided. The winner is the loop. Its number is on the wire, or only a rating (device, supervised) cut it. No bound held it, and nothing was unmet. (Controller._loop_alarm_input.)
2. A battery another owner set to discharge alarms when it gives less than it was told. This covers every battery on a cycle the loop did not decide, and a battery with its own pin otherwise. The test is more than saturation_w short of the least it stood at over SHORT_CYCLES cycles and SHORT_SPAN_S (the plant's measured settle, SAFETY-13/73), for saturation_cycles cycles in a row (clamp.delivery_short). It covers a real shortfall during maintenance or under the peak guard. Before, that shortfall was silent unless the kick happened to reach the rail (house 1000 W, drain 2000 W, battery gives nothing: 0 warnings before, 4 in 10 min now).
3. At N>=2, while maintenance holds a battery, the loop is bounded by OPT-11's loop_bound() (what the batteries may place). It does not wind, and control comes back one slew step a cycle. Why maintenance only: that is where the jump was measured and where the owner order puts maintenance above the loop. Other N>=2 limits (pack cut-out, SAFETY-73 refusal) keep the old law. Rule 1 still silences them (the target is unmet), so they no longer warn either.

Fixing the windup was chosen over only ignoring the wound part, because at N>=2 the wound integrator moves real watts at hand-back. At N=1 there was nothing to fix: re-seeding already prevents windup.

What SAFETY-03/40 protect is kept. With the loop in charge, the integrator bound still warns (a runaway, a house above the rating), and a saturated inverter under the loop's own command still does not alarm (SAFETY-03 AC 2): rule 2 grades only batteries another owner set.

The counter. ClampWatchdog.bound_episodes counts episodes that had a bound engagement. The status row shows it ("N times since start"). bound (cycles) stays for the log and the tests.

Re-pinned digests. Every change is intended; nothing at N=1 moves a watt.

digest	what changed
s78 n1_drain_owner	the false clamp rows are gone from the log; commands identical
s78 n2_drain, s84 n2_charge, n2_charge_banked, s79 n2_maint (test_peak_margin)	loop reason (mode-bound), integrator and loop claim while bounded; commands identical
opt11 n2_maint (test_modes)	A drops out at t=1655 s: B follows the house at once, 8 cycles differ (max 920 W)
s84 n2_charge_dear	A's pin lifts at t=1800 s: 400 W a cycle, not a 1390 W jump; the surplus step after it; 98 cycles

test_safety86's "without the ceiling the log floods" now needs the ceiling and the bound both removed: either one alone keeps the loop inside what the batteries can give. The alarmed() helpers in test_safety84/86 also read SAFETY-81's quarter stamp, because ALLOCATOR rows can push its row out of the 40-row log.

Review (PR #163). The first draft graded each battery against last cycle's command and graded charges too. On plantsim's battery (10 s lag) at the live 2 s meter, every drain or charge start warned once, and an N=2 drain or HOLD under the peak guard with a stepping house warned 15 times an hour. A maintenance charge tapering near full warned 11 times in 50 min, which SAFETY-42 section 7 had ruled out. With the settle window and discharge only: 0 in all of those cases. A battery that gives nothing still warns, lagging or not. At a hypothetical 20 s lag, it warns at most twice an hour. The cost: a battery that does not take a charge another owner set is not named by this alarm (the same gap SAFETY-42 states; the charge has its 36 h timeout). test_safety85.py part 7.

Not changed, open for the owner.

• With the loop in charge and the house above the batteries' total rating, it still warns (SAFETY-40). On the rig's 2 x 2000 W N=2, most of SAFETY-84's count came from houses of 4500 and 6500 W.
• TEL-10's Loop reason reads mode-bound while the maintenance bound holds the loop, with modes off. DOCS lists the value with both meanings.