draft(foxess_h3_smart): battery control via the remote-control block — hardware-validated, pending the control-tier pipeline (#70)

[Leitet]

Draft pending #70's rollout decision — CI is now fully green. This is the control implementation behind the hardware findings posted on #70. #69 merged 2026-08-06 and the branch tracks main. The v2 control contract (srcfl/ftw#738, #741) merged the same day, and this driver now implements it — driver_command_v2 / driver_default_mode_v2 with structured results, host-verified write evidence (write ack + setpoint readback), and a default mode that writes the release and proves it. Both package targets build as unsigned candidates and the packages job passes; what remains before un-drafting is the #70 product question of rolling out the control tier, not engineering. The driver runs today as a local operator override on the 1K5 site (v1 entrypoints, kept for exactly that), per Fredrik's own-driver-at-own-risk guidance.

What it does

driver_command("battery", power_w) drives the H3-Smart remote-control block: enable 46001=1, timeout 46002, i32 setpoint 46003/46004. The register's semantics were reverse-engineered on hardware and then confirmed against nathanmarlor/foxess_modbus: it is the inverter's AC active power, export-positive — not battery power and not a grid target. A naive vendor = -target charges by importing (it displaced PV for 12 h on this site before the model fell out), and a naive positive setpoint curtails PV instead of discharging. The driver therefore translates vendor = pv × PV_AC_EFF − battery_target, with the charge path guarded: BMS ceiling (46018/46019) minus a 200 W margin, a daylight split on PV string voltage, a one-cycle 0 W pause on import/export sign crossings, and hold-at-zero (a commanded 0 is a held setpoint, not a release — releasing produced a ~90 s limit cycle against the host's absorb ceiling). PV_AC_EFF = 0.977 is calibrated from two held-zero hardware points; the residual stays within ±25 W across the daytime range. Base work mode stays Self-use — remote control is an overlay and Self-use is the only fallback.

Safety posture (all hardware-exercised)

• Vendor timeout 60 s, refreshed every poll — the inverter reverts itself within a minute if the driver dies. The 60 is load-bearing: the master samples the RC block slowly, and a 15 s session expires before it acts — writes land, read back correctly, and do nothing, with zero error surface.
• Driver-side 60 s command lease — a silent EMS releases remote control rather than refreshing a stale setpoint forever.
• Explicit release in driver_default_mode; the disable is only written if this driver enabled the session, so a FoxESS-app strategy period is never stomped (the app uses these same registers — operators must not run app schedule periods alongside).
• Charge refused at SoC ≥ 99% — the inverter ignores its own Max SoC under remote control — and refused when the BMS charge limit reads below a 250 W floor (full, cold, or BMS hold: native self-use handles surplus better than a fighting setpoint).

Evidence

Validated live on a 1K5-HI-10-V1 in all three regimes: discharge in full sun (−1000 W commanded → battery −1080 W, PV uncurtailed), charge within PV surplus (no import, no curtailment, on target), and charge above surplus (import appears gradually and bounded, balance exact). Hold-at-zero verified across multiple days including the −70 W → +71 W → ±25 W calibration arc recorded in the driver header. Upstream telemetry tests (drivers/tests/test_foxess_h3_smart.py) replay the hardware capture, including per-phase CT and lifetime counters.

Covered since the earlier draft notes

• Control v2 contract implemented; packages CI job green. The v2 default mode always writes the disable and reads it back — the v1 skip-if-not-ours courtesy toward FoxESS-app schedule periods cannot be proven to the host, so the signed package owns 46001 outright (documented in the driver header).
• Control-path tests are in the diff (drivers/tests/test_foxess_h3_smart_control.py): statuses, codes, device_state, evidence lists, and the registers actually written, including the failure paths.
• The migration surfaced a latent v1 bug now fixed: the host's write bindings return error strings rather than raising, so a bare pcall reported failed writes as success.
• PV curtailment (pv-curtail, 0.8.0) via an AC-setpoint ceiling, hardware-validated: a 2000 W cap pinned export at cap−load while the battery absorbed the excess and PV ran uncurtailed.
• Versions and manifests synced via bump_driver.py; catalogs regenerated; changelog entry current.

🤖 Generated with Claude Code

[Leitet]

Branch updated through v0.5.0 — the setpoint semantics turned out to be inverter AC active power, export-positive (proved on hardware when a naive discharge command curtailed PV in full sun; confirmed against nathanmarlor/foxess_modbus, whose charge path documents the import-displaces-PV behaviour). Discharge is now hardware-validated in daylight; charge ships behind four guards adapted from the reference (BMS-ceiling cap with 200 W margin, daylight split by string voltage, sign-crossing pause, release-on-uncomputable). Full story in the commits.

[Leitet]

CI status is now definitive: dco, drivers (full suite incl. control-claims), signed-channel, history, boundary all green. Manifest and package metadata are fully synced and declare the truth: control: true, modbus.write, a typed battery command, vendor_autonomous default via driver_default_mode, and the bounded lease the driver actually implements (5 s heartbeat / 60 s max / return-to-default — the schema's lease model matched our hardware-derived design 1:1 without modification).

The single remaining red is packages, failing at exactly one line: ftw-core: control requires driver_default_mode_v2. That's the answer to this issue-#70 question about pipeline readiness: the control-package schema is complete and validates, and the only missing link is the v2 command contract on the FTW side (srcfl/ftw#738/#741, unmerged). When v2 ships, porting this driver's two entrypoints is the last step to a fully signed control artifact.

[Leitet]

Marking this ready for review. Summary of where it stands and what the review decides:

Engineering state. CI fully green, including packages — the control v2 contract (srcfl/ftw#738/#741) merged this morning and this driver implements it: structured results, host-verified write evidence (write ack + setpoint readback), a default mode that writes the release and reads it back. 63 tests including a dedicated v2 control suite; both package targets build as unsigned candidates.

Hardware evidence. Everything control-shaped here was validated on a live 1K5-HI-10-V1 over four days: discharge in full sun (PV uncurtailed, battery tracks), charge within and above PV surplus (bounded import, exact balance), hold-at-zero calibrated to ±25 W across the daytime range (two-point efficiency calibration recorded in the header), and PV curtailment (2000 W cap → export pinned at cap−load through cloud swings while the battery absorbed the excess). The register semantics (46003/46004 = AC active power, export-positive) were misdiagnosed twice before the model fell out and are confirmed against nathanmarlor/foxess_modbus; the header documents the evidence trail.

What merging decides. tools/ftw_repository.py now builds channel artifacts with control intact when the catalog says control: true ("control follows the catalog"). Merging this manifest is therefore the decision to ship a control-capable driver through the channel — the review is the gate, so saying it out loud: that is what approving this PR means. The stricter signed-package tier (v2 contract, per-site pins) builds green here but has no publication workflow yet; that remains #70.

The foxess removal, honestly framed. The last commit removes the untested 11000-range foxess driver. This is not a clean supersession — foxess_h3_smart covers 1K5-HI/H3-Smart, not the H1 / H3 / H3-PRO / AIO-H3 families the old driver claimed. But every one of those entries said "untested", and on hardware that answers unknown registers with silence, an unvalidated map is a trap, not a fallback (a real 1K5 answered none of it, and the catalog offering it anyway cost a full "device not supported" detour). generate_history.py now carries forward the published record of a removed driver — foxess 1.0.0 stays in driver-history.json; the channel just stops offering it. If reviewers want H1-range coverage kept listed, that commit reverts cleanly on its own.

🤖 Generated with Claude Code