feat: Added raising of target timeframe data source events (2 hours dev time)

Author: BottlecapDave

_docs/migrations/target_timeframes.md

@@ -12,21 +12,33 @@ The first thing you need to do is install the new integration. Full instructions
 
 Once installed, you'll need to configure the integration by setting up a data source that represents data coming from this integration. This can be done by [following the link](https://my.home-assistant.io/redirect/config_flow_start/?domain=target_timeframes) or navigating to your integrations view, clicking 'Add integration' and searching for 'Target Timeframes'. You'll need a data source for each of your meters you want to create target rate sensors for (e.g. one for import and one for export).
 
-The recommended name is `Octopus Energy Import` and the recommended source id is `octopus_energy_import`, but you can pick whatever you want as long as it's unique within the integration.
+The recommended name is `Octopus Energy Import`.
+
+The recommended source id will depend on if you're wanting to just consume the rates straight from this integration, or if you want the target timeframe sensors to also include other additional/external data (e.g. carbon intensity or free electricity sessions).
+
+### I just want OE rate data
+
+The source id should follow the following format `octopus_energy_<<METER MPAN OR MPRN>>_<<METER SERIAL NUMBER>>`, depending on which meter you want the rate information to come from. For example if you want your target timeframes to be powered by your import meter with an MPAN of `123` and serial number of `ABC`, then your data source id should be equal to `octopus_energy_123_ABC`. 
+
+Once rate information is retrieved by this integration, data should flow automatically into this data source. You can confirm this by looking at the [Data Source Last Updated entity](bottlecapdave.github.io/HomeAssistant-TargetTimeframes/setup/data_source/#data-source-last-updated).
+
+### I want OE rate data as well as other data
+
+The recommended source id is `octopus_energy_import`, but you can pick whatever you want as long as it's unique within the integration and not equal to `octopus_energy_<<METER MPAN OR MPRN>>_<<METER SERIAL NUMBER>>`
 
 ![Data Source window](../assets/target_timeframes_data_source.png)
 
-## Configuring Octopus Energy data
+#### Configuring data
 
 Next, we'll need to get data from the Octopus Energy integration into the Target Timeframes integration. The recommended approach is an automation based on one of the [available blueprints](https://bottlecapdave.github.io/HomeAssistant-TargetTimeframes/blueprints/#octopus-energy). 
 
 There are different blueprints available depending upon whether you want your target rate sensors to take account of just carbon intensity, just Octopus rates, or both. For target rate sensors that use Octopus rates there are different blueprints depending upon whether you want to take account of Octopus free electricity sessions or not.
 
-Select the blueprint you want to use and click 'Install blueprint'.  You will get a prompt to open a page in Home Assistant, click 'Open link', you'll get a second prompt to confirm you want to import the blueprint, click 'Preview blueprint' then 'Import blueprint' and the blueprint will be installed in your Home Assistant.
+Select the blueprint you want to use and click 'Install blueprint'. You will get a prompt to open a page in Home Assistant, click 'Open link', you'll get a second prompt to confirm you want to import the blueprint, click 'Preview blueprint' then 'Import blueprint' and the blueprint will be installed in your Home Assistant.
 
-Next you need to create an automation using the blueprint you just imported.  The automation will track when the rate entities within the Octopus Energy integration are updated and will then transform the rate data into the shape required by Target Timeframes and use the available service to add the rate data with the data source we just created. Each `value` in Target Timeframes will represent our rate in pounds/pence.
+Next you need to create an automation using the blueprint you just imported. The automation will track when the rate entities within the Octopus Energy integration are updated and will then transform the rate data into the shape required by Target Timeframes and use the available service to add the rate data with the data source we just created. Each `value` in Target Timeframes will represent our rate in pounds/pence.
 
-Click the name of the blueprint you just imported.  You'll be prompted to configure the blueprint with the names of your Octopus Integration sensors. Use the dropdowns to select the appropriate Home Assistant sensor or event name:
+Click the name of the blueprint you just imported. You'll be prompted to configure the blueprint with the names of your Octopus Integration sensors. Use the dropdowns to select the appropriate Home Assistant sensor or event name:
 
 ![Blueprint configuration](../assets/target_timeframes_blueprint.png)
 

custom_components/octopus_energy/const.py

@@ -151,6 +151,9 @@
 EVENT_NEW_FREE_ELECTRICITY_SESSION = "octopus_energy_new_octoplus_free_electricity_session"
 EVENT_ALL_FREE_ELECTRICITY_SESSIONS = "octopus_energy_all_octoplus_free_electricity_sessions"
 
+EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE = "target_timeframe_update_data_source"
+EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE_ID = "octopus_energy_{}_{}"
+
 REPAIR_UNIQUE_RATES_CHANGED_KEY = "electricity_unique_rates_updated_{}"
 REPAIR_INVALID_API_KEY = "invalid_api_key_{}"
 REPAIR_ACCOUNT_NOT_FOUND = "account_not_found_{}"

custom_components/octopus_energy/coordinators/__init__.py

@@ -11,11 +11,12 @@
 
 from ..utils import (
   Tariff,
-  get_active_tariff
+  get_active_tariff,
+  private_rates_to_target_timeframe_data
 )
 from ..utils.rate_information import get_min_max_average_rates
 from ..utils.requests import calculate_next_refresh
-from ..const import DOMAIN, REPAIR_TARIFF_RATES_EMPTY
+from ..const import DOMAIN, EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE, EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE_ID, REPAIR_TARIFF_RATES_EMPTY
 from ..utils.repairs import safe_repair_key
 
 _LOGGER = logging.getLogger(__name__)
@@ -110,9 +111,15 @@ def raise_rate_events(current_datetime: datetime,
   (old_previous_rates, old_current_rates, old_next_rates) = __rates_to_current_previous_next_rates(previous_datetime, previous_rates)
   (new_previous_rates, new_current_rates, new_next_rates) = __rates_to_current_previous_next_rates(current_datetime, new_rates)
 
-  __raise_rate_event(previous_event_key, new_previous_rates, old_previous_rates, additional_attributes, fire_event)
-  __raise_rate_event(current_event_key, new_current_rates, old_current_rates, additional_attributes, fire_event)
-  __raise_rate_event(next_event_key, new_next_rates, old_next_rates, additional_attributes, fire_event)
+  previous_event_raised = __raise_rate_event(previous_event_key, new_previous_rates, old_previous_rates, additional_attributes, fire_event)
+  current_event_raised = __raise_rate_event(current_event_key, new_current_rates, old_current_rates, additional_attributes, fire_event)
+  next_event_raised = __raise_rate_event(next_event_key, new_next_rates, old_next_rates, additional_attributes, fire_event)
+
+  if (previous_event_raised or current_event_raised or next_event_raised):
+    fire_event(EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE, { 
+      "data_source_id": EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE_ID.format(additional_attributes["mpan"] if "mpan" in additional_attributes else additional_attributes["mprn"], additional_attributes["serial_number"]),
+      "data": private_rates_to_target_timeframe_data(new_rates) 
+    })
 
 def get_electricity_meter_tariff(current: datetime, account_info, target_mpan: str, target_serial_number: str):
   if len(account_info["electricity_meter_points"]) > 0:

custom_components/octopus_energy/utils/__init__.py

@@ -163,3 +163,25 @@ def private_rates_to_public_rates(rates: list):
     new_rates.append(new_rate)
 
   return new_rates
+
+def private_rates_to_target_timeframe_data(rates: list):
+  new_rates = []
+
+  for rate in rates:
+    metadata = {}
+    if "is_capped" in rate:
+      metadata["is_capped"] = rate["is_capped"]
+      
+    if "is_intelligent_adjusted" in rate:
+      metadata["is_intelligent_adjusted"] = rate["is_intelligent_adjusted"]
+
+    new_rate = {
+      "start": as_local(rate["start"]),
+      "end": as_local(rate["end"]),
+      "value": rate["value_inc_vat"],
+      "metadata": metadata
+    }
+
+    new_rates.append(new_rate)
+
+  return new_rates

tests/unit/coordinators/__init__.py

@@ -0,0 +1,14 @@
+from custom_components.octopus_energy.const import EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE
+
+
+def assert_raised_target_timeframe_update_event(raised_events: dict, expected_rates: list, expected_serial_number: str, expected_mpan_or_mprn: str):
+  assert EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE in raised_events
+  assert "data_source_id" in raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]
+  assert raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]["data_source_id"] == f"octopus_energy_{expected_mpan_or_mprn}_{expected_serial_number}"
+  assert "data" in raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]
+  assert len(raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]["data"]) == len(expected_rates)
+
+  for (index, rate) in enumerate(expected_rates):
+    assert raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]["data"][index]["start"] == rate["start"]
+    assert raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]["data"][index]["end"] == rate["end"]
+    assert raised_events[EVENT_TARGET_TIMEFRAME_UPDATE_DATA_SOURCE]["data"][index]["value"] == round(rate["value_inc_vat"] / 100, 6)