📝 docs: document site power units, site energy cadence, and WebSocket limits #75

Merged

mat merged 1 commit from docs-sensor-semantics into main

2026-08-24 10:05:20 +00:00

mat commented

2026-08-24 09:59:27 +00:00

Owner

Addresses GitHub issue #54.

What

Adds a dedicated sensor reference (EN + FR) and refreshes the README sections to match the actual API behavior verified against the code:

New docs/sensors.md + docs/sensors-fr.md:

Site power sensors (Production, Consumption, Injection, Withdrawal, Charge, Discharge) are instantaneous W from the REST FLOW series sampled ~every 2 min — not hourly Wh deltas.
Site *_total_energy sensors are cumulative Wh driven exclusively by the official QUANTITY/HOUR buckets → they advance in hourly steps by design; seeded with ~8 days of history on first run.
Per-device Power: real time via WebSocket (FLOW messages, polyphase summed).
Per-device Total Energy: live accumulation from streamed power, reconciled hourly against server buckets; starts at zero at install; persisted across restarts.
The stream sends FLOW and STATE only — never QUANTITY — so all energy comes from REST buckets.
Energy dashboard guidance: use *_total_energy, never the power (W) entities.
Bonus: the four site rate sensors (%), not mentioned in the issue.

README.md / README-fr.md: new summary table in Usage (site vs device, W vs Wh, cadences), absolute links to the reference docs (they must also work from the HACS panel, which renders the README), and a Features section rewritten with the real vocabulary (injection/withdrawal/charge/discharge instead of "network in/out").

Notes

Every claim in the docs was verified against sensor.py, coordinator.py and stream.py before writing.

Addresses GitHub issue #54. ## What Adds a dedicated sensor reference (EN + FR) and refreshes the README sections to match the actual API behavior verified against the code: **New `docs/sensors.md` + `docs/sensors-fr.md`:** - Site power sensors (`Production`, `Consumption`, `Injection`, `Withdrawal`, `Charge`, `Discharge`) are **instantaneous W** from the REST `FLOW` series sampled ~every 2 min — not hourly Wh deltas. - Site `*_total_energy` sensors are **cumulative Wh** driven exclusively by the official `QUANTITY/HOUR` buckets → they advance in **hourly steps by design**; seeded with ~8 days of history on first run. - Per-device `Power`: **real time via WebSocket** (`FLOW` messages, polyphase summed). - Per-device `Total Energy`: live accumulation from streamed power, **reconciled hourly** against server buckets; starts at zero at install; persisted across restarts. - The stream sends `FLOW` and `STATE` only — **never `QUANTITY`** — so all energy comes from REST buckets. - Energy dashboard guidance: use `*_total_energy`, never the power (W) entities. - Bonus: the four site rate sensors (%), not mentioned in the issue. **README.md / README-fr.md:** new summary table in Usage (site vs device, W vs Wh, cadences), absolute links to the reference docs (they must also work from the HACS panel, which renders the README), and a Features section rewritten with the real vocabulary (injection/withdrawal/charge/discharge instead of "network in/out"). ## Notes - Every claim in the docs was verified against `sensor.py`, `coordinator.py` and `stream.py` before writing.

mat added 1 commit

2026-08-24 09:59:27 +00:00

📝 docs: document site power units, site energy cadence, and WebSocket limits

Validate / lint-ruff (push) Successful in 8s

Details

Validate / test-pytest (push) Successful in 3m12s

Details

Validate / type-check-mypy (push) Successful in 3m15s

Details

Validate / lint-ruff (pull_request) Successful in 7s

Details

Validate / test-pytest (pull_request) Successful in 3m14s

Details

Validate / type-check-mypy (pull_request) Successful in 3m15s

Details

9956977335

Site power sensors are instantaneous W from the REST FLOW series sampled
~every 2 min — not hourly Wh deltas. Site *_total_energy sensors are
cumulative Wh driven exclusively by the official QUANTITY/HOUR buckets,
so they advance in hourly steps by design. Per-device power updates in
real time through the WebSocket stream (FLOW), switches through STATE;
the stream never sends QUANTITY energy messages, so all energy comes
from REST buckets — directly for sites, via hourly reconciliation for
devices. Document the Energy dashboard guidance (use *_total_energy)
and the four site rate sensors, in EN and FR.

Closes #54

mat referenced this pull request

2026-08-24 09:59:34 +00:00

🔥 chore: drop info.md, HACS 2.0+ renders the README #76

mat changed title from ~~WIP: 📝 docs: document site power units, site energy cadence, and WebSocket limits~~ to 📝 docs: document site power units, site energy cadence, and WebSocket limits

2026-08-24 10:04:21 +00:00

mat merged commit 91c0229ec2 into main

2026-08-24 10:05:20 +00:00

mat deleted branch docs-sensor-semantics

2026-08-24 10:05:20 +00:00

mat referenced this pull request from a commit

2026-08-24 10:05:21 +00:00

📝 docs: document site power units, site energy cadence, and WebSocket limits (#75)

mat referenced this pull request from a commit

2026-08-24 10:05:36 +00:00

🔥 chore: drop info.md, HACS 2.0+ renders the README (#76)