feat(nibe_local): opt-in Solar PV surplus write path (srcfl/ftw#537)

[HuggeK]

What

nibe_local gains its first write path, and deliberately its only one: the
pump's native Solar PV surplus feed (registers 2107 enable / 2109
available power). The NIBE S-series was built to take a live "available solar
power" number from NIBE's own Modbus accessory and soak the surplus into
heating and hot water using owner-tuned offsets. FTW now acts as that
accessory — control by hint: the pump's firmware decides what to do with
the number, so a wrong value degrades to wasted comfort, never to unsafe
operation.

Tracks srcfl/ftw#537.

Safety posture

Off by default and triple-gated:

1. host capabilities.http.allow_write (the new FTW-core write grant),
2. driver write.solar_pv: true with a mandatory write.max_w clamp ceiling,
3. the owner-side enable on the pump itself (register 2107).

Every clamp answers a quantified risk:

• value clamped to [0, max_w] — a sign bug or telemetry spike must not tell the pump there are 100 kW of surplus;
• deadband + at-most-one-write-per-interval against register churn; a decrease past the deadband is written immediately (surplus collapsed = safety direction);
• dead-man's switch clears the feed when commands stop — the pump's timeout for a silently stopped feed is undocumented, so the driver does not lean on it;
• driver_default_mode clears the feed on watchdog trip / stale site meter / driver stop (idempotent, rate-limited);
• a startup sweep clears a non-zero feed a crashed run left standing;
• the clearing machinery stays armed even when a config mistake (missing max_w) refuses new writes, so a mistake never strands a standing feed.

The Local REST API's most dangerous habit is covered: it rejects a write
inside an HTTP 200 with a per-point error: read only value result. The
driver judges success on the body, never the status code, and surfaces a
read-only pump as an actionable error naming installer menu 7.5.15. The
driver header documents the decommission step (turn 2107 off, or set the API
read-only) for the day FTW is no longer there to clear the feed.

Requires FTW core host.http_patch

The write uses a new host verb, host.http_patch, added in a companion
srcfl/ftw PR (host-side gate capabilities.http.allow_write). On a core
without it the driver detects the absence, says so, and stays read-only —
so this driver is safe to publish ahead of the core change.

Catalog-convention compliance (why the driver body changed beyond the write path)

Editing this promoted driver drops its byte-identity exemption from
baselines/ftw, so the full catalog convention suite now applies to it.
Brought it into compliance without changing behaviour:

• wrapped the read path's http_get and json_decode in pcall (matches the esphome-dsmr idiom);
• lowercased the three mutable interval locals (setup_retry_ms, poll_interval_ms, full_refresh_ms) so driver_poll's returns match the poll-interval convention — they are reassigned from config, so lowercase is the honest style; genuine constants stay UPPERCASE;
• renamed resolve_pv_registers → resolve_pv_points: the _registers suffix made test_no_undefined_locals read a declared local function as an undeclared register guard.

baselines/ftw is intentionally left untouched — the baseline means "field-proven, Go-tested", which this new write path is not yet.

Why 2107/2109 specifically (register risk classification)

