DEPLOY-01: bump version to 0.3.0, changelog for SAFETY-04 and TEL-01

Fixes the version collision noticed while planning DEPLOY-01: release/1.0
still carried version 0.2.1, identical to what is already running on the
live system, so Home Assistant would not have offered the update at all.

- config.yaml: version 0.2.1 -> 0.3.0 (minor: TEL-01 adds a feature,
  SAFETY-04 changes the control law's internals)
- CHANGELOG.md: 0.3.0 entry for SAFETY-04 and TEL-01, in the existing voice

No code under app/ touched, no option defaults changed. Verified:
meter_source: off, integrator_max_w: 0, target_grid_w: -10 all unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Du77usMj8XNKNFZGmUiWDa

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.3.0
+
+**SAFETY-04.** The control law's integrator is now an explicit accumulator,
+bounded independently of the output clamp instead of inheriting whatever
+headroom the clamp happened to leave. It also freezes while the inverter is
+not tracking, rather than continuing to wind up against a command nothing is
+acting on. `integrator_max_w` (default `0`) governs the bound; `0` means
+"follow `max_w`", which is the existing behaviour.
+
+Behaviour is unchanged at the defaults - a 4,928-case equivalence sweep
+against the previous control law confirms it decides identically at
+`integrator_max_w: 0`.
+
+**TEL-01.** P1 meter ingestion, so a Belgian P1's two unsigned registers
+(consumption, injection) no longer need a hand-written signed template
+sensor: the subtraction moves into the add-on, done once and tested. Two
+transports, chosen with the new `meter_source` option: `ha_dsmr` subscribes
+to the DSMR integration over the HA WebSocket, `mqtt_p1` reads a topic.
+Defaults to `off`, which keeps the existing `meter_entity` path untouched -
+nothing changes for an install that does not opt in.
+
+Enabling it publishes `sensor.p1_sample_age_s`: seconds since the newest
+accepted telegram, recomputed against the clock and republished roughly once
+a second rather than only when a telegram lands. That is deliberate - Home
+Assistant only pushes a state on change, so a meter sitting at a genuinely
+constant reading would otherwise look identical to a dead one. Watching the
+age instead means a frozen meter shows a climbing age, not a flat line. The
+firmware watchdog subscribes to this exact entity id.
+
+Known limits, both already in DOCS.md: on `mqtt_p1`, a bridge stuck
+republishing its last telegram still "arrives", so the age cannot detect
+that particular failure - prefer `ha_dsmr` where both are available. And a
+dead P1 meter takes 45 s to reach 0 W commanded (30 s for `meter_max_age_s`
+to call the reading stale, then 15 s of `stale_input_s` on top), which is
+`meter_max_age_s` and `stale_input_s` stacking, not either one alone.
+
 ## 0.2.1
 
 `target_grid_w` (default -10 W): what the meter should rest at. The deadband

goodwe_controller/DOCS.md

@@ -142,12 +142,35 @@ behind it would trip the firmware watchdog on a system that is working fine.
 | `target_grid_w` | -10 | What the meter should rest at. Negative = a slight export |
 | `step_w` | 10 | Quantisation |
 | `saturation_w` | 500 | Divergence that counts as "the inverter is at a limit" |
-| `saturation_cycles` | 3 | How many consecutive cycles before freezing. **Do not set to 1** |
+| `saturation_cycles` | 3 | How many consecutive cycles before freezing. A cycle is one *changed* meter reading, not a fixed period - see the note below. **Do not set to 1** |
 | `integrator_max_w` | 0 | Bound on the loop's accumulator, and 0 means "same as `max_w`". Caps how much stale error can be waiting to unwind when the sign flips. **Do not raise it above `max_w`** - the output clamp already bounds what is commanded, so the only thing extra headroom buys is more cycles of wrong-direction power after every saturation event. Lowering it below `max_w` is the useful direction |
 | `heartbeat_s` | 10 | Refresh interval; must stay well under the firmware watchdog |
 | `stale_input_s` | 15 | How long inputs may be missing before commanding 0 W. In P1 mode this clock starts only *after* `meter_max_age_s` has already expired — the two stack, see "How long a dead meter takes to reach 0 W" |
 | `auto_start` | false | Start controlling on boot (only after commissioning) |
 
+#### Saturation is counted in cycles, not seconds
+
+The specification states the saturation window as **"> 10 s"**. This add-on counts
+**cycles** instead, and that is a deliberate, accepted deviation rather than an
+oversight - the acceptance criterion is not met as literally written.
+
+A cycle here is one *changed* meter reading: the controller only runs the loop when the
+meter value differs from the previous poll. At the reference P1's ~5 s update rate the
+default of 3 cycles is usually around 15 s, but there is **no guaranteed wall-clock
+window** - a meter that repeats the same value stalls the counter for as long as it
+repeats.
+
+Two reasons that is acceptable:
+
+- the control law is a pure function with no clock, which is what makes it testable
+  without hardware, and a seconds-based window would have to live in the controller;
+- a stalled counter is a detection-latency limit and not a runaway risk. The condition
+  that stalls it - an unchanging meter - stops the whole loop, so nothing accumulates
+  while it is stalled.
+
+If a guaranteed window matters on your site, raise `saturation_cycles` for a fast meter,
+and treat the figure as "N meter updates" rather than "N seconds".
+
 #### Why `target_grid_w` is not zero
 
 The deadband is a one-way ratchet: any resting point inside it holds until

goodwe_controller/app/control.py

@@ -156,15 +156,45 @@ def compute(
         # has been in service on real hardware. It is applied here as well
         # because the requirement is that the INTEGRATOR stop accumulating, not
         # only the command.
-        if not frozen:
+        #
+        # ⚠️ EXACTLY ZERO IS ITS OWN CASE, and it must be handled explicitly
+        # rather than falling into one of the two branches. "May not wind
+        # further in the direction it is already pushing" has no referent at
+        # zero: nothing is wound, and neither direction is "further". Writing
+        # this as `if i_w > 0 ... else ...` silently files zero under
+        # rising-only and permanently blocks the first push toward charging -
+        # the same deadlock as the shrink-only encoding above, mirrored in sign,
+        # and reachable because main.py resets i_w to exactly 0.0 on every stop
+        # and every reseed. Measured before the fix: 12 800 of 25 920 frozen
+        # ticks at i_w == 0.0 held the integrator, 8 304 of them changing the
+        # emitted command, worst case abandoning a 2 kW charge into a 4 kW
+        # export.
+        #
+        # Freezing at zero would also be pointless: the freeze exists to stop
+        # accumulation running away, and a first step from zero is bounded by
+        # the gain, the output clamp and the slew limit like any other.
+        if not frozen or i_w == 0.0:
             i_w = moved
+        elif i_w > 0:
+            i_w = min(moved, i_w)
         else:
-            i_w = min(moved, i_w) if i_w > 0 else max(moved, i_w)
+            i_w = max(moved, i_w)
 
     # ⚠️ Applied EVERY cycle, frozen or not: the freeze is conditional, this
     # bound is not. It is what makes the worst-case unwind time finite and
     # knowable instead of a function of how long the error happened to stand.
-    i_w = max(-limit, min(limit, i_w))
+    bounded = max(-limit, min(limit, i_w))
+    if bounded != i_w:
+        # ⚠️ SAFETY-03 (alarm whenever the loop winds into a rail) must watch
+        # for THIS, not for "clamped" below. At the default limit == max_w the
+        # integrator bound is reached first and the command derived from it can
+        # then never exceed max_w, so "clamped" is unreachable on a default
+        # install - it survives only for a configuration that deliberately lets
+        # the integrator run above the rail. Two reasons rather than one
+        # because the two events want different alarms: "i-clamped" is the loop
+        # winding, "clamped" is a command that came out over the rating anyway.
+        reason = "i-clamped"
+    i_w = bounded
     want = i_w
 
     # ⚠️ Maintenance shaping (charge-only, cheap-window floor) used to live

goodwe_controller/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.2.1"
+version: "0.3.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart

goodwe_controller/test_control.py

@@ -24,6 +24,63 @@ def check(name, cond):
         fails.append(name)
 
 
+# ---------------------------------------------------------------------------
+# COVERAGE AUDIT - measured, not executed. Read this before adding a mechanism.
+#
+# THE INVARIANT: every mechanism in compute() must be noticed by AT LEAST TWO
+# checks when it is deleted. If you add a mechanism to compute(), re-run the
+# audit and add it to the table. If a figure here drops, a check has started
+# passing for a reason other than the one it names.
+#
+# THE TECHNIQUE, because there is no script to run: replace one mechanism in
+# control.py with a no-op, run this file, count the failures, restore. That is
+# the converse of the usual mutation - not "does a wrong value fail?" but "does
+# anyone notice when the mechanism is GONE?". It is kept as a comment rather
+# than as tooling on purpose: the only cheap way to automate it is to key on
+# source lines, which goes stale silently, and a green audit that has quietly
+# stopped testing anything is precisely the failure this ticket exists to fix.
+# A comment cannot go stale-green, because it never claims to be running.
+#
+# Measured at 389d9ec. Numbers are the lead's independent reproduction.
+#
+#   mechanism in compute()                     checks that fail when deleted
+#   ------------------------------------------ -----------------------------
+#   integrator freeze (AC 3)                                               2
+#   integrator clamp (AC 1)                                                6
+#   integrator bound follows max_w                                         4
+#   output clamp                                                           3
+#   slew limit                                                             4
+#   output freeze                                                          2
+#   deadband                                                               5
+#   quantisation                                                           2
+#   saturation detector, `saturated_now = False`                          11
+#   saturation duration (AC 2), fires instantly                            2
+#   sat counter reset on a good cycle                                      6
+#   target_grid_w bias                                                     3
+#   i_w=None seeding from prev_w                                           6
+#
+# The detector figure is for the `saturated_now = False` form specifically;
+# disabling it further down as `frozen = False` is a weaker mutation and gives
+# 10. Reproduce the same form or the number will not match.
+#
+# ⚠️ IT HAS FOUND A DEAD MECHANISM TWICE, BOTH THE SAME WAY: a clamp standing in
+# for the mechanism under test. Deleting the integrator freeze once failed
+# NOTHING, because the fixtures sat at max_w 2000 and the integrator bound
+# truncated a wound value back to exactly 2000 - the assertion passed on the
+# clamp. The output clamp was masked the same way by the integrator bound.
+# Hence: A FIXTURE MUST SIT CLEAR OF EVERY RAIL IT IS NOT TESTING. Where a test
+# names one mechanism, make that mechanism the binding one (see TCLAMP and TF).
+#
+# ⚠️ RUN MUTATIONS WITH `python -B` AND CLEAR app/__pycache__. CPython
+# invalidates a .pyc on (source mtime in whole seconds, source size), so a
+# same-second rewrite that also preserves the file size reuses stale bytecode
+# and the suite reports on code you are no longer running. It under-reported one
+# mutation here as 2 where the true figure is 6. The error is one-directional -
+# stale bytecode can only under-report - so every figure above is a lower bound
+# at worst, and the two zeros ever recorded were both confirmed by fixing them
+# and watching the count rise, which a caching artefact cannot do.
+# ---------------------------------------------------------------------------
+
 print("control law")
 
 # Deadband: inside meter noise, hold exactly - do not drift.
@@ -41,13 +98,22 @@ check("proportional step (gain 0.6)", d.target_w == 300)
 d = compute(prev_w=0, grid_w=-500, actual_w=0, tuning=T)
 check("export drives charging", d.target_w == -300)
 
-# Clamp
-d = compute(prev_w=1900, grid_w=1000, actual_w=1900, tuning=Tuning(max_w=2000, slew_w=5000))
+# Clamp.
+# ⚠️ integrator_max_w is lifted clear of max_w so that the OUTPUT clamp is the
+# mechanism under test. Left at the default the integrator bound truncates
+# first, these two assertions pass on that alone, and deleting the output clamp
+# fails nothing - the same masking that hid the integrator freeze.
+TCLAMP = Tuning(max_w=2000, slew_w=5000, integrator_max_w=5000)
+d = compute(prev_w=1900, grid_w=1000, actual_w=1900, tuning=TCLAMP)
 check("clamped to max_w", d.target_w == 2000)
 
 # Slew: from 0 with a huge error, no more than slew_w in one cycle.
 d = compute(prev_w=0, grid_w=5000, actual_w=0, tuning=Tuning(max_w=5000, slew_w=1000))
 check("slew limits one cycle", d.target_w == 1000)
+d = compute(prev_w=-1900, grid_w=-1000, actual_w=-1900, tuning=TCLAMP)
+check("clamped to -max_w", d.target_w == -2000)
+d = compute(prev_w=0, grid_w=-5000, actual_w=0, tuning=Tuning(max_w=5000, slew_w=1000))
+check("slew limits one cycle, charging", d.target_w == -1000)
 
 # Saturation needs DURATION: one diverging cycle must NOT freeze.
 t = Tuning(saturation_w=500, saturation_cycles=3)
@@ -86,12 +152,12 @@ RUNAWAY_CYCLES = 150
 HISTORICAL_W = 14768.0
 
 
-def runaway(tuning):
+def runaway(tuning, sign=1):
     """Inverter off: it reports 0 W forever, the error never clears."""
     prev, i_w, sat = 0.0, 0.0, 0
     worst_i, worst_cmd = 0.0, 0.0
     for _ in range(RUNAWAY_CYCLES):
-        d = compute(prev_w=prev, grid_w=RUNAWAY_ERROR, actual_w=0.0,
+        d = compute(prev_w=prev, grid_w=sign * RUNAWAY_ERROR, actual_w=0.0,
                     tuning=tuning, sat_count=sat, i_w=i_w)
         prev, i_w, sat = d.target_w, d.i_w, d.sat_count
         worst_i = max(worst_i, abs(i_w))
@@ -113,6 +179,12 @@ check(f"runaway with the detector defeated: integrator still bounded ({wi:.0f} W
       wi <= TD.max_w)
 check("runaway with the detector defeated: command still <= max_w", wc <= TD.max_w)
 
+# The mirror: the same runaway driving the other way. An export that never
+# clears winds the integrator negative just as hard.
+wi, wc = runaway(Tuning(max_w=2000), sign=-1)
+check(f"runaway (export direction): integrator bounded at {wi:.0f} W", wi <= 2000)
+check("runaway (export direction): emitted command <= max_w", wc <= 2000)
+
 # The bound is a separate quantity, and the useful direction is BELOW max_w:
 # there it binds first and caps unwind latency tighter than the rail does.
 d = compute(prev_w=0, grid_w=6000, actual_w=0,
@@ -121,11 +193,22 @@ check("integrator bound binds independently of the output clamp",
       d.i_w == 1000 and d.target_w == 1000)
 
 # Freeze = may not wind further in the direction it is already pushing.
-TF = Tuning(saturation_w=500, saturation_cycles=3)
+# ⚠️ max_w is raised WELL above the fixtures on purpose. At the default 2000
+# the integrator bound truncates a wound value back to exactly 2000 and
+# satisfies these assertions on its own, so deleting the freeze outright
+# failed nothing - the clamp was standing in for the mechanism under test.
+# Any fixture here must sit clear of every rail, or it tests the rail.
+TF = Tuning(saturation_w=500, saturation_cycles=3, max_w=5000)
 f1 = compute(prev_w=2000, grid_w=800, actual_w=0, tuning=TF, sat_count=3, i_w=2000.0)
 check("frozen: integration does not wind further", f1.i_w == 2000.0 and f1.frozen)
 f2 = compute(prev_w=2000, grid_w=-800, actual_w=0, tuning=TF, sat_count=3, i_w=2000.0)
 check("frozen: unwinding is still allowed", f2.i_w < 2000.0)
+# ...and the same two on the charging side. Every freeze rule in this file has
+# a mirror, because the one that did not is the defect that got through review.
+f3 = compute(prev_w=-2000, grid_w=-800, actual_w=0, tuning=TF, sat_count=3, i_w=-2000.0)
+check("frozen (charging): integration does not wind further", f3.i_w == -2000.0)
+f4 = compute(prev_w=-2000, grid_w=800, actual_w=0, tuning=TF, sat_count=3, i_w=-2000.0)
+check("frozen (charging): unwinding is still allowed", f4.i_w > -2000.0)
 
 # ⚠️ REGRESSION, and the reason the first cut of SAFETY-04 was rejected. A
 # freeze encoded as "only corrections that shrink |i_w|" is unsatisfiable for
@@ -145,6 +228,50 @@ check("frozen at i_w=0: the freeze then clears", not z2.frozen)
 z3 = compute(prev_w=100, grid_w=-1000, actual_w=800, tuning=T, sat_count=3, i_w=100.0)
 check("frozen at i_w=+100: a 1 kW export still moves the command",
       z3.frozen and z3.target_w < 0)
+z4 = compute(prev_w=-100, grid_w=1000, actual_w=-800, tuning=T, sat_count=3, i_w=-100.0)
+check("frozen at i_w=-100: a 1 kW import still moves the command",
+      z4.frozen and z4.target_w > 0)
+
+# ⚠️ EXACTLY ZERO, BOTH DIRECTIONS. This boundary has a history: the first cut
+# deadlocked here under import, and the fix for it deadlocked here under export
+# because `if i_w > 0 ... else ...` files 0.0 under rising-only. main.py resets
+# i_w to exactly 0.0 on every stop and every reseed, so it is a normal state,
+# not a corner.
+zi = compute(prev_w=0, grid_w=2000, actual_w=600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0.0: an import push moves the integrator",
+      zi.frozen and zi.i_w > 0)
+ze = compute(prev_w=0, grid_w=-2000, actual_w=-600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0.0: an export push moves the integrator",
+      ze.frozen and ze.i_w < 0)
+# The COMMAND still holds at 0 W in that second case, and that is release/1.0's
+# rule, not a leftover: at prev_w == 0 the output freeze forbids starting to
+# charge while saturated, because commanding 0 while the inverter reports
+# hundreds of watts means something else is driving the bus. Asserted so that
+# nobody "fixes" it by accident - the integrator moving is what this ticket
+# owns, the command rule belongs to the output freeze.
+check("frozen at i_w=0.0: the output freeze still blocks a charge from 0 W",
+      ze.target_w == 0.0)
+# Where prev_w is already charging the output freeze does NOT block, and there
+# the difference reaches the wire: held at 0.0 the integrator abandons the
+# charge mid-export.
+zc = compute(prev_w=-2000, grid_w=-4000, actual_w=-600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0.0: a charge is not abandoned during heavy export",
+      zc.target_w == -2000.0)
+
+# The general property, rather than another handful of points: while frozen the
+# integrator may be held ONLY when the correction would push it further from
+# zero on the side it already sits. Any other hold is a deadlock.
+stuck = []
+for i0 in [x * 25.0 for x in range(-80, 81)]:
+    for g in [x * 100.0 for x in range(-40, 41)]:
+        err = g - T.target_grid_w
+        if abs(err) < T.deadband_w:
+            continue
+        dd = compute(prev_w=0.0, grid_w=g, actual_w=1500.0, tuning=T, sat_count=3, i_w=i0)
+        if dd.i_w == i0 and not ((i0 > 0 and err > 0) or (i0 < 0 and err < 0)):
+            stuck.append((i0, g))
+check(f"frozen integrator never deadlocks, over {161*81} states"
+      + (f" (e.g. {stuck[0]})" if stuck else ""), not stuck)
 
 # False-positive guard: a normal 2 kW load step must not trip the detector,
 # because the plant needs several cycles to catch up on every one of them.
@@ -196,34 +323,67 @@ print("SAFETY-04: the i_w=None path is still release/1.0, exactly")
 
 def legacy(prev, grid, actual, t, sat_count):
     """release/1.0's control law, transcribed. Do not 'improve' this."""
+    reason = "tracking"
     sc = min(sat_count + 1, 10) if abs(prev - actual) > t.saturation_w else 0
     frozen = sc >= t.saturation_cycles
     error = grid - t.target_grid_w
-    want = prev if abs(error) < t.deadband_w else prev + t.gain * error
+    if abs(error) < t.deadband_w:
+        want, reason = prev, "deadband"
+    else:
+        want = prev + t.gain * error
     target = max(-t.max_w, min(t.max_w, want))
-    target = max(prev - t.slew_w, min(prev + t.slew_w, target))
+    if target != want:
+        reason = "clamped"
+    slewed = max(prev - t.slew_w, min(prev + t.slew_w, target))
+    if slewed != target:
+        reason = "slew-limited"
+    target = slewed
     if frozen:
         target = min(target, prev) if prev > 0 else max(target, prev)
+        reason = "saturated-freeze"
     step = max(1, int(t.step_w))
-    return float(round(target / step) * step), sc
+    return float(round(target / step) * step), sc, frozen, reason
 
 
-# Exhaustive over the interesting corners, both freeze states, both signs, and
-# either side of the deadband. This is what makes the claim in control.py's
-# integrator comment a checked fact rather than an assertion.
+# ⚠️ Compare EVERYTHING observable, not just the number. A previous version of
+# this sweep compared (target_w, sat_count) only and passed 3024 cases while
+# `reason` had silently lost a value - which is the kind of thing a sweep this
+# broad exists to catch. `frozen` and `reason` are both in the tuple now.
+#
+# The one deliberate rename: what release/1.0 called "clamped" is now
+# "i-clamped", because the truncation happens on the integrator before the
+# command is derived from it. Aliased here rather than papered over - if any
+# OTHER reason ever diverges, this check goes red.
+ALIAS = {"i-clamped": "clamped"}
 diffs = []
+seen = set()
 for tune in (Tuning(), Tuning(target_grid_w=-10.0), Tuning(max_w=5000, slew_w=5000)):
     for prev in (-2000.0, -500.0, -100.0, 0.0, 100.0, 500.0, 2000.0):
         for grid in (-6000.0, -1000.0, -500.0, -14.0, 0.0, 14.0, 500.0, 1000.0, 6000.0):
             for actual in (-2000.0, 0.0, 600.0, 2000.0):
                 for sc in (0, 2, 3, 9):
                     d = compute(prev, grid, actual, tune, sc)   # i_w defaults to None
-                    lt, lsc = legacy(prev, grid, actual, tune, sc)
-                    if (d.target_w, d.sat_count) != (lt, lsc):
-                        diffs.append((prev, grid, actual, sc, d.target_w, lt))
-check(f"i_w=None reproduces release/1.0 over {3*7*9*4*4} cases"
+                    seen.add(d.reason)
+                    got = (d.target_w, d.sat_count, d.frozen,
+                           ALIAS.get(d.reason, d.reason))
+                    if got != legacy(prev, grid, actual, tune, sc):
+                        diffs.append((prev, grid, actual, sc, got,
+                                      legacy(prev, grid, actual, tune, sc)))
+check(f"i_w=None reproduces release/1.0 over {3*7*9*4*4} cases, reason included"
       + (f" (first diff {diffs[0]})" if diffs else ""), not diffs)
 
+# ...and the rename is not a quiet deletion: the signal SAFETY-03 alarms on has
+# to actually occur in that sweep, or its hook is dead.
+check("the integrator clamp reports itself as 'i-clamped'", "i-clamped" in seen)
+
+# "clamped" stays reachable, but only where the integrator is deliberately
+# allowed above the rail - then BOTH fire and the output clamp, which describes
+# the value actually emitted, is the one reported.
+dc = compute(prev_w=0, grid_w=6000, actual_w=0,
+             tuning=Tuning(max_w=2000, integrator_max_w=3000, slew_w=5000))
+check("the output clamp still reports 'clamped' when it is the binding one",
+      dc.reason == "clamped" and dc.i_w == 3000 and dc.target_w == 2000)
+
 print("capacity tariff")
 check("no forecast means no cap", maintenance_charge_floor(2500, None, 3500) == 2500)
 check("headroom caps the charge", maintenance_charge_floor(2500, 2000, 3500) == 1500)