Documentation Page
docs/public/power-and-energy-conventions.md — "The power-flows capability is an exception"
Current Documentation
The panel's power-flows capability does not use the panel-perspective rule above. Its four properties are a derived, source-centric summary in which each value describes what the named entity is doing, so their signs are inverted relative to the meter capabilities:
power-flows property |
Positive |
Negative |
grid |
Panel exporting to the utility |
Utility delivering into the panel |
pv |
(not produced in normal operation) |
PV generating into the panel |
battery |
Battery charging (panel delivering to it) |
Battery discharging into the panel |
site |
Site consuming |
Site net-producing |
Expected/Correct Information
The table is right. The sentence above it describes the opposite convention on three of the four properties.
"Each value describes what the named entity is doing" is the source's own frame. Read that way:
| property |
what "source-centric" implies |
what the table says |
pv |
positive = PV generating |
negative while generating |
battery |
positive = battery discharging |
positive while charging |
grid |
positive = grid supplying the home |
positive while exporting |
site |
positive = site consuming |
positive = site consuming ✅ |
Only site survives, and it survives because the site is not a device on the other side of a boundary — there is nothing to take a perspective from.
The values are not source-centric. They are panel-centric with the reference direction reversed: positive = power leaving the panel node, negative = power entering it. That single statement generates every row of the table, including the pv row that currently reads as an unexplained special case — positive pv would mean the panel is delivering power into the array, which is why it is not produced in normal operation.
Suggested replacement for the sentence:
The panel's power-flows capability does not use the panel-perspective rule above. Its four properties are a derived summary published in the reverse reference direction: positive means power flowing out of the panel node, negative means power flowing into it. Their signs are therefore inverted relative to the meter capabilities.
The second half of the existing sentence — "their signs are inverted relative to the meter capabilities" — is accurate and worth keeping.
Worth adding while you are in there: because all four terms share one frame, they are one balance at one node and sum to zero.
pv + battery + grid + site = 0
Stating that in the document would give integrators something they can assert against a live panel with no reference implementation and no hardware assumptions. It is also a fast self-check while wiring up a client: if the four retained values do not close, the client has a sign wrong somewhere, and the residual points at which one.
Additional Context
Found while reconciling a simulator's published tree against a panel's, property by property. The simulator had implemented the eBus power-flows catalog as literally written, which produced values inverted from the panel on pv, grid and battery — and the balance above missing zero by exactly 2 × site, which is what made the defect findable at all.
The wording matters here precisely because it is not vague. "Source-centric, each value describes what the named entity is doing" is an exact description of the convention the eBus power-flows catalog uses — positive = producing, positive = discharging, positive = importing — which is the convention SPAN Panel does not use. It points confidently at the wrong answer. An integrator who reads the sentence and skims the table implements the eBus signs believing they have implemented SPAN's, and gets a plausible-looking result with three of four values backwards.
That failure is quiet in a way most documentation errors are not. A wrong property name fails loudly at the first read. A wrong sign keeps producing believable numbers, and these particular values feed long-term statistics in consumer platforms — energy dashboards, cost attribution, monthly totals. The error is recorded and aggregated for weeks before anyone notices, and correcting the client afterwards does not repair what was already stored.
Verified against r202627 on the flat data model, where the four power-flows values close to within 1e-12 across samples taken hours apart. The battery sign could not be observed directly (no storage on that panel) and is taken from the r202633 changelog entry for the new BESS meter/active-power, which states that it is positive while charging and carries the same value and sign as power-flows/battery.
The rest of the document is consistent — the "three surfaces" note in the introduction, the downstream-lugs and BESS deviation notes, and the worked example's caveat that the published values cannot be summed directly all agree with the table. This is the one sentence that does not.
Documentation Page
docs/public/power-and-energy-conventions.md— "Thepower-flowscapability is an exception"Current Documentation
power-flowspropertygridpvbatterysiteExpected/Correct Information
The table is right. The sentence above it describes the opposite convention on three of the four properties.
"Each value describes what the named entity is doing" is the source's own frame. Read that way:
pvbatterygridsiteOnly
sitesurvives, and it survives because the site is not a device on the other side of a boundary — there is nothing to take a perspective from.The values are not source-centric. They are panel-centric with the reference direction reversed: positive = power leaving the panel node, negative = power entering it. That single statement generates every row of the table, including the
pvrow that currently reads as an unexplained special case — positivepvwould mean the panel is delivering power into the array, which is why it is not produced in normal operation.Suggested replacement for the sentence:
The second half of the existing sentence — "their signs are inverted relative to the
metercapabilities" — is accurate and worth keeping.Worth adding while you are in there: because all four terms share one frame, they are one balance at one node and sum to zero.
Stating that in the document would give integrators something they can assert against a live panel with no reference implementation and no hardware assumptions. It is also a fast self-check while wiring up a client: if the four retained values do not close, the client has a sign wrong somewhere, and the residual points at which one.
Additional Context
Found while reconciling a simulator's published tree against a panel's, property by property. The simulator had implemented the eBus
power-flowscatalog as literally written, which produced values inverted from the panel onpv,gridandbattery— and the balance above missing zero by exactly2 × site, which is what made the defect findable at all.The wording matters here precisely because it is not vague. "Source-centric, each value describes what the named entity is doing" is an exact description of the convention the eBus
power-flowscatalog uses —positive = producing,positive = discharging,positive = importing— which is the convention SPAN Panel does not use. It points confidently at the wrong answer. An integrator who reads the sentence and skims the table implements the eBus signs believing they have implemented SPAN's, and gets a plausible-looking result with three of four values backwards.That failure is quiet in a way most documentation errors are not. A wrong property name fails loudly at the first read. A wrong sign keeps producing believable numbers, and these particular values feed long-term statistics in consumer platforms — energy dashboards, cost attribution, monthly totals. The error is recorded and aggregated for weeks before anyone notices, and correcting the client afterwards does not repair what was already stored.
Verified against r202627 on the flat data model, where the four
power-flowsvalues close to within 1e-12 across samples taken hours apart. Thebatterysign could not be observed directly (no storage on that panel) and is taken from the r202633 changelog entry for the new BESSmeter/active-power, which states that it is positive while charging and carries the same value and sign aspower-flows/battery.The rest of the document is consistent — the "three surfaces" note in the introduction, the downstream-lugs and BESS deviation notes, and the worked example's caveat that the published values cannot be summed directly all agree with the table. This is the one sentence that does not.