feat: Updated action to retrieve dispatches based on point in time ((1.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/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,16 +240,19 @@ def get_intelligent_entities(hass, account_id: str, config: dict):
           "async_refresh_dispatches"
         )
 
-        platform.async_register_entity_service(
-          "get_intelligent_dispatch_history",
-          vol.All(
-            cv.make_entity_service_schema(
-              {},
-              extra=vol.ALLOW_EXTRA,
-            ),
-          ),
-          "async_get_intelligent_dispatch_history"
-        )
+      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

@@ -330,13 +330,17 @@ 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,

custom_components/octopus_energy/icons.json

@@ -15,6 +15,6 @@
         "boost_water_heater": "mdi:thermometer-plus",
         "set_heat_pump_flow_temp_config": "mdi:heat-pump",
         "refresh_intelligent_dispatches": "mdi:refresh",
-        "get_intelligent_dispatch_history": "mdi:history"
+        "get_point_in_time_intelligent_dispatch_history": "mdi:history"
     }
 }

custom_components/octopus_energy/intelligent/__init__.py

@@ -404,4 +404,17 @@ 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 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

custom_components/octopus_energy/intelligent/dispatching.py

@@ -1,5 +1,7 @@
+from datetime import datetime
 import logging
 
+from custom_components.octopus_energy.const import DOMAIN
 from homeassistant.const import (
     STATE_UNAVAILABLE,
     STATE_UNKNOWN,
@@ -8,7 +10,7 @@
 from homeassistant.helpers.entity import generate_entity_id
 from homeassistant.exceptions import ServiceValidationError
 
-from homeassistant.util.dt import (utcnow)
+from homeassistant.util.dt import (utcnow, as_local)
 from homeassistant.components.binary_sensor import (
     BinarySensorEntity,
 )
@@ -17,6 +19,7 @@
 from ..intelligent import (
   dispatches_to_dictionary_list,
   get_applicable_dispatch_periods,
+  get_applicable_intelligent_dispatch_history,
   get_current_and_next_dispatching_periods,
   simple_dispatches_to_dictionary_list
 )
@@ -158,10 +161,31 @@ async def async_refresh_dispatches(self):
       raise ServiceValidationError(result.last_error)
 
   @callback
-  async def async_get_intelligent_dispatch_history(self):
+  async def async_get_point_in_time_intelligent_dispatch_history(self, point_in_time: datetime):
     """Refresh dispatches"""
+    local_point_in_time = as_local(point_in_time)
     result: IntelligentDispatchesCoordinatorResult = await self.coordinator.refresh_dispatches()
-    if result is not None:
-      return result.history.to_dict()
+    applicable_dispatches = get_applicable_intelligent_dispatch_history(result.history if result is not None else None, local_point_in_time)
+    if applicable_dispatches is not None:
+      return applicable_dispatches.to_dict()
 
-    return []
+    earliest_timestamp = (as_local(result.history.history[0].timestamp).isoformat()
+                          if result is not None and
+                          result.history is not None and
+                          result.history.history is not None and
+                          len(result.history.history) > 0 
+                          else None)
+    
+    if earliest_timestamp is not None:
+      raise ServiceValidationError(
+        translation_domain=DOMAIN,
+        translation_key="point_in_time_intelligent_dispatch_history_data_out_of_bounds",
+        translation_placeholders={ 
+          "earliest_timestamp": earliest_timestamp,
+        },
+      )
+    
+    raise ServiceValidationError(
+        translation_domain=DOMAIN,
+        translation_key="point_in_time_intelligent_dispatch_history_data_unavailable",
+      )

custom_components/octopus_energy/services.yaml

@@ -391,10 +391,17 @@ refresh_intelligent_dispatches:
       integration: octopus_energy
       domain: binary_sensor
 
-get_intelligent_dispatch_history:
-  name: Get intelligent dispatch history
-  description: Retrieve the history for up to the last 48 hours of intelligent dispatches that have been captured locally. For more information please see https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/services/#octopus_energyget_intelligent_dispatch_history.
+get_point_in_time_intelligent_dispatch_history:
+  name: Get point in time intelligent dispatch history
+  description:
+    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. For more information please see https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/services/#octopus_energyget_intelligent_dispatch_history.
   target:
     entity:
       integration: octopus_energy
-      domain: binary_sensor
+      domain: binary_sensor
+  fields:
+    point_in_time:
+      name: Point in time
+      description: The datetime of the point in time to retrieve the application intelligent dispatch history for
+      selector:
+        datetime:

custom_components/octopus_energy/storage/intelligent_dispatches_history.py

@@ -36,7 +36,7 @@ def __init__(self, history: list[IntelligentDispatchesHistoryItem]):
   def from_dict(data: dict):
     history = []
     for item in data["history"]:
-      history.append(IntelligentDispatches.from_dict(item))
+      history.append(IntelligentDispatchesHistoryItem.from_dict(item))
 
     return IntelligentDispatchesHistory(history)
 

custom_components/octopus_energy/translations/en.json

@@ -341,6 +341,12 @@
     },
     "invalid_rate_weightings": {
       "message": "{error}"
+    },
+    "point_in_time_intelligent_dispatch_history_data_out_of_bounds": {
+      "message": "The requested point in time is before historic data is available. The earliest available intelligent dispatch data is from {earliest_timestamp}"
+    },
+    "point_in_time_intelligent_dispatch_history_data_unavailable": {
+      "message": "No intelligent dispatch data is currently available. This will refresh automatically over time when intelligent dispatches are updated."
     }
   },
   "issues": {