feat(zap): opt-in read-only PV and battery ingest by frahlg · Pull Request #100 · srcfl/device-drivers

frahlg · 2026-08-23T16:51:40Z

Summary

Zap 3.1.0 keeps P1/HAN as the default and brings back opt-in, read-only ingest of PV and battery from devices Zap already talks to.

That matches the field case where a native inverter driver cannot be used (SolarEdge Modbus closed, no SetApp; or Zap already owns the RS-485 bus). Dual-Modbus sites stay on the 3.0 path: flags default off, so a native FTW driver is not doubled.

The driver still never writes. Chargers stay out — add those in FTW.

Config

config:
  host: zap.local
  read_pv: true        # default false
  read_battery: true   # default false

FTW Settings → Devices will expose the same switches once the bundled pin moves.

Test plan

make test-driver ID=zap
catalog generate (index, devices, support-status, manifests sha)
full pytest + host-api + sandbox + baseline check
FTW go test ./internal/drivers -run Zap against this commit (companion PR)

Note

Medium Risk
Core production driver now emits extra DERs when flags are on, so a misconfigured site can double-count PV/battery against a native driver. Still read-only; flags default off.

Overview
Zap 3.1.0 keeps P1/HAN as the default and adds opt-in, read-only PV and battery ingest from devices Zap already talks to (read_pv / read_battery, off by default). Chargers stay out; the driver still never writes.

Discovery now tracks per-serial meter/PV/battery records. When opted in, poll fetches those device snapshots, aggregates power (PV forced generation-negative; battery SoC capacity-weighted when possible), and drops overflow sentinels via a 10× nameplate sane_power guard. Catalog/manifest ders become [meter, pv, battery].

^{Reviewed by Cursor Bugbot for commit 5342bf2. Bugbot is set up for automated code reviews on this repo. Configure here.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 60021a0b07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-08-23T16:55:11Z

+        end
+    end
+
+    if any_power then


Suppress aggregates when any tracked source fails

When read_pv tracks multiple resources and one /data/json request fails or lacks a valid W, any_power can remain true because another resource succeeded, so this publishes a partial sum as the complete site PV value; the battery aggregate has the same behavior. Downstream consumers cannot distinguish that undercount from a real production or battery-power change, so suppress or explicitly invalidate the aggregate unless every tracked source contributes a current valid sample.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-23T16:55:11Z

+    notes: "P1/HAN site meter from a Sourceful Zap. PV and battery telemetry from devices on Zap are opt-in (read_pv / read_battery) and read-only. Prefer a native FTW driver; use Zap as the reader only when it already owns the bus."
+    min_driver_version: "3.1.0"


Record the Zap API in upstream_docs

The new PV and battery serializers are decoded from the Zap Local API referenced by the driver, but the updated manifest still has no upstream_docs entry. Consequently, the repository's weekly documentation watcher cannot detect when the payload contract changes or disappears; add that API URL and its metadata to this manifest.

AGENTS.md reference: AGENTS.md:L60-L66

Useful? React with 👍 / 👎.

frahlg · 2026-08-23T16:55:15Z

Companion FTW PR: srcfl/ftw#974 — Settings → Devices opt-in, tests, docs, bundled pin.

cursor

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 60021a0. Configure here.}

cursor · 2026-08-23T16:58:14Z

+        else
+            host.log("warn", "Zap: site-meter fetch failed: " .. tostring(err))
+        end
+    end


Duplicate meter fetch on failure

Medium Severity

After a successful discovery the site meter is always in tracked and already requested in the first loop of snapshot_map. When that request fails, the trailing fallback fetches the same URL again and logs the same warn a second time. Each failed poll therefore pays two HTTP round-trips and duplicate warnings before emit_meter also reports the gap.

^{Reviewed by Cursor Bugbot for commit 60021a0. Configure here.}

cursor · 2026-08-23T16:58:15Z

+        end
+    end
+
+    if not any_power then return end


Battery emit drops valid SoC

Medium Severity

emit_battery accumulates SoC and energy, then returns early unless sane_power accepted W. The driver comment notes Zap can return integer overflow sentinels when a unit is offline; with a known nameplate those values are rejected, so a still-valid SoC_nom_fract never reaches host.emit("battery", ...). Catalog guidance is to emit the battery DER when any answered field is usable, not only power.

Additional Locations (1)

drivers/lua/zap.lua#L104-L115

^{Reviewed by Cursor Bugbot for commit 60021a0. Configure here.}

cursor

Stale comment

Left a non-blocking comment: Cursor Bugbot found two unresolved medium-severity issues, so this is not approved. Assigned Leitet and davmoz for human review.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

P1/HAN stays the default. Sites where Zap is the only reader — closed inverter Modbus, or an RS-485 bus Zap already owns — can set read_pv or read_battery. The driver still never writes. Chargers stay out. Signed-off-by: Fredrik Ahlgren <fredrik@sourceful-labs.com>

srcfl/device-drivers#100 landed as 19dd64cc. Point the recovery snapshot at that commit instead of the PR head. Signed-off-by: Fredrik Ahlgren <fredrik@sourceful-labs.com>

cursor

Left a non-blocking comment: Cursor Bugbot skipped on this head (neutral/skipped), so this is not approved. Leitet and davmoz are already assigned; no additional reviewers were added.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

* feat(zap): opt-in read of PV and battery from Zap Keep Zap as the P1/HAN meter by default. Settings → Devices can turn on read-only PV or battery ingest when Zap is the only reader. The driver never writes. Bundled pin moves to srcfl/device-drivers@60021a0 (srcfl/device-drivers#100). Signed-off-by: Fredrik Ahlgren <fredrik@sourceful-labs.com> * chore(drivers): pin Zap 3.1.0 at the device-drivers merge srcfl/device-drivers#100 landed as 19dd64cc. Point the recovery snapshot at that commit instead of the PR head. Signed-off-by: Fredrik Ahlgren <fredrik@sourceful-labs.com> --------- Signed-off-by: Fredrik Ahlgren <fredrik@sourceful-labs.com>

frahlg mentioned this pull request Aug 23, 2026

feat(zap): opt-in read of PV and battery from Zap srcfl/ftw#974

Merged

5 tasks

chatgpt-codex-connector Bot reviewed Aug 23, 2026

View reviewed changes

cursor Bot reviewed Aug 23, 2026

View reviewed changes

cursor Bot requested review from Leitet and davmoz August 23, 2026 16:59

cursor Bot reviewed Aug 23, 2026

View reviewed changes

frahlg force-pushed the zap-opt-in-read branch from 60021a0 to 5342bf2 Compare August 24, 2026 08:45

frahlg merged commit 19dd64c into main Aug 24, 2026
9 checks passed

frahlg deleted the zap-opt-in-read branch August 24, 2026 08:49

cursor Bot reviewed Aug 24, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(zap): opt-in read-only PV and battery ingest - #100

feat(zap): opt-in read-only PV and battery ingest#100
frahlg merged 1 commit into
mainfrom
zap-opt-in-read

frahlg commented Aug 23, 2026 •

edited by cursor Bot

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Aug 23, 2026

Uh oh!

chatgpt-codex-connector Bot Aug 23, 2026

Uh oh!

frahlg commented Aug 23, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Aug 23, 2026

Uh oh!

cursor Bot Aug 23, 2026

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		notes: "P1/HAN site meter from a Sourceful Zap. PV and battery telemetry from devices on Zap are opt-in (read_pv / read_battery) and read-only. Prefer a native FTW driver; use Zap as the reader only when it already owns the bus."
		min_driver_version: "3.1.0"

Uh oh!

Conversation

frahlg commented Aug 23, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Config

Test plan

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

frahlg commented Aug 23, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 23, 2026

Choose a reason for hiding this comment

Duplicate meter fetch on failure

Uh oh!

cursor Bot Aug 23, 2026

Choose a reason for hiding this comment

Battery emit drops valid SoC

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

frahlg commented Aug 23, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading