feat: Updated started dispatch calculation to be more forgiving on how stale the data is. A planned dispatch will only transition to a started dispatch if data has been retrieved within the last 3 minutes (1 hour dev time)

Author: BottlecapDave

_docs/entities/intelligent.md

@@ -30,7 +30,7 @@ This sensor is used to determine if you're currently in a planned dispatch perio
 |-----------|------|-------------|
 | `planned_dispatches` | `array` | An array of the dispatches that are currently planned by Octopus Energy. |
 | `completed_dispatches` | `array` | An array of the dispatches that have been completed by Octopus Energy. This will only store up to the last 3 days worth of completed dispatches. |
-| `started_dispatches` | `array` | An array of the dispatches that have been planned by Octopus Energy and upon API refresh are still planned when the current 30 minute period started and is not in a boosting state. A planned dispatch will be added one 30 minute period at a time. This will only store up to the last 3 days worth of started dispatches. This is used to determine historic off peak rates. For example if you have a planned dispatch of `2025-04-01T10:00:00`-`2025-04-01T11:00:00`, at `2025-04-01T10:01:00` if the planned dispatch is still available the period of `2025-04-01T10:00:00`-`2025-04-01T10:30:00` will be added. |
+| `started_dispatches` | `array` | An array of the dispatches that have been planned by Octopus Energy and upon API refresh are still planned when the current 30 minute period has started, is not in a boosting state and the data has been refreshed within the last 3 minutes. A planned dispatch will be added one 30 minute period at a time. This will only store up to the last 3 days worth of started dispatches. This is used to determine historic off peak rates. For example if you have a planned dispatch of `2025-04-01T10:00:00`-`2025-04-01T11:00:00`, at `2025-04-01T10:01:00` if the planned dispatch is still available the period of `2025-04-01T10:00:00`-`2025-04-01T10:30:00` will be added. |
 | `provider` | `string` | The provider of the intelligent features |
 | `vehicle_battery_size_in_kwh` | `float` | The size of the target vehicle battery in kWh. |
 | `charge_point_power_in_kw` | `float` | The power of the charge point battery in kW. |

custom_components/octopus_energy/coordinators/intelligent_dispatches.py

@@ -109,7 +109,10 @@ def has_dispatches_changed(existing_dispatches: IntelligentDispatches, new_dispa
     )
   )
 
-def merge_started_dispatches(current: datetime, current_state: str, started_dispatches: list[SimpleIntelligentDispatchItem], planned_dispatches: list[IntelligentDispatchItem]):
+def merge_started_dispatches(current: datetime,
+                             current_state: str,
+                             started_dispatches: list[SimpleIntelligentDispatchItem],
+                             planned_dispatches: list[IntelligentDispatchItem]):
   new_started_dispatches = clean_previous_dispatches(current, started_dispatches)
 
   if current_state == "SMART_CONTROL_IN_PROGRESS":
@@ -137,7 +140,7 @@ def merge_started_dispatches(current: datetime, current_state: str, started_disp
 
   return new_started_dispatches
 
-async def async_refresh_intelligent_dispatches(
+async def async_retrieve_intelligent_dispatches(
   current: datetime,
   client: OctopusEnergyApiClient,
   account_info,
@@ -146,7 +149,6 @@ async def async_refresh_intelligent_dispatches(
   is_data_mocked: bool,
   is_manual_refresh: bool,
   planned_dispatches_supported: bool,
-  async_save_dispatches: Callable[[str, IntelligentDispatches], Awaitable[list]],
 ):
   requests_current_hour = existing_intelligent_dispatches_result.requests_current_hour if existing_intelligent_dispatches_result is not None else 0
   requests_last_reset = existing_intelligent_dispatches_result.requests_current_hour_last_reset if existing_intelligent_dispatches_result is not None else current
@@ -208,18 +210,8 @@ async def async_refresh_intelligent_dispatches(
         dispatches.planned.clear()
 
       if dispatches is not None:
-        dispatches.completed = clean_previous_dispatches(utcnow(), (existing_intelligent_dispatches_result.dispatches.completed if existing_intelligent_dispatches_result is not None and existing_intelligent_dispatches_result.dispatches is not None and existing_intelligent_dispatches_result.dispatches.completed is not None else []) + dispatches.completed)
-        dispatches.started = merge_started_dispatches(current,
-                                                      dispatches.current_state,
-                                                      existing_intelligent_dispatches_result.dispatches.started 
-                                                      if existing_intelligent_dispatches_result is not None and existing_intelligent_dispatches_result.dispatches is not None and  existing_intelligent_dispatches_result.dispatches.started is not None
-                                                      else [],
-                                                      dispatches.planned)
-
-        if (existing_intelligent_dispatches_result is None or
-            existing_intelligent_dispatches_result.dispatches is None or
-            has_dispatches_changed(existing_intelligent_dispatches_result.dispatches, dispatches)):
-          await async_save_dispatches(account_id, dispatches)
+        dispatches.completed = clean_previous_dispatches(current,
+                                                         (existing_intelligent_dispatches_result.dispatches.completed if existing_intelligent_dispatches_result is not None and existing_intelligent_dispatches_result.dispatches is not None and existing_intelligent_dispatches_result.dispatches.completed is not None else []) + dispatches.completed)
 
         return IntelligentDispatchesCoordinatorResult(current, 1, dispatches, requests_current_hour + 1, requests_last_reset)
 
@@ -245,6 +237,48 @@ async def async_refresh_intelligent_dispatches(
 
   return existing_intelligent_dispatches_result
 
+async def async_refresh_intelligent_dispatches(
+  current: datetime,
+  client: OctopusEnergyApiClient,
+  account_info,
+  intelligent_device: IntelligentDevice,
+  existing_intelligent_dispatches_result: IntelligentDispatchesCoordinatorResult,
+  is_data_mocked: bool,
+  is_manual_refresh: bool,
+  planned_dispatches_supported: bool,
+  async_save_dispatches: Callable[[str, IntelligentDispatches], Awaitable[list]],
+):
+  result = await async_retrieve_intelligent_dispatches(
+    current,
+    client,
+    account_info,
+    intelligent_device,
+    existing_intelligent_dispatches_result,
+    is_data_mocked,
+    is_manual_refresh,
+    planned_dispatches_supported
+  )
+
+  if result is not None and result.dispatches is not None:
+    if result.last_retrieved < (current - timedelta(minutes=REFRESH_RATE_IN_MINUTES_INTELLIGENT)):
+      _LOGGER.debug('Skipping started dispatches processing as data has not been refreshed recently')
+      # If we haven't refreshed recently, then we can't accurately process started dispatches
+      return result
+    
+    result.dispatches.started = merge_started_dispatches(current,
+                                                         result.dispatches.current_state,
+                                                         existing_intelligent_dispatches_result.dispatches.started 
+                                                         if existing_intelligent_dispatches_result is not None and existing_intelligent_dispatches_result.dispatches is not None and  existing_intelligent_dispatches_result.dispatches.started is not None
+                                                         else [],
+                                                         result.dispatches.planned)
+
+    if (existing_intelligent_dispatches_result is None or
+        existing_intelligent_dispatches_result.dispatches is None or
+        has_dispatches_changed(existing_intelligent_dispatches_result.dispatches, result.dispatches)):
+      await async_save_dispatches(account_info["id"], result.dispatches)
+
+  return result
+
 async def async_setup_intelligent_dispatches_coordinator(hass, account_id: str, mock_intelligent_data: bool, manual_dispatch_refreshes: bool, planned_dispatches_supported: bool):
   async def async_update_intelligent_dispatches_data(is_manual_refresh = False):
     """Fetch data from API endpoint."""

tests/unit/coordinators/test_async_refresh_intelligent_dispatches.py

@@ -283,6 +283,64 @@ async def async_save_dispatches(*args, **kwargs):
     assert save_dispatches_account_id == None
     assert save_dispatches_dispatches == None
 
+@pytest.mark.asyncio
+async def test_when_existing_dispatches_returned_and_planned_dispatch_started_and_refreshed_recently_then_started_dispatches_updated():
+  current = datetime.strptime("2023-07-14T10:30:01+01:00", "%Y-%m-%dT%H:%M:%S%z")
+  expected_dispatches = IntelligentDispatches("SMART_CONTROL_IN_PROGRESS", [], [])
+  mock_api_called = False
+  async def async_mock_get_intelligent_dispatches(*args, **kwargs):
+    nonlocal mock_api_called
+    mock_api_called = True
+    return expected_dispatches
+  
+  save_dispatches_called = False
+  save_dispatches_account_id = None
+  save_dispatches_dispatches = None
+  async def async_save_dispatches(*args, **kwargs):
+    nonlocal save_dispatches_called, save_dispatches_account_id, save_dispatches_dispatches
+    save_dispatches_called = True
+    account_id, dispatches = args
+    save_dispatches_account_id = account_id
+    save_dispatches_dispatches = dispatches
+  
+  account_info = get_account_info()
+  existing_dispatches = IntelligentDispatchesCoordinatorResult(current - timedelta(minutes=2), 1, mock_intelligent_dispatches(), 1, last_retrieved)
+  existing_dispatches.dispatches.current_state = "SMART_CONTROL_IN_PROGRESS"
+  existing_dispatches.dispatches.planned = [
+    IntelligentDispatchItem(
+      current - timedelta(minutes=1),
+      current + timedelta(minutes=45),
+      1.1,
+      None,
+      "home"
+    )
+  ]
+  
+  with mock.patch.multiple(OctopusEnergyApiClient, async_get_intelligent_dispatches=async_mock_get_intelligent_dispatches):
+    client = OctopusEnergyApiClient("NOT_REAL")
+    retrieved_dispatches: IntelligentDispatchesCoordinatorResult = await async_refresh_intelligent_dispatches(
+      current,
+      client,
+      account_info,
+      intelligent_device,
+      existing_dispatches,
+      False,
+      False,
+      True,
+      async_save_dispatches
+    )
+
+    assert mock_api_called == False
+    assert retrieved_dispatches == existing_dispatches
+
+    assert len(retrieved_dispatches.dispatches.started) == 1
+    assert retrieved_dispatches.dispatches.started[0].start == current.replace(second=0, microsecond=0)
+    assert retrieved_dispatches.dispatches.started[0].end == current.replace(second=0, microsecond=0) + timedelta(minutes=30)
+
+    assert save_dispatches_called == False
+    assert save_dispatches_account_id == None
+    assert save_dispatches_dispatches == None
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize("existing_dispatches",[
   (None),