The Solar PV feed is the safest writable register class on the S-series:
it is control-by-hint and self-clearing in intent — the whole design
point is that FTW keeps feeding a number the pump interprets, and stopping the
feed (or the dead-man's clear) returns the pump to its own behaviour. Contrast
with persistent-state registers (degree minutes → short-cycling, operating
mode, DHW/legionella, heat curve) which latch and can harm the pump or comfort,
and forbidden ones (alarm/fault reset, sensor spoofing, defrost) which the
driver never exposes. 2108 ("include own consumption") and the offset
aggressiveness stay owner-tuned on the pump and are never written.

Tests

• New fake-pump Lua harness test_nibe_local_ftw.lua: clamp, deadband, sign conversion, pump-side gates (2107 disabled, read-only 200 rejection), dead-man's switch, orphan clear, u16 sentinel skip, rate-limit decrease bypass, default-mode idempotence, invalid-max_w keeps clearing armed.
• host_mock.lua gains an http_patch mock; spec/host-api-profile.json declares http_patch.
• Full catalog suite green for nibe_local (convention + test_no_undefined_locals); make check validators (sync/validate/host-api/history/baseline/sandbox) pass.

---

🤖 Generated with Claude Code

[frahlg]

Automated maintenance pass: not merging this one, and flagging it for a maintainer rather than acting further.

Reasons, in order of weight:

1. This is the repo's first write path on nibe_local, and AGENTS.md is explicit that new drivers start read-only and that control needs "a safe default mode, bounded leases, structured results and HIL acceptance for every target host." Whatever the quality of the fake-pump Lua harness, HIL acceptance on a real S-series unit is a human decision this session can't make or substitute for.
2. It depends on an unlanded companion change — FTW core's host.http_patch verb (tracked in Opt-in writable NIBE driver: feed PV production to the Solar PV registers (2107/2108/2109), later cap the electric add-heat ftw#537) — so even a clean merge here doesn't reach working control until that lands and the driver is re-verified against it.
3. It's from a non-collaborator contributor via a fork, so GitHub has held CI as action_required — nothing here has actually run against this repo's runners yet.
4. It's marked draft by its author, which already keeps it out of the merge queue.

The safety reasoning in the PR body (register risk classification, triple-gating, dead-man's switch) reads carefully thought through, and the write-path design looks sound on review. Flagging for a maintainer to: (a) approve CI so it actually runs, (b) decide when/whether to pursue HIL acceptance on real hardware, and (c) coordinate the FTW-side dependency before this leaves draft.

---

Generated by Claude Code

[frahlg]

Automated maintenance pass: re-checked, still not merging — status update rather than a new verdict.

What changed since the last pass: this PR is no longer draft, and CI now runs and is green on this repo's own runners (previously held as action_required since it came from a fork).

What hasn't changed, and is why this still isn't a merge:

1. This is nibe_local's first write path. AGENTS.md is explicit that new drivers start read-only and that control requires "a safe default mode, bounded leases, structured results and HIL acceptance for every target host." The Lua harness here (fake-pump test_nibe_local_ftw.lua) is thorough on the software side, but it isn't hardware-in-the-loop acceptance on a real S-series unit — that's a human/hardware step this session can't perform or waive.
2. The write path is inert without FTW core's host.http_patch verb (tracked in Opt-in writable NIBE driver: feed PV production to the Solar PV registers (2107/2108/2109), later cap the electric add-heat ftw#537), which hasn't landed. The driver degrades to read-only without it, so nothing unsafe ships today — but "safe to merge" and "ready to actually control a pump" are different questions, and the second one still needs that companion change plus re-verification against it.

Flagging for a maintainer to decide when/whether to run HIL acceptance on real hardware and to coordinate the FTW-side dependency. The design itself (register risk classification, triple-gating, dead-man's switch) continues to read as careful work.

---

Generated by Claude Code

[frahlg]

Automated maintenance pass: re-checked. Verdict unchanged — still not merging, still flagged for a maintainer — but one fact from the last pass needs correcting.

host.http_patch / capabilities.http.allow_write (srcfl/ftw#537) has landed and shipped, in ftw 1.14.0 (confirmed against ftw's CHANGELOG.md and go/internal/drivers/lua.go/host.go at current main). So the companion dependency is no longer a blocker — a host running 1.14.0+ would actually pick up the write path once merged, not just degrade to read-only.

That doesn't change the merge decision, though: this is still nibe_local's first write path, and AGENTS.md's requirement — "Control needs a safe default mode, bounded leases, structured results and HIL acceptance for every target host" — is a hardware-in-the-loop step nobody has performed yet. The fake-pump Lua harness is thorough but isn't HIL acceptance on a real S-series unit. dco is also still failing on this PR's head commit.

Flagging for a maintainer to decide when/whether to run HIL acceptance on a real pump; the design itself continues to read as careful, safety-conscious work.

---

Generated by Claude Code

[frahlg]

Automated repo maintenance pass (device-driver PR review).

This is nibe_local's first write path on a live heat pump, and the design covers most of AGENTS.md's control bar well: a safe default mode that clears the feed on watchdog/stale-meter/stop, a bounded 300s dead-man's-switch lease plus a startup orphan sweep, and structured driver_command results consistent with the rest of the catalog.

Two gaps worth a human look before this lands:

1. No hardware-in-the-loop evidence. Test coverage here is a new Lua harness against a mocked pump only — no real S-series capture or field data in the diff, which AGENTS.md calls for on any control change ("Control needs a safe default mode, bounded leases, structured results and HIL acceptance for every target host").
2. The write-refusal-counting rule (docs/WRITING-A-DRIVER.md, "the same rule for writes") isn't applied here, and CI doesn't catch it: test_refused_write_settles.py only probes drivers with PROTOCOL == "modbus", and nibe_local is PROTOCOL = "http" (writes via host.http_patch), so it's silently skipped. In the current code, driver_default_mode has no bounded refusal counter — if the pump keeps refusing the clear write (e.g. left read-only on the pump side), it retries every 60s indefinitely instead of counting to N and reporting the state as held, the way sungrow 1.5.7 does. Might be worth a follow-up issue for the refusal-counting check itself, since this gap would apply to any future HTTP-protocol control driver, not just this one.

Also: dco is currently failing on the head commit, and the PR base (1.1.1) is behind current main (1.1.2), so there's a real merge conflict to resolve independent of the above.

---

Generated by Claude Code

[HuggeK]

Branch updated with main; the conflicts were the catalog-wide 1.1.2 patch bumps from d128510 landing under this PR's 1.2.0 (kept — 1.2.0 was minted from 1.1.1 and the merged driver carries the verification-claim metadata), plus both sides' CHANGELOG bullets (both kept). Contract tests pass locally on the merged tree.

🤖 Generated with Claude Code

[miravoss26]

First write path for nibe_local — the pump's native Solar PV surplus feed (control-by-hint, so a wrong value degrades to wasted comfort, never unsafe operation). This is unusually careful work for an actuation change and I read it closely because of that.

Traced the deadband/rate-limit logic against the test suite — it's correct: the unconditional max_w clamp applies before any rate gate, a genuine decrease beyond the deadband bypasses the rate limit and writes immediately (safety direction), small jitter in either direction is swallowed, and an explicit zero always bypasses both the rate limit and the pump-side enable gate. The startup orphan-sweep correctly distinguishes a standing feed from the u16 not-connected sentinel (65535) so it doesn't turn "no accessory" into "accessory reporting zero."

Safety layering checks out: host allow_write + driver write.solar_pv+mandatory max_w + pump-side register 2107 enable, dead-man's switch for the undocumented pump-side timeout, default-mode clear gated on requested (not the validated flag) so a bad max_w config can't disarm the clearing machinery — a nice detail, and it's exercised by its own test.

Two minor, non-blocking notes:

• write_pv_surplus judges success via substring match (find(resp, "error")) rather than real JSON parsing of the per-point status. Matches the pump's fixed vocabulary and is tested, but a response shape with "error" appearing in an unrelated field would false-positive. Low risk given the closed vocabulary.
• serial (from the device's own registration response) is concatenated raw into the PATCH URL path — same pattern as the read-only driver this builds on (#7), not new here, and still same-host/pinned-cert scoped.

Test coverage is genuinely comprehensive — every safety branch has a corresponding assertion. verification_status stays beta, which matches a first write path that hasn't seen extended field hours yet. Safe to merge from my read.