admin/goodwe-addon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TEL-12: several PV inverters, and one absent member is an absent TOTAL
checks / unit (pull_request) Successful in 7m59s
Details

Browse Source 
0.11.0 shipped `pv_entity` as a single string. The reference site's owner
reported within minutes of it going live that they have several PV inverters
and could configure one - which is ordinary for a multi-string roof, not a
property of one house. `pv_entities` is the roster and the row carries the
SITE total.

⚠️ THE HARD PART IS ABSENCE, NOT THE LIST. Three configured, one `unavailable`,
and the sum of the other two is a SMALLER NUMBER INDISTINGUISHABLE FROM A REAL
ONE. Read back by OPT-10 that says "there was less PV than there was" - the "no
irradiance" conclusion the channel exists to TEST. So `pv.total()` answers
`None` the moment any configured entity is absent: the topic carries HA's own
`None`, the entity goes to `unknown`, the recorder records a GAP. The
alternative (the partial sum beside a contributor count) was implemented and
run as mutation N1b; it loses because the MQTT row is read COLD a week later by
an attribution that would believe it, while the qualifying count would live in a
second entity with its own history. The partial information is not thrown away -
the STATUS PAGE names every entity that reported, with its watts, and every one
that did not, with its reason, because that surface is read LIVE by a human who
wants the diagnostic.

⚠️ AND THE MIRROR: a member honestly reporting 0 W is SUMMED. The test is
`is None`, never falsiness - a roster that blanked the site on a zero would
report an absence on every clear evening.

THE SURFACE IS MEASURED, NOT PREFERRED. `pv_entity` could not become a list:
tools/supervisor_shape_probe.py §G shows Supervisor 2026.08.0 answering an
0.11.0 install's stored string with `Invalid list for option 'pv_entity'`, and
deepmerge's list strategy is `override` so a `[]` default does not rescue it -
the live add-on would not start. `match(.*)?` does accept both shapes and is
rejected for a different, measured reason: it validates nothing (a string, a
list and the integer 417 all pass) and renders as a plain text box. So
`pv_entities` joins `pv_entity` and REPLACES it when set, CFG-04's rule for
`inverters:`, with a status caution saying which key won - a union would
double-count the inverter the old key still names.

STILL NOT A CONTROL INPUT. tools/tel11_pv_trace.py was extended rather than
replaced and now grades five claims over three document sets. The control hash
is UNMOVED - 846a10a5b89e… on `unset` and on `one`, on both trees - and the
roster control document is byte-identical between the two trees. 2/5 is a claim
TEL-11 could not make: with 0.11.0 as the baseline, "one entity behaves exactly
as 0.11.0 does" is a real cross-tree identity over control AND telemetry.

⚠️ TEL-11's OWN `--compare` REFUSAL HAD TO CHANGE, and that is MUTATION.md habit
24: a discriminator defined as "the baseline lacks this feature" dies on the
release that ships the feature, and dies as a false refusal.

Twelve mutations, each on a fresh purged `cp -a`, no survivors. N5 is +0 B
(`sum` -> `max`, the same three characters) and was run on a fresh copy with
`cmp` confirming the edit on disk. The fixture is three distinct NON-ZERO
contributions in two units with absence driven at EVERY position - a member
contributing 0 W could go absent without moving the sum of the rest, which is
habit 23 with a coinciding value in the arithmetic rather than in the plant.

