Improve AlphaESS schedule readback and clarify write pacing

Author: dragon2611

apps/predbat/alphaess.py

@@ -80,6 +80,7 @@
     ALPHAESS_HOLD_SOC,
     ALPHAESS_HOLD_POWER,
     ALPHAESS_SETTLE_POLLS,
+    ALPHAESS_CONFIG_SETTLE_SECONDS,
     ALPHAESS_WRITE_SETTLE_SECONDS,
     ALPHAESS_WRITE_BURST_MAX,
     ALPHAESS_STORAGE_MODULE,
@@ -89,6 +90,7 @@
     ALPHAESS_CACHE_CONTROL,
     ALPHAESS_TTL_STATIC,
     ALPHAESS_TTL_CONFIG,
+    ALPHAESS_TTL_CONTROL_CONFIG,
     ALPHAESS_TTL_ENERGY,
 )
 
@@ -1435,7 +1437,7 @@ def _owned_fields(direction):
         if direction == "charge":
             return ("gridCharge", "timeChaf1", "timeChae1", "timeChaf2", "timeChae2", "batHighCap")
         if direction == "periodic":
-            return ("gridChargeCycle", "ctrDisCycle", "chargeTimeList", "dischargeTimeList")
+            return ("executeCycleType", "gridChargeCycle", "ctrDisCycle", "chargeTimeList", "dischargeTimeList")
         return ("ctrDis", "timeDisf1", "timeDise1", "timeDisf2", "timeDise2", "batUseCap")
 
     # chargeTimeList/dischargeTimeList entries carry fields Predbat never writes (the API
@@ -1503,10 +1505,12 @@ def _field_differs(self, direction, field, observed_value, applied_value):
     def note_external_change(self, sn, direction, observed):
         """Report when a Predbat-owned field no longer matches what Predbat last wrote.
 
-        Suppressed for the first ALPHAESS_SETTLE_POLLS reads after a write, because
+        Suppressed for ALPHAESS_CONFIG_SETTLE_SECONDS after a write, because
         settings only reach the inverter on its next cloud poll - typically one to five
         minutes later - so an immediate read-back legitimately shows the old values.
-        Without that window every single write would raise a false alarm.
+        Count-based grace is only a fallback for old cached intent with no write timestamp.
+        Config reads can be thirty minutes apart, so counting those polls for a timestamped
+        write would hide a real overwrite for up to two hours, including after a restart.
 
         Does nothing before Predbat has written anything for this serial and direction:
         with no recorded intent there is nothing to have been overwritten, and what the
@@ -1518,7 +1522,11 @@ def note_external_change(self, sn, direction, observed):
         key = (sn, direction)
         polls = self.settle_count.get(key, 0) + 1
         self.settle_count[key] = polls
-        if polls <= ALPHAESS_SETTLE_POLLS:
+        last_write = self.last_write_time.get(key)
+        if last_write is not None:
+            if (time.time() - last_write) < ALPHAESS_CONFIG_SETTLE_SECONDS:
+                return
+        elif polls <= ALPHAESS_SETTLE_POLLS:
             return
         differing = [field for field in self._owned_fields(direction) if field in observed and self._field_differs(direction, field, observed.get(field), applied.get(field))]
         if not differing:
@@ -2145,7 +2153,10 @@ async def run(self, seconds, first):
         if not self.device_list:
             self.log("Warn: AlphaESS found no battery systems on this account")
             return False
-        if self.tier_expired("config", ALPHAESS_TTL_CONFIG):
+        config_ttl = ALPHAESS_TTL_CONFIG
+        if self.control_active.intersection(self.device_list) and self.control_enable and not self._is_read_only():
+            config_ttl = ALPHAESS_TTL_CONTROL_CONFIG
+        if self.tier_expired("config", config_ttl):
             await self.refresh_config()
         live_ok = True
         if self.tier_expired("power", self.power_tier_ttl()):

apps/predbat/alphaess_const.py

@@ -74,6 +74,8 @@
 # Tier TTLs in minutes.
 ALPHAESS_TTL_STATIC = 8 * 60
 ALPHAESS_TTL_CONFIG = 30
+# Check the real schedule more often while Predbat is actively controlling a system.
+ALPHAESS_TTL_CONTROL_CONFIG = 5
 ALPHAESS_TTL_POWER = 1
 ALPHAESS_TTL_ENERGY = 5
 # Power tier interval once a serial has been demoted to the history path - matches the
@@ -92,6 +94,8 @@
 # Polls a written payload is considered pending for before an unexpected read-back counts
 # as external interference (the phone app, or another Predbat instance).
 ALPHAESS_SETTLE_POLLS = 3
+# Inverter cloud propagation takes minutes, not three 30-minute config-tier polls.
+ALPHAESS_CONFIG_SETTLE_SECONDS = 5 * 60
 
 # How long after a SUCCESSFUL write a further difference still counts as the rest of the
 # SAME schedule update, and is therefore let through alphaess_min_write_interval.

apps/predbat/tests/test_alphaess_control.py

@@ -2022,10 +2022,105 @@ def test_alphaess_shutdown_force_mode_is_accepted():
     assert client.shutdown_mode == "self_consumption_force"
 
 
+def test_alphaess_readback_grace_expires_by_time_on_the_first_config_poll():
+    """A first read half an hour after a write must detect a disabled schedule immediately."""
+    for direction in ("charge", "discharge", "periodic"):
+        client = _writable()
+        field = {"charge": "gridCharge", "discharge": "ctrDis", "periodic": "gridChargeCycle"}[direction]
+        client.applied_payload["AL70"] = {direction: {field: 1}}
+        client.last_write_time[("AL70", direction)] = 1000.0
+        with patch("alphaess.time.time", return_value=2800.0):
+            client.note_external_change("AL70", direction, {field: 0})
+        assert direction not in client.applied_payload["AL70"], "A stale schedule was still cached as applied after 30 minutes"
+        assert any("no longer match" in message for message in client.log_messages)
+
+
+def test_alphaess_readback_grace_protects_the_full_five_minutes():
+    """Frequent early reads cannot spend the settling grace before the inverter catches up."""
+    client = _writable()
+    client.applied_payload["AL70"] = {"charge": {"gridCharge": 1}}
+    client.last_write_time[("AL70", "charge")] = 1000.0
+    for elapsed in (1, 60, 120, 180, 299):
+        with patch("alphaess.time.time", return_value=1000.0 + elapsed):
+            client.note_external_change("AL70", "charge", {"gridCharge": 0})
+        assert "charge" in client.applied_payload["AL70"], "A pending write was treated as interference before five minutes"
+    with patch("alphaess.time.time", return_value=1300.0):
+        client.note_external_change("AL70", "charge", {"gridCharge": 0})
+    assert "charge" not in client.applied_payload["AL70"]
+
+
+def test_alphaess_periodic_cycle_type_change_is_detected():
+    """Switching a daily schedule to weekly changes its meaning even when its times match."""
+    client = _writable()
+    payload = client.build_periodic_payload("AL70", _schedule())
+    client.applied_payload["AL70"] = {"periodic": payload}
+    client.last_write_time[("AL70", "periodic")] = 1000.0
+    with patch("alphaess.time.time", return_value=2800.0):
+        client.note_external_change("AL70", "periodic", dict(payload, executeCycleType=1))
+    assert "periodic" not in client.applied_payload["AL70"], "A daily schedule changed to weekly without being detected"
+
+
+def test_alphaess_control_readback_uses_five_minutes_only_while_driving():
+    """Active control checks settings sooner; monitoring and read-only retain the normal TTL."""
+    for active, enabled, read_only, interval in ((True, True, False, 300), (False, True, False, 1800), (True, False, False, 1800), (True, True, True, 1800)):
+        client = _client()
+        client.control_active = {"AL70"} if active else set()
+        client.control_enable = enabled
+        client.state["switch.predbat_set_read_only"] = "on" if read_only else "off"
+        client._tier_refreshed = {tier: 1000.0 for tier in ("static", "config", "power", "energy")}
+        with (
+            patch.object(client, "refresh_config", new_callable=AsyncMock, return_value=True) as refresh,
+            patch.object(client, "refresh_power", new_callable=AsyncMock, return_value=True),
+            patch.object(client, "refresh_energy", new_callable=AsyncMock, return_value=True),
+            patch.object(client, "_reconcile_control", new_callable=AsyncMock),
+            patch.object(client, "refresh_discovery"),
+        ):
+            with patch("alphaess.time.time", return_value=1000.0 + interval - 1):
+                assert run_async_local(client.run(0, False))
+            assert refresh.await_count == 0, "Config read ran before its TTL expired"
+            with patch("alphaess.time.time", return_value=1000.0 + interval):
+                assert run_async_local(client.run(0, False))
+            assert refresh.await_count == 1, "Config read did not run when its TTL expired"
+
+
+def test_alphaess_reverted_schedule_after_restart_is_reapplied_after_startup_delay():
+    """An old persisted write cannot hide a reversion, and recovery still obeys startup delay."""
+    from tests.test_alphaess_storage import FakeStorage, StoredAlphaESS
+
+    store = FakeStorage()
+    client = StoredAlphaESS(store=store)
+    client._periodic_ok["AL70"] = True
+    client.control_active.add("AL70")
+    client.local_schedule["AL70"] = _schedule(charge={"enable": True, "soc": 90, "power": 3000, "start": "01:00:00", "end": "05:00:00"})
+    payload = client.build_periodic_payload("AL70", client.local_schedule["AL70"])
+    client.applied_payload["AL70"] = {"periodic": payload}
+    client.last_write_time[("AL70", "periodic")] = 1000.0
+    run_async_local(client.save_config())
+    run_async_local(client.save_control())
+
+    restored = StoredAlphaESS(store=store, startup_write_delay=300)
+    run_async_local(restored.restore_state())
+    restored._post = AsyncMock(return_value=(200, None))
+    with patch("alphaess.time.time", return_value=2800.0):
+        restored.note_external_change("AL70", "periodic", dict(payload, gridChargeCycle=0, executeCycleType=1))
+        assert "periodic" not in restored.applied_payload["AL70"], "Restart granted a fresh multi-poll grace to an old write"
+        run_async_local(restored._reconcile_control("AL70"))
+        restored._post.assert_not_awaited()
+        restored.startup_write_ready_at = 0
+        run_async_local(restored._reconcile_control("AL70"))
+    restored._post.assert_awaited_once_with("set_time_charge", body=payload)
+    assert restored.applied_payload["AL70"]["periodic"] == payload
+
+
 def run_alphaess_control_tests(my_predbat):
     """Run all AlphaESS control-logic tests."""
     failed = False
     for name, fn in [
+        ("readback_elapsed_grace", test_alphaess_readback_grace_expires_by_time_on_the_first_config_poll),
+        ("readback_full_grace", test_alphaess_readback_grace_protects_the_full_five_minutes),
+        ("periodic_cycle_type_change", test_alphaess_periodic_cycle_type_change_is_detected),
+        ("active_control_readback_ttl", test_alphaess_control_readback_uses_five_minutes_only_while_driving),
+        ("restart_reversion_startup_delay", test_alphaess_reverted_schedule_after_restart_is_reapplied_after_startup_delay),
         ("entities_round_trip", test_alphaess_control_entities_round_trip),
         ("reserve_unclamped", test_alphaess_reserve_entity_is_published_unclamped),
         ("entity_routing", test_alphaess_entity_routing_does_not_confuse_prefixed_serials),

docs/apps-yaml.md

@@ -1028,7 +1028,7 @@ Keep `alphaess_app_id` and `alphaess_app_secret` in `secrets.yaml` rather than i
 - `alphaess_control_enable` - Allow Predbat to write charge/export schedules to the inverter. Defaults to **`true`** - an AlphaESS component that is configured but not writing to the inverter is not what most users expect, so set this to `false` explicitly if you only want monitoring
 - `alphaess_battery_rate_max` - Optional override, in Watts, for the battery's maximum charge/discharge rate - see below
 - `alphaess_api_delay` - Optional pacing between API calls, in seconds (default: `2`). AlphaESS advise a minimum 10-second polling interval between calls to the same endpoint
-- `alphaess_min_write_interval` - Optional minimum spacing between writes to the same inverter, in seconds (default: `300`). Both write endpoints are documented as writable once per 24 hours, so this is the first line of defence against exhausting that budget. Predbat applies a schedule in stages (window, then enable, then target SoC), so for up to 60 seconds after a write it will still send a small number of corrections to the schedule it just sent - otherwise a half-applied schedule, such as a charge window carrying the previous cycle's target SoC, would sit on the inverter for the whole interval
+- `alphaess_min_write_interval` - Optional local pacing between writes to the same inverter, in seconds (default: `300`). The periodic schedule API (`setTimeChargeBySn`) supports repeated updates and is not limited to one write per day; the once-per-day wording in the legacy endpoint documentation does not apply to it. This setting avoids unnecessary requests and is not an API-imposed daily limit. Predbat applies a schedule in stages (window, then enable, then target SoC), so for up to 60 seconds after a write it will still send a small number of corrections to the schedule it just sent - otherwise a half-applied schedule, such as a charge window carrying the previous cycle's target SoC, would sit on the inverter for the whole interval
 - `alphaess_startup_write_delay` - How long Predbat waits after starting or restarting before it sends charge and discharge schedules (default: `300` seconds, or five minutes). Predbat still reads your inverter during the wait. It sends the latest schedule when the wait ends and another update is due. Set to `0` to remove the wait
 - `alphaess_hold_power` - The charging power Predbat requests when it needs to stop the battery discharging (default: `100` W). It sets a 10% target, so a battery below 10% may charge up to that level. Increase this value if your inverter rejects 100 W. This setting only works if your AlphaESS system lets Predbat set charging power through the cloud
 - `alphaess_shutdown_mode` - What Predbat does when it stops normally (default: `none`). This only applies when inverter control is enabled and Predbat is not read-only:

docs/components.md

@@ -1524,7 +1524,7 @@ Integrates with AlphaESS SMILE/Storion hybrid inverters via the AlphaESS Open AP
 
 - **EXPERIMENTAL:** nobody on the Predbat project has AlphaESS hardware, so behaviour is inferred from AlphaESS's published Open API documentation and the Home Assistant AlphaESS integration rather than confirmed against real inverters. Every request and response is traced to the log (`api_debug`, on by default) with credentials redacted, so a tester can capture evidence for an issue report. Run the [diagnostics CLI](inverter-setup.md#alphaess-cloud) against your own system before trusting Predbat with control
 - **Control is on by default**, the same as `sunsynk_control_enable`. Set `alphaess_control_enable: false` for monitoring only. `switch.predbat_set_read_only` additionally holds back Predbat's own automatic writes, including its periodic re-apply
-- **Both write endpoints are documented as writable once per 24 hours.** Predbat therefore only writes when the payload actually changes, gates charge and discharge independently so one does not consume the other's budget, and paces writes with `alphaess_min_write_interval`
+- **The periodic schedule API (`setTimeChargeBySn`) supports repeated updates and is not limited to one write per day.** Once-per-day wording appears in the legacy `updateChargeConfigInfo` and `updateDisChargeConfigInfo` documentation; it must not be applied to the periodic API. Predbat only writes when the payload actually changes and uses `alphaess_min_write_interval` as local pacing to avoid unnecessary requests. Legacy charge and discharge writes are paced independently
 A schedule is committed in stages (window, then enable, then target SoC), so a small, capped number of corrections is allowed through within 60 seconds of a successful write - without it the inverter would run a schedule Predbat had already superseded until the interval expired
 - **Export cannot be controlled at all.** The Open API has no forced-export, working-mode or dispatch endpoint, and AlphaESS document the discharge window as a *permission* window - during it the system runs in self-consumption, outside it the battery may only charge - so Force Export exports nothing beyond genuine solar surplus. Freeze Export is equally undeliverable, because nothing in the API stops the battery charging from solar. Set `select.predbat_mode` to `Control charge` on these systems, and see [AlphaESS cannot be used to control export](apps-yaml.md#alphaess-cannot-be-used-to-control-export)
 - The battery percentage in a timed discharge schedule is Predbat's requested reserve, or its export target if it has planned an export window. AlphaESS has a separate minimum battery level for powering your home; set that in AlphaESS. A disabled discharge schedule may still show a battery percentage because AlphaESS requires one, but it does not set that separate level. Predbat uses a **zero** charge or discharge rate when it needs to hold the battery, because AlphaESS has no pause control
@@ -1535,6 +1535,7 @@ A schedule is committed in stages (window, then enable, then target SoC), so a s
 - Systems reporting no battery capacity (plug-in solar, such as the VT1000 family) are skipped by design - there is nothing for Predbat to control
 - A system that does not serve live power data automatically falls back to five-minute history data and re-probes itself back to live if it recovers
 - Using the AlphaESS phone app while Predbat is running can overwrite Predbat's settings, and vice versa - the charge and discharge endpoints are whole-object replacements, so the last writer wins. Predbat logs when a field it owns has changed since its last write
+- While Predbat actively controls a system, it reads schedules back every five minutes; monitoring-only and read-only installations use a thirty-minute interval. A write gets five minutes to reach the inverter before a mismatch triggers re-application, and a restart preserves that deadline. Periodic readback also checks whether the daily schedule has been changed to weekly
 - A write reaching the cloud does not mean the inverter has applied it: it collects new settings on its next poll, typically one to five minutes later
 
 #### Configuration Options (alphaess)

templates/alphaess_cloud.yaml

@@ -49,8 +49,9 @@ pred_bat:
   # inverter's nominal power (poinv). Set this if you know your pack's real limit.
   #alphaess_battery_rate_max: 3600
 
-  # Optional pacing. AlphaESS advise a minimum 10-second polling interval, and both write
-  # endpoints are documented as writable once per 24 hours.
+  # Optional pacing. AlphaESS advise a minimum 10-second polling interval.
+  # The periodic schedule API supports repeated writes, not a once-per-day limit.
+  # alphaess_min_write_interval is Predbat's local pacing, not an API-imposed daily limit.
   #alphaess_api_delay: 2
   #alphaess_min_write_interval: 300
   # Wait 5 minutes after Predbat starts before sending schedules. Monitoring continues.