mat/homeassistant-comwatt
Watch
1
0
Fork
You've already forked homeassistant-comwatt
 0
Code Issues 36 Pull requests 1 Projects Releases Packages Activity Actions

🐛 fix: site flow metrics are instantaneous power (W), not hourly Wh #70

Merged
mat merged 2 commits from fix-site-unit into main 2026-08-23 13:42:45 +00:00
Conversation 0 Commits 2 Files changed 3 +71 -14
mat commented 2026-08-15 17:55:22 +00:00
Owner
Copy link

Corrects a unit-semantics bug dating from the origin of the site sensors.

The bug

The 6 site sensors (production, consumption, injection, withdrawal, charge, discharge) were declared WATT_HOUR / MEASUREMENT on the belief that get_site_time_series(site_id, "FLOW", "NONE", None, "HOUR", 1) returns hourly Wh deltas (per the code comment and the original analysis in #42).

Live API verification (2026-08-15) proved otherwise:

  • the FLOW/HOUR series is sampled ~every 2 min (29 points/h, 719/24 h), not 1/h
  • the values track instantaneous transients (clouds), mirroring the per-device *_power sensors (site production 4507 while solaire..._power = 4457 W, same freshness)
  • the site rate sensors are exact ratios of these values (53/4558 = 1.163 % = withdrawal_rate)

So these sensors have been instantaneous watts mislabeled as Wh all along. The ~1h "delay" attributed to them in #42 was a misreading — they are ~2 min fresh.

The fix

Metadata-only: the 6 sensors now expose UnitOfPower.WATT + device_class=POWER (state_class=MEASUREMENT unchanged). No unique_id, entity_id, name, data source, or cadence change. The false module comment and docstrings are corrected.

Migration note (important for HA ≥ 2025.12)

Home Assistant will raise a units_changed repair item for these 6 entities and will not record long-term statistics until the old Wh statistics are deleted (Developer Tools → Statistics). Historical states are kept. This is the standard remediation for a mislabeled unit.

Tests

2 new (TDD RED→GREEN): test_site_power_metrics_have_power_unit (unit W, device_class power, value passthrough) and test_site_rates_still_percent (rates keep % and ×100). 95 tests total, ruff + mypy clean.

Relation to #42

Closes the "site sensors lag ~1h" misconception; the real-time site energy work (adding <site>_*_total_energy from the official QUANTITY/HOUR buckets) is the next slice.

Corrects a unit-semantics bug dating from the origin of the site sensors. ## The bug The 6 site sensors (`production`, `consumption`, `injection`, `withdrawal`, `charge`, `discharge`) were declared `WATT_HOUR` / `MEASUREMENT` on the belief that `get_site_time_series(site_id, "FLOW", "NONE", None, "HOUR", 1)` returns hourly Wh deltas (per the code comment and the original analysis in #42). Live API verification (2026-08-15) proved otherwise: - the FLOW/HOUR series is sampled **~every 2 min** (29 points/h, 719/24 h), not 1/h - the values track instantaneous transients (clouds), mirroring the per-device `*_power` sensors (site production 4507 while `solaire..._power` = 4457 W, same freshness) - the site rate sensors are exact ratios of these values (53/4558 = 1.163 % = `withdrawal_rate`) So these sensors have been **instantaneous watts mislabeled as Wh** all along. The ~1h "delay" attributed to them in #42 was a misreading — they are ~2 min fresh. ## The fix Metadata-only: the 6 sensors now expose `UnitOfPower.WATT` + `device_class=POWER` (`state_class=MEASUREMENT` unchanged). No `unique_id`, entity_id, name, data source, or cadence change. The false module comment and docstrings are corrected. ## Migration note (important for HA ≥ 2025.12) Home Assistant will raise a `units_changed` repair item for these 6 entities and will not record long-term statistics until the old Wh statistics are deleted (Developer Tools → Statistics). Historical states are kept. This is the standard remediation for a mislabeled unit. ## Tests 2 new (TDD RED→GREEN): `test_site_power_metrics_have_power_unit` (unit W, device_class power, value passthrough) and `test_site_rates_still_percent` (rates keep % and ×100). 95 tests total, ruff + mypy clean. ## Relation to #42 Closes the "site sensors lag ~1h" misconception; the real-time site energy work (adding `<site>_*_total_energy` from the official QUANTITY/HOUR buckets) is the next slice.
📝 fix stale bucket vocabulary in _extract_site_metrics docstring
All checks were successful
Validate / lint-ruff (pull_request) Successful in 9s
Details
Validate / test-pytest (pull_request) Successful in 3m11s
Details
Validate / type-check-mypy (pull_request) Successful in 3m15s
Details
Validate / lint-ruff (push) Successful in 7s
Details
Validate / test-pytest (push) Successful in 3m8s
Details
Validate / type-check-mypy (push) Successful in 3m15s
Details
3c04a7e5df
mat changed title from WIP: fix: site flow metrics are instantaneous power (W), not hourly Wh to 🐛 fix: site flow metrics are instantaneous power (W), not hourly Wh 2026-08-23 13:42:26 +00:00
mat merged commit 09418fcb54 into main 2026-08-23 13:42:45 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
v1.0 · bloquant
À corriger absolument avant la release v1.0

  
v1.0 · majeur
Fortement recommandé avant la v1.0

  
v1.0 · mineur
Polish / robustesse, non bloquant

No labels
v1.0 · bloquant
v1.0 · majeur
v1.0 · mineur
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
mat/homeassistant-comwatt!70
No description provided.