Release v1.2.13-beta.7

Release Date: 2026-02-25

Type: Beta release - Replaces poll-count timeout with time-based timeout to fix overcounting
at short scan intervals.

What's Changed (since v1.2.13-beta.6)

Sync guard timeout fires too early with short scan intervals - The poll-count-based
SYNC_TIMEOUT_POLLS was inherently broken when scan_interval differs from the assumed 60s.
With a 10s scan interval, 3 polls x 10s = 30s timeout, which fires before the Alfa
firmware's ~55s delay between updating energia_prodotta and energia_immessa. The timeout
calculated with stale immessa, producing an UP-DIP oscillation pattern that HA's
TOTAL_INCREASING state class overcounted by the daily export amount.

Root cause: Poll-count-based timeout doesn't account for the actual scan interval.
The effective timeout in seconds was SYNC_TIMEOUT_POLLS x scan_interval, which varied
from 30s (at 10s polling) to 180s (at 60s polling). The firmware needs at least ~60s.

Fix: Replaced SYNC_TIMEOUT_POLLS with SYNC_TIMEOUT_SECONDS = 120. The sync guard
now tracks elapsed time using time.monotonic() instead of counting polls. This works
correctly regardless of scan interval: the guard holds auto_consumata frozen until the
"both fresh" condition fires (~60s), well before the 120s timeout. The timeout only fires
during genuine single-sensor-changing periods (no-export, no oscillation risk).

Beta	Bug	Root Cause
beta.1	Over-counting in calculated energy sensors	Desynchronized `prodotta - immessa` calculation
beta.2	Idle polls poisoned sync counter	`else` branch didn't distinguish "one fresh" from "neither fresh"
beta.3	Consumed energy freezes at night	`energia_consumata` locked inside sync guard
beta.4	(no bug fix -- ModbusLink 1.5.1 upgrade)	(dependency update)
beta.5	Cross-midnight timing artifact	Sync guard held stale value during quiescent period
beta.6	Autoconsumption = production (poll count 2->3)	Timeout still too short for 10s scan interval
beta.7	Timeout fires before immessa catches up	Poll-count timeout doesn't scale with scan_interval

After deploying this update:

During peak solar hours: Monitor sensor.alfa_energy_self_consumed. It should increase
only once per ~15-minute firmware cycle (when "both fresh" fires), with no intermediate
UP-DIP pattern. The debug log should show "Waiting for synchronized base sensor update"
with increasing elapsed_seconds values until "both fresh" fires at ~55-60s.
Hourly check: Compare hourly_autoconsumption vs hourly_production - hourly_export.
They should match. The overcounting (autoconsumption = production) should be eliminated.
After deploying: Calibrate utility meters to correct today's accumulated overcount.

Files changed: const.py (new constant), api.py (time-based logic), tests/test_api.py,
CLAUDE.md, energy-oscillation-fix.md
Replaced: SYNC_TIMEOUT_POLLS: int = 3 with SYNC_TIMEOUT_SECONDS: int = 120
Replaced: _unsync_poll_count: int = 0 with _first_unsync_time: float | None = None
Tests automatically adapted -- use time.monotonic() manipulation for timeout tests

Full Changelog:
compare/v1.2.13-beta.6...v1.2.13-beta.7