v1.13.0

Release v1.13.0

Release Date: 2026-02-27

Type: Minor release - Fixes energy over-counting caused by Alfa firmware register timing and upgrades ModbusLink.

Summary

This release fixes a significant accuracy issue in the calculated energy sensors (energia_auto_consumata
and energia_consumata) caused by the Alfa device firmware updating its Modbus registers asynchronously.
It also upgrades ModbusLink to v1.5.1, which adds a separate TCP connection timeout for faster detection
of unreachable devices.

Root Cause: Alfa Firmware Register Timing

The Alfa device firmware updates its energy registers (energia_prodotta and energia_immessa) on an
internal ~15-minute cycle. However, it does not update them atomically — energia_prodotta (production)
is always written ~55-60 seconds before energia_immessa (export). This means that with the integration's
default 60-second polling interval, the two values are often captured in a desynchronized state:

• Poll N: energia_prodotta has been updated (new value), but energia_immessa still holds the
  previous cycle's value (stale)
• Poll N+1: energia_immessa catches up, energia_prodotta unchanged

The integration calculates self-consumption as prodotta - immessa. When prodotta is fresh but immessa
is stale, the difference temporarily spikes upward. On the next poll, when immessa catches up, the
difference drops back down. This oscillation pattern interacts badly with Home Assistant's
TOTAL_INCREASING state class, which interprets any decrease as a meter reset and adds the "lost"
amount on top. Over a full day, this caused significant over-counting on self-consumption and
consumption sensors.

The Fix: Synchronized Calculation with Time-Based Timeout

The integration now implements a sync guard for calculated energy sensors:

1. Both-fresh gate: Energy sensors are only recalculated when both energia_prodotta and
   energia_immessa have changed since the last calculation. This ensures the difference is always
   computed from a consistent pair of values.

2. Time-based timeout (SYNC_TIMEOUT_SECONDS = 120): During periods when only one sensor is
   changing (e.g., nighttime with no exports, or no-production periods), a 120-second timeout allows
   the calculation to proceed. This is safe because when only one sensor changes, there is no
   oscillation pattern.

3. Quiescent reconciliation: When both base sensors stop changing (e.g., after sunset),
   energia_auto_consumata is force-aligned with the true prodotta - immessa value. This prevents
   any residual gap from carrying over to the next day's utility meters.

4. Consumed energy always live: energia_consumata (import + production - export) is calculated
   outside the sync guard, since it depends on energia_prelevata (import) which updates independently
   and doesn't suffer from the firmware timing issue.

Power sensors (MEASUREMENT state class) are always calculated immediately — they don't accumulate
and are not affected by the oscillation.

What's Changed

Fixed

• Fixed energy over-counting in calculated sensors - Synchronized energia_auto_consumata
  calculation to wait for both base sensors to update, eliminating the oscillation pattern that
  caused HA's TOTAL_INCREASING to over-count
• Fixed consumed energy sensor freezing at night - Moved energia_consumata outside the sync
  guard so it always reflects the latest import values
• Fixed cross-midnight timing artifact - Added quiescent reconciliation to prevent stale values
  from carrying over to the next day's utility meters
• Fixed debug log spam during nighttime - Sync waiting messages only fire when relevant

Changed

• Upgraded ModbusLink from v1.4.2 to v1.5.1 - Adds connection_timeout parameter (5s fixed)
  for TCP connection establishment, separate from the user-configurable data timeout. Unreachable
  devices are now detected faster.

User Action Required

Which Sensors Are Affected?

Only sensors derived from the two calculated Alfa sensors are affected:

• sensor.alfa_energy_self_consumed (energia_auto_consumata)
• sensor.alfa_energy_consumed (energia_consumata)

Sensors tracking direct Modbus registers are NOT affected — production, export, and import
values from the Alfa device have always been correct.

How to Fix Utility Meters

Future data is automatically correct after installing this release — no action needed for
new readings.

To fix accumulated values, use the utility_meter.calibrate service. Calculate the correct
value using the direct (unaffected) Alfa sensors:

• Self-consumption = Production - Export
• Consumption = Import + Production - Export

How to Fix Historical Statistics (Energy Dashboard)

1. Go to Developer Tools > Statistics
2. Search for the affected sensor (e.g., sensor.alfa_energy_self_consumed)
3. Click the adjust icon to correct individual hourly data points

Full Changelog:
compare/v1.2.12...v1.13.0