31/31 in the CI image. Not deployable as merged: config.yaml stays at 0.11.0,
so predeploy_check.py reports a NO-OP until PKG cuts a version. A CHANGELOG
entry is wanted and deliberately not written - 11b forbids `## Unreleased` and
the bump is PKG's call; DECISIONS/TEL-12-several-pv-inverters.md is the
material it needs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU
This commit is contained in:
admin
2026-09-24 22:13:25 +02:00
co-authored by Claude Opus 5
parent cccb2fa07b
commit 0ef9565071
13 changed files with 1893 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
goodwe_controller/app/main.py
+117 -29
View File
@@ -887,8 +887,13 @@ class Controller:
self.pv_w = None
# Why there is no reading, in words the page prints - or, on a good
# read, the UNIT the value came in. Never empty.
self.pv_why = ("not configured" if not self.pv_entity
self.pv_why = ("not configured" if not self.pv_roster
else "not read yet")
# TEL-12. EVERY configured entity's own answer, `(entity, watts, why)`,
# in roster order - kept because `checks()` has to be able to name the
# sensor that is missing, and `self.pv_w` alone cannot. Empty before the
# first read, which is what "no entity has answered yet" is.
self.pv_parts = []
# Did the grid-following loop actually win the LAST arbitration? That is
# the question SAFETY-02 has to ask about the command standing on the
# wire right now, so it is recorded when the arbitration happens rather
@@ -1669,20 +1674,29 @@ class Controller:
# -- io ------------------------------------------------------------------
@property
def pv_entity(self) -> str:
"""The configured PV production entity, or `""`. TEL-11.
def pv_roster(self) -> tuple:
"""Every configured PV production entity, or `()`. TEL-11/TEL-12.
⚠️ ONE READING OF THE OPTION, and `mqtt.optional_keys()` is graded
against it: the thing that decides whether the row is ANNOUNCED and the
thing that decides whether it is READ have to be the same predicate, or
the add-on ends up with an entity nothing feeds or a topic nothing
declared. `announced_units()` in mqtt.py is the same argument for the
roster, in its own words.
⚠️ ONE READING OF THE OPTIONS, and it is `pv.entities()` - the SAME call
`mqtt.optional_keys()` makes. The thing that decides whether the row is
ANNOUNCED, the thing that decides whether it is READ and the thing that
decides WHAT IS SUMMED have to be one predicate, or the add-on ends up
with an entity nothing feeds, a topic nothing declared, or a total taken
over a different list from the announced one. `announced_units()` in
mqtt.py is the same argument for the inverter roster, in its own words.
⚠️ IT REPLACED A `pv_entity` PROPERTY RATHER THAN JOINING ONE. Two
properties where one is a subset of the other is the second spelling
arriving by the back door; every gate in this file reads this one.
"""
return str(self.o.get("pv_entity") or "").strip()
return pv_read.entities(self.o)
async def _read_pv(self) -> None:
"""This cycle's PV production, or an ABSENCE with a reason. TEL-11.
"""This cycle's SITE PV production, or an ABSENCE with a reason.
TEL-11 for one entity, TEL-12 for a roster of them. `pv.total()` is where
"one of three is absent" becomes an absence of the SITE figure rather
than the sum of the two that answered, and its docstring is the argument.
⚠️ IT ASSIGNS ON EVERY CALL, INCLUDING THE FAILING ONES. Leaving the
last good number standing through an outage is what `circulation` does
@@ -1697,8 +1711,18 @@ class Controller:
there is no magnitude heuristic that can separate 30 W of dusk from
30 kW of noon.
"""
self.pv_w, self.pv_why = pv_read.watts(
await self.hass.state(self.pv_entity))
# ⚠️ TEL-12: EVERY ENTITY IN ONE GATHER, for the reason the outer
# gather exists (see `read_inputs()`). Read serially, a three-inverter
# roster with one slow sensor would add up to three of `hass.state()`'s
# 10 s timeouts to a cycle that feeds the ESP32 heartbeat - i.e. the
# telemetry channel would be able to push a healthy battery towards
# layer 1's veto, which is exactly the foot in the control path this
# card is not allowed to have. Gathered, N entities cost what one does.
roster = self.pv_roster
states = await asyncio.gather(
*(self.hass.state(entity) for entity in roster))
self.pv_w, self.pv_why, self.pv_parts = pv_read.total(
list(zip(roster, states)))
async def read_inputs(self, now_mono: float | None = None) -> None:
"""Every input this cycle needs, and SAFETY-37's freshness verdict.
@@ -1744,11 +1768,11 @@ class Controller:
# serially and stays that way because it is a CONTROL input (the
# capacity guard sizes off it), so the site is entitled to wait for it.
#
# ⚠️ AND AN UNSET `pv_entity` APPENDS NOTHING. Not a coroutine, not an
# ⚠️ AND AN EMPTY PV ROSTER APPENDS NOTHING. Not a coroutine, not an
# HTTP call, not a log line: at the shipped default this gather is the
# same list of the same coroutines it has always been.
_reads = [self._read_unit(inv, now_mono) for inv in self.inverters]
if self.pv_entity:
if self.pv_roster:
_reads.append(self._read_pv())
await asyncio.gather(*_reads)
if o.get("peak_forecast_entity"):
@@ -4472,7 +4496,13 @@ class Controller:
# goes to `unknown` and the recorder records a GAP - which is how a
# reader of a week of history tells "no PV reported" from "PV reported
# 0 W". The second never reaches the broker at all, because an install
# that never set `pv_entity` has no such entity announced.
# that never set `pv_entity` or `pv_entities` has no such entity
# announced. ⚠️ TEL-12: AND THE ROW IS STILL ONE NUMBER. At a roster of
# three it is the SITE total, `None` unless EVERY entity answered - see
# `pv.total()`, whose note is where the decision not to publish a
# partial sum is argued. This line did not have to change for that, and
# that is the point: TEL-11's `None`-is-an-absence rule already covered
# it, one layer up.
#
# ⚠️ AND THE GATE IS `optional_keys()`, THE SAME EXPRESSION THE
# ANNOUNCEMENT USES. Written as a second predicate here the two could
@@ -5000,7 +5030,7 @@ class Controller:
out.append({"ok": False, "warn": True,
"text": "no peak forecast: maintenance charging is not capacity-capped"})
# --- TEL-11 ----------------------------------------------------------
# ⚠️ NO ROW AT ALL WHEN `pv_entity` IS UNSET, AND THAT IS A DELIBERATE
# ⚠️ NO ROW AT ALL WHEN THE ROSTER IS EMPTY, AND THAT IS A DELIBERATE
# DIFFERENCE FROM THE PEAK-FORECAST CAUTION DIRECTLY ABOVE. That one
# nags because an unset forecast entity leaves a MONEY GUARD without an
# input; this one is pure instrumentation, and a permanent caution on
@@ -5013,20 +5043,78 @@ class Controller:
# battery site into NOT READY would be observability with a foot in the
# control path. The reason comes from `pv.watts()` rather than being
# re-derived here, so the page cannot disagree with the reading.
if self.pv_entity:
if self.pv_w is None:
#
# --- TEL-12: AND AT A ROSTER OF ONE THESE TWO SENTENCES ARE 0.11.0's --
# ⚠️ THE `len(...) == 1` BRANCH IS 0.11.0's CODE UNCHANGED, DOWN TO THE
# f-string, so an install that set `pv_entity` reads the row it already
# reads. That is an ACCEPTANCE CRITERION rather than a courtesy, and it
# is graded across trees by `tools/tel11_pv_trace.py` rather than argued
# here: `pv.total()` passes a single entity's `why` through verbatim for
# exactly this reason. Multi-entity sentences are separate BECAUSE they
# have to say something the single-entity ones never could.
roster = self.pv_roster
if roster:
if len(roster) == 1:
if self.pv_w is None:
out.append({"ok": False, "warn": True,
"text": f"PV production: no reading from "
f"{roster[0]} - {self.pv_why}"})
else:
# habit 14: the value sits inside its own literal text, in
# its own slot, beside the entity it was read from and the
# unit it was read in - so a transposition of any two of the
# three is visible in the sentence rather than merely
# present in it.
out.append({"ok": True, "warn": False,
"text": f"PV production: {self.pv_w:.0f} W "
f"from {roster[0]} (reported "
f"in {self.pv_why})"})
elif self.pv_w is None:
# ⚠️ THE ROW THAT SAYS THERE IS NO TOTAL, AND IT SAYS IT IN
# THOSE WORDS. `pv.total()`'s note is the argument; this is
# where the operator meets it. The partial information is NOT
# thrown away - every entity that reported is named with its
# watts and every one that did not is named with its reason -
# because this surface is read LIVE by a human who wants the
# diagnostic, whereas the MQTT row is read back COLD a week
# later by an attribution that would believe a smaller number.
# Different reader, different instant, different rule.
out.append({"ok": False, "warn": True,
"text": f"PV production: no reading from "
f"{self.pv_entity} - {self.pv_why}"})
"text": "PV production: NO SITE TOTAL - "
+ self.pv_why + ". Reporting: "
+ (", ".join(
f"{ent} {watt:.0f} W"
for ent, watt, _y in self.pv_parts
if watt is not None) or "nothing")})
else:
# habit 14: the value sits inside its own literal text, in its
# own slot, beside the entity it was read from and the unit it
# was read in - so a transposition of any two of the three is
# visible in the sentence rather than merely present in it.
# habit 14 at a roster: the total in its own slot, then EVERY
# contributor in its own slot with its own watts and its own
# unit. A sum that disagrees with the addends it is printed
# beside is visible in the sentence.
out.append({"ok": True, "warn": False,
"text": f"PV production: {self.pv_w:.0f} W from "
f"{self.pv_entity} (reported in "
f"{self.pv_why})"})
f"{len(self.pv_parts)} entities ("
+ ", ".join(
f"{ent} {watt:.0f} W in {why}"
for ent, watt, why in self.pv_parts)
+ ")"})
# ⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s
# `entities()` makes `pv_entities` REPLACE `pv_entity`, which is the
# right rule (its docstring says why) and is also the rule an
# operator upgrading from 0.11.0 is most likely to trip over: they
# add all their inverters to the new field and the old key is left
# standing, doing nothing. A replacement nobody is told about is the
# "one of which silently wins" `config.yaml` refuses elsewhere - and
# refusing to START over a telemetry key would be observability with
# a foot in the control path, so this is a CAUTION and never a `bad`
# row.
if pv_read.entity_is_ignored(self.o):
out.append({"ok": False, "warn": True,
"text": "PV production: `pv_entities` is set, so "
"`pv_entity` is IGNORED - the "
f"{len(roster)} entities in the "
"list are what is summed. Clear "
"`pv_entity` to remove this caution"})
return out
def status_payload(self) -> dict:
@@ -5152,7 +5240,7 @@ class Controller:
# question it answers is the one those two cannot: at "Grid 0 W,
# Battery 0 W" the site is either becalmed or throwing away every
# watt it makes, and only this row separates them.
*(() if not self.pv_entity else ((("PV", w(self.pv_w)),))),
*(() if not self.pv_roster else ((("PV", w(self.pv_w)),))),
("State of charge", "—" if self.pack_floor_soc is None
else f"{self.pack_floor_soc:g} %"),
("Commanded", w(self.target)),
@@ -5428,7 +5516,7 @@ async def amain() -> None:
omit=() if is_enabled(opts) else ("p1_age",),
# TEL-11. ⚠️ THE SHIPPED PREDICATE, NOT A SECOND READING OF THE
# OPTION - `Controller.publish()` gates the row on this same
# call. An install that never set `pv_entity` announces exactly
# call. An install with no PV roster announces exactly
# what it announced before: no topic, no entity, no row.
include=optional_keys(opts),
# TEL-07. ⚠️ THE NAMES, NOT A ROSTER. `build_roster()` here