feat: Added service/action for retrieveing intelligent dispatches applicable at a given point in time via local data. This is useful to determine why off peak or dispatch sensors might have turned on (4.5 hours dev time)

Author: BottlecapDave

_docs/services.md

@@ -308,6 +308,25 @@ Refreshes intelligent dispatches for a given account.
 
 For an automation example, please refer to the available [blueprint](./blueprints.md#manual-intelligent-dispatch-refreshes).
 
+### get_point_in_time_intelligent_dispatch_history
+
+Retrieve the intelligent dispatch history which was active for a given point in time based on up to the last 48 hours of intelligent dispatches that have been captured locally. This can be used to determine why [is dispatching](./entities/intelligent.md#is-dispatching) or [off peak](./entities/electricity.md#off-peak) might have turned on during a certain time period.
+
+!!! info
+
+    The OE API doesn't provide historic intelligent dispatch information, so this information is stored locally as it changes. Therefore depending on how often your dispatch information refreshes, it can take a while for data to become available.
+
+!!! note
+
+    The data that powers this service is available at `config/.storage/octopus_energy.intelligent_dispatches_history_{{DEVICE_ID}}`
+
+
+| Attribute                | Optional | Description                                                                                                           |
+| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `target.entity_id`       | `no`     | The [dispatching](./entities/intelligent.md#is-dispatching) entity that you want to refresh the content for (e.g. `binary_sensor.octopus_energy_{{DEVICE_ID}}_intelligent_dispatching`). |
+| `data.point_in_time`     | `no`     | The point in time to get the historic dispatch information that was active at the time.
+
+
 ## Miscellaneous
 
 ### octopus_energy.purge_invalid_external_statistic_ids

custom_components/octopus_energy/__init__.py

@@ -33,6 +33,7 @@
 from .storage.intelligent_device import async_load_cached_intelligent_devices, async_save_cached_intelligent_devices
 from .storage.rate_weightings import async_load_cached_rate_weightings
 from .storage.intelligent_dispatches import async_load_cached_intelligent_dispatches
+from .storage.intelligent_dispatches_history import IntelligentDispatchesHistory, async_load_cached_intelligent_dispatches_history
 from .api_client.intelligent_dispatches import IntelligentDispatches
 from .discovery import DiscoveryManager
 from .coordinators.intelligent_device import IntelligentDeviceCoordinatorResult, async_setup_intelligent_devices_coordinator
@@ -547,13 +548,15 @@ async def async_register_intelligent_devices(hass, config: dict, now: datetime,
   await async_save_cached_intelligent_devices(hass, account_id, intelligent_devices)
 
   for intelligent_device in intelligent_devices:
-
     cached_dispatches = await async_load_cached_intelligent_dispatches(hass, account_id, intelligent_device.id)
+    intelligent_dispatches_history = await async_load_cached_intelligent_dispatches_history(hass, intelligent_device.id)
+    
     if cached_dispatches is not None:
       hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES][intelligent_device.id] = IntelligentDispatchesCoordinatorResult(
         now - timedelta(hours=1),
         1,
         cached_dispatches,
+        intelligent_dispatches_history,
         0,
         now - timedelta(hours=1)
       )
@@ -597,6 +600,7 @@ async def async_register_intelligent_devices(hass, config: dict, now: datetime,
             now - timedelta(hours=1),
             1,
             IntelligentDispatches(None, [], []),
+            IntelligentDispatchesHistory([]),
             0,
             now - timedelta(hours=1)
           )

custom_components/octopus_energy/binary_sensor.py

@@ -2,9 +2,10 @@
 
 import voluptuous as vol
 
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, SupportsResponse
 from homeassistant.helpers import config_validation as cv, entity_platform, issue_registry as ir
 from homeassistant.util.dt import (utcnow)
+import homeassistant.helpers.config_validation as cv
 
 from .electricity.off_peak import OctopusEnergyElectricityOffPeak
 from .octoplus.saving_sessions import OctopusEnergySavingSessions
@@ -225,8 +226,9 @@ def get_intelligent_entities(hass, account_id: str, config: dict):
   for intelligent_device in intelligent_devices:
 
     if intelligent_device.device_type == INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLES or intelligent_device.device_type == INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLE_CHARGERS:
+      
+      platform = entity_platform.async_get_current_platform()
       if (manually_refresh_dispatches):
-        platform = entity_platform.async_get_current_platform()
         platform.async_register_entity_service(
           "refresh_intelligent_dispatches",
           vol.All(
@@ -238,6 +240,20 @@ def get_intelligent_entities(hass, account_id: str, config: dict):
           "async_refresh_dispatches"
         )
 
+      platform.async_register_entity_service(
+        "get_point_in_time_intelligent_dispatch_history",
+        vol.All(
+          cv.make_entity_service_schema(
+          {
+            vol.Required("point_in_time"): cv.datetime
+          },
+          extra=vol.ALLOW_EXTRA,
+        ),
+        ),
+        "async_get_point_in_time_intelligent_dispatch_history",
+        supports_response=SupportsResponse.ONLY
+      )
+
       coordinator = hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES_COORDINATOR.format(intelligent_device.id)]
       entities.append(OctopusEnergyIntelligentDispatching(hass, coordinator, intelligent_device, account_id, intelligent_rate_mode, manually_refresh_dispatches))
 

custom_components/octopus_energy/coordinators/intelligent_dispatches.py

@@ -28,8 +28,9 @@
 from ..api_client.intelligent_device import IntelligentDevice
 from ..storage.intelligent_dispatches import async_save_cached_intelligent_dispatches
 
-from ..intelligent import clean_previous_dispatches, has_intelligent_tariff, mock_intelligent_dispatches
+from ..intelligent import clean_intelligent_dispatch_history, clean_previous_dispatches, has_dispatches_changed, has_intelligent_tariff, mock_intelligent_dispatches
 from ..coordinators.intelligent_device import IntelligentDeviceCoordinatorResult
+from ..storage.intelligent_dispatches_history import IntelligentDispatchesHistory, async_save_cached_intelligent_dispatches_history
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -71,38 +72,17 @@ async def refresh_dispatches(self):
 
 class IntelligentDispatchesCoordinatorResult(BaseCoordinatorResult):
   dispatches: IntelligentDispatches
+  history: IntelligentDispatchesHistory
   requests_current_hour: int
   requests_current_hour_last_reset: datetime
 
-  def __init__(self, last_evaluated: datetime, request_attempts: int, dispatches: IntelligentDispatches, requests_current_hour: int, requests_current_hour_last_reset: datetime, last_error: Exception | None = None):
+  def __init__(self, last_evaluated: datetime, request_attempts: int, dispatches: IntelligentDispatches, history: IntelligentDispatchesHistory, requests_current_hour: int, requests_current_hour_last_reset: datetime, last_error: Exception | None = None):
     super().__init__(last_evaluated, request_attempts, REFRESH_RATE_IN_MINUTES_INTELLIGENT, None, last_error)
     self.dispatches = dispatches
+    self.history = history
     self.requests_current_hour = requests_current_hour
     self.requests_current_hour_last_reset = requests_current_hour_last_reset
 
-def has_dispatch_items_changed(existing_dispatches: list[SimpleIntelligentDispatchItem], new_dispatches: list[SimpleIntelligentDispatchItem]):
-  if len(existing_dispatches) != len(new_dispatches):
-    return True
-
-  if len(existing_dispatches) > 0:
-    for i in range(0, len(existing_dispatches)):
-      if (existing_dispatches[i].start != new_dispatches[i].start or
-          existing_dispatches[i].end != new_dispatches[i].end):
-        return True
-
-  return False
-
-def has_dispatches_changed(existing_dispatches: IntelligentDispatches, new_dispatches: IntelligentDispatches):
-  return (
-    existing_dispatches.current_state != new_dispatches.current_state or
-    len(existing_dispatches.completed) != len(new_dispatches.completed) or
-    has_dispatch_items_changed(existing_dispatches.completed, new_dispatches.completed) or
-    len(existing_dispatches.planned) != len(new_dispatches.planned) or
-    has_dispatch_items_changed(existing_dispatches.planned, new_dispatches.planned) or
-    len(existing_dispatches.started) != len(new_dispatches.started) or
-    has_dispatch_items_changed(existing_dispatches.started, new_dispatches.started)
-  )
-
 def merge_started_dispatches(current: datetime,
                              current_state: str,
                              started_dispatches: list[SimpleIntelligentDispatchItem],
@@ -165,6 +145,7 @@ async def async_retrieve_intelligent_dispatches(
           existing_intelligent_dispatches_result.last_evaluated,
           existing_intelligent_dispatches_result.request_attempts,
           existing_intelligent_dispatches_result.dispatches,
+          existing_intelligent_dispatches_result.history,
           existing_intelligent_dispatches_result.requests_current_hour,
           existing_intelligent_dispatches_result.requests_current_hour_last_reset,
           last_error=error
@@ -180,6 +161,7 @@ async def async_retrieve_intelligent_dispatches(
           existing_intelligent_dispatches_result.last_evaluated,
           existing_intelligent_dispatches_result.request_attempts,
           existing_intelligent_dispatches_result.dispatches,
+          existing_intelligent_dispatches_result.history,
           existing_intelligent_dispatches_result.requests_current_hour,
           existing_intelligent_dispatches_result.requests_current_hour_last_reset,
           last_error=error
@@ -216,15 +198,20 @@ async def async_retrieve_intelligent_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)
+        
+        new_history = clean_intelligent_dispatch_history(current,
+                                                         dispatches,
+                                                         existing_intelligent_dispatches_result.history.history if existing_intelligent_dispatches_result is not None else [])
 
-        return IntelligentDispatchesCoordinatorResult(current, 1, dispatches, requests_current_hour + 1, requests_last_reset)
+        return IntelligentDispatchesCoordinatorResult(current, 1, dispatches, IntelligentDispatchesHistory(new_history), requests_current_hour + 1, requests_last_reset)
 
       result = None
       if (existing_intelligent_dispatches_result is not None):
         result = IntelligentDispatchesCoordinatorResult(
           existing_intelligent_dispatches_result.last_evaluated,
           existing_intelligent_dispatches_result.request_attempts + 1,
           existing_intelligent_dispatches_result.dispatches,
+          existing_intelligent_dispatches_result.history,
           existing_intelligent_dispatches_result.requests_current_hour + 1,
           existing_intelligent_dispatches_result.requests_current_hour_last_reset,
           last_error=raised_exception
@@ -234,7 +221,15 @@ async def async_retrieve_intelligent_dispatches(
           _LOGGER.warning(f"Failed to retrieve new dispatches - using cached dispatches. See diagnostics sensor for more information.")
       else:
         # We want to force into our fallback mode
-        result = IntelligentDispatchesCoordinatorResult(current - timedelta(minutes=REFRESH_RATE_IN_MINUTES_INTELLIGENT), 2, None, requests_current_hour, requests_last_reset, last_error=raised_exception)
+        result = IntelligentDispatchesCoordinatorResult(
+          current - timedelta(minutes=REFRESH_RATE_IN_MINUTES_INTELLIGENT),
+          2,
+          None,
+          IntelligentDispatchesHistory([]),
+          requests_current_hour,
+          requests_last_reset,
+          last_error=raised_exception
+        )
         _LOGGER.warning(f"Failed to retrieve new dispatches. See diagnostics sensor for more information.")
 
       return result
@@ -253,6 +248,7 @@ async def async_refresh_intelligent_dispatches(
   is_manual_refresh: bool,
   planned_dispatches_supported: bool,
   async_save_dispatches: Callable[[IntelligentDispatches], Awaitable[list]],
+  async_save_dispatches_history: Callable[[IntelligentDispatchesHistory], Awaitable[list]],
 ):
   result = await async_retrieve_intelligent_dispatches(
     current,
@@ -282,10 +278,17 @@ async def async_refresh_intelligent_dispatches(
         existing_intelligent_dispatches_result.dispatches is None or
         has_dispatches_changed(existing_intelligent_dispatches_result.dispatches, result.dispatches)):
       await async_save_dispatches(result.dispatches)
+      await async_save_dispatches_history(result.history)
 
   return result
 
-async def async_setup_intelligent_dispatches_coordinator(hass, account_id: str, device_id: str, mock_intelligent_data: bool, manual_dispatch_refreshes: bool, planned_dispatches_supported: bool):
+async def async_setup_intelligent_dispatches_coordinator(
+    hass,
+    account_id: str,
+    device_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."""
     # Request our account data to be refreshed
@@ -304,17 +307,22 @@ async def async_update_intelligent_dispatches_data(is_manual_refresh = False):
     client: OctopusEnergyApiClient = hass.data[DOMAIN][account_id][DATA_CLIENT]
     account_result = hass.data[DOMAIN][account_id][DATA_ACCOUNT]
     account_info = account_result.account if account_result is not None else None
+    existing_intelligent_dispatches_result = (hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES][device_id]
+                                              if DATA_INTELLIGENT_DISPATCHES in hass.data[DOMAIN][account_id] and
+                                              device_id in hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES] 
+                                              else None)
 
     hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES][device_id] = await async_refresh_intelligent_dispatches(
       current,
       client,
       account_info,
       intelligent_device,
-      hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES][device_id] if DATA_INTELLIGENT_DISPATCHES in hass.data[DOMAIN][account_id] and device_id in hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES] else None,
+      existing_intelligent_dispatches_result,
       mock_intelligent_data,
       is_manual_refresh,
       planned_dispatches_supported,
-      lambda dispatches: async_save_cached_intelligent_dispatches(hass, device_id, dispatches)
+      lambda dispatches: async_save_cached_intelligent_dispatches(hass, device_id, dispatches),
+      lambda history: async_save_cached_intelligent_dispatches_history(hass, device_id, history)
     )
 
     return hass.data[DOMAIN][account_id][DATA_INTELLIGENT_DISPATCHES][device_id]

custom_components/octopus_energy/icons.json

@@ -14,6 +14,7 @@
         "boost_heat_pump_zone": "mdi:thermometer-plus",
         "boost_water_heater": "mdi:thermometer-plus",
         "set_heat_pump_flow_temp_config": "mdi:heat-pump",
-        "refresh_intelligent_dispatches": "mdi:refresh"
+        "refresh_intelligent_dispatches": "mdi:refresh",
+        "get_point_in_time_intelligent_dispatch_history": "mdi:history"
     }
 }

custom_components/octopus_energy/intelligent/__init__.py

@@ -8,6 +8,7 @@
 
 from ..const import CONFIG_MAIN_INTELLIGENT_RATE_MODE_PLANNED_AND_STARTED_DISPATCHES, INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLE_CHARGERS, INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLES, INTELLIGENT_SOURCE_BUMP_CHARGE_OPTIONS, INTELLIGENT_SOURCE_SMART_CHARGE_OPTIONS, REFRESH_RATE_IN_MINUTES_INTELLIGENT
 
+from ..storage.intelligent_dispatches_history import IntelligentDispatchesHistory, IntelligentDispatchesHistoryItem
 from ..api_client.intelligent_settings import IntelligentSettings
 from ..api_client.intelligent_dispatches import IntelligentDispatchItem, IntelligentDispatches, SimpleIntelligentDispatchItem
 from ..api_client.intelligent_device import IntelligentDevice
@@ -266,6 +267,38 @@ def clean_previous_dispatches(time: datetime, dispatches: list[IntelligentDispat
 
   return list(new_dispatches.values())
 
+def clean_intelligent_dispatch_history(time: datetime,
+                                       dispatches: IntelligentDispatches,
+                                       history: list[IntelligentDispatchesHistoryItem]) -> list[IntelligentDispatchItem]:
+  history.sort(key = lambda x: x.timestamp)
+
+  new_history: list[IntelligentDispatchesHistoryItem] = []
+  previous_history_item: IntelligentDispatchesHistoryItem | None = None
+  min_time = time - timedelta(days=2)
+  
+  for history_item in history:
+
+    if history_item.timestamp >= min_time:
+      # Ensure we have one record before the minimum stored time so we know what we had at the start
+      if (len(new_history) == 0 and previous_history_item is not None):
+        new_history.append(previous_history_item)
+
+      new_history.append(history_item)
+
+    previous_history_item = history_item
+
+  # Ensure we have one record before the minimum stored time so we know what we had at the start
+  if (len(new_history) == 0 and previous_history_item is not None):
+    new_history.append(previous_history_item)
+
+  if len(new_history) < 1 or has_dispatches_changed(new_history[-1].dispatches, dispatches):
+    new_history.append(IntelligentDispatchesHistoryItem(
+      time,
+      dispatches)
+    )
+
+  return new_history
+
 def dictionary_list_to_dispatches(dispatches: list):
   items = []
   if (dispatches is not None):
@@ -370,4 +403,37 @@ def device_type_to_friendly_string(device_type: str) -> str:
   elif device_type == INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLES:
     return "Electric Vehicle"
   else:
-    return device_type
+    return device_type
+  
+def has_dispatch_items_changed(existing_dispatches: list[SimpleIntelligentDispatchItem], new_dispatches: list[SimpleIntelligentDispatchItem]):
+  if len(existing_dispatches) != len(new_dispatches):
+    return True
+
+  if len(existing_dispatches) > 0:
+    for i in range(0, len(existing_dispatches)):
+      if (existing_dispatches[i].start != new_dispatches[i].start or
+          existing_dispatches[i].end != new_dispatches[i].end):
+        return True
+
+  return False
+  
+def has_dispatches_changed(existing_dispatches: IntelligentDispatches, new_dispatches: IntelligentDispatches):
+  return (
+    existing_dispatches.current_state != new_dispatches.current_state or
+    has_dispatch_items_changed(existing_dispatches.completed, new_dispatches.completed) or
+    has_dispatch_items_changed(existing_dispatches.planned, new_dispatches.planned) or
+    has_dispatch_items_changed(existing_dispatches.started, new_dispatches.started)
+  )
+
+def get_applicable_intelligent_dispatch_history(history: IntelligentDispatchesHistory, time: datetime) -> IntelligentDispatchesHistoryItem  | None:
+  if history is None or history.history is None or len(history.history) == 0:
+    return None
+
+  applicable_history_item: IntelligentDispatchesHistoryItem | None = None
+  for history_item in history.history:
+    if history_item.timestamp <= time:
+      applicable_history_item = history_item
+    else:
+      break
+
+  return applicable_history_item