Merge pull request #5010 from TCWORLD/octopus-lead-hours

Add Lead Hours Configuration for Octopus Saving Session Auto Join

Author: springfall2008

apps/predbat/config.py

@@ -889,6 +889,18 @@
         "type": "switch",
         "default": True,
     },
+    {
+        "name": "octopus_saving_auto_join_lead_hours",
+        "friendly_name": "Octopus Saving Session Auto Join Lead Time",
+        "type": "input_number",
+        "min": 0,
+        "max": 12,
+        "step": 1,
+        "unit": "hours",
+        "icon": "mdi:clock-end",
+        "enable": "octopus_saving_auto_join",
+        "default": 0,
+    },
     {
         "name": "octopus_intelligent_ignore_unplugged",
         "friendly_name": "Ignore Intelligent slots when car is unplugged",

apps/predbat/octopus.py

@@ -3844,6 +3844,7 @@ def fetch_octopus_sessions(self, axle_sessions=None):
             saving_rate = 200  # Default rate if not reported
             octopoints_per_penny = self.get_arg("octopus_saving_session_octopoints_per_penny", 8)  # Default 8 octopoints per penny
             octopoints_min_threshold = self.get_arg("octopus_saving_session_min_octopoints_per_kwh", 0)
+            join_lead_hours = self.get_arg("octopus_saving_auto_join_lead_hours", 0)
 
             joined_events = []
             available_events = []
@@ -3910,6 +3911,10 @@ def fetch_octopus_sessions(self, axle_sessions=None):
                         if self._saving_event_conflicts_axle(start_time, end_time, axle_sessions):
                             self.log("Octopus: Skipping saving event code {} {}-{} - conflicts with an Axle VPP session".format(code, start_time.strftime("%a %d/%m %H:%M"), end_time.strftime("%H:%M")))
                             continue
+                        # If a lead hours is set, skip joining session until we are within that many hours of the start time
+                        if join_lead_hours and (start_time - timedelta(hours=join_lead_hours)) > self.now_utc:
+                            self.log("Octopus: Delaying join of saving event code {} {}-{} - not within configured lead hours ({}) of start of event".format(code, start_time.strftime("%a %d/%m %H:%M"), end_time.strftime("%H:%M"), join_lead_hours))
+                            continue
                         if code:  # Join the new Octopus saving event and send an alert if successfully joined
                             self.log("Octopus: Joining Octopus saving event code {} {}-{} at rate {} p/kWh".format(code, start_time.strftime("%a %d/%m %H:%M"), end_time.strftime("%H:%M"), saving_rate))
                             entity_id_join = self.get_arg("octopus_saving_session_join", indirect=False)

apps/predbat/tests/test_saving_session.py

@@ -9,7 +9,7 @@
 # pylint: disable=attribute-defined-outside-init
 import yaml
 import json
-from datetime import timedelta
+from datetime import timedelta, datetime
 from ha import run_async
 
 
@@ -1035,6 +1035,11 @@ def test_saving_session_auto_join_toggle(my_predbat):
     tz_offset = int(my_predbat.midnight_utc.tzinfo.utcoffset(my_predbat.midnight_utc).total_seconds() / 3600)
     tz_offset = f"{tz_offset:02d}"
 
+    # Use a fixed time reference before event to allow testing of pre-event lead hours.
+    original_now_utc = my_predbat.now_utc
+    now = datetime.fromisoformat(f"{date_today}T15:45:00+{tz_offset}:00")
+    my_predbat.now_utc = now
+
     session_binary = f"""
 state: off
 current_joined_event_start: null
@@ -1094,7 +1099,7 @@ def setup_items():
     else:
         print("  PASS: Join skipped when octopus_saving_auto_join is False")
 
-    # Test 2: auto-join enabled -> join proceeds
+    # Test 2: auto-join enabled, lead-hours unset default -> join proceeds
     print("  Test 2: octopus_saving_auto_join=True allows the join")
     setup_items()
     my_predbat.expose_config("octopus_saving_auto_join", True, quiet=True)
@@ -1111,11 +1116,82 @@ def setup_items():
     else:
         print("  PASS: Join proceeds when octopus_saving_auto_join is True")
 
-    if not failed:
-        print("PASS: All auto-join toggle tests passed")
+    # Test 3: auto-join disabled, event within configured lead hours -> no join
+    print("  Test 3: octopus_saving_auto_join=False blocks the join despite time before event < octopus_saving_auto_join_lead_hours.")
+    setup_items()
+    my_predbat.expose_config("octopus_saving_auto_join", False, quiet=True)
+    my_predbat.expose_config("octopus_saving_auto_join_lead_hours", 3, quiet=True)
+    ha.service_store_enable = True
+    ha.service_store = []
+    my_predbat.fetch_octopus_sessions()
+    service_result = ha.get_service_store()
+    ha.service_store_enable = False
+
+    join_calls = [svc for svc in service_result if "join" in svc[0]]
+    if join_calls:
+        print(f"ERROR: Expected no join when auto-join disabled, got {join_calls}")
+        failed = True
+    else:
+        print("  PASS: Join skipped when octopus_saving_auto_join is False")
+
+    # Test 4: auto-join enabled, lead hours set to 0 (immediate) -> join proceeds
+    print("  Test 4: octopus_saving_auto_join=True with octopus_saving_auto_join_lead_hours=0 allows the join")
+    setup_items()
+    my_predbat.expose_config("octopus_saving_auto_join", True, quiet=True)
+    my_predbat.expose_config("octopus_saving_auto_join_lead_hours", 0, quiet=True)
+    ha.service_store_enable = True
+    ha.service_store = []
+    my_predbat.fetch_octopus_sessions()
+    service_result = ha.get_service_store()
+    ha.service_store_enable = False
+
+    join_calls = [svc for svc in service_result if "join" in svc[0]]
+    if len(join_calls) != 1:
+        print(f"ERROR: Expected 1 join when immediate auto-join enabled, got {len(join_calls)}: {service_result}")
+        failed = True
+    else:
+        print("  PASS: Join proceeds when octopus_saving_auto_join is True")
+
+    # Test 5: auto-join enabled, event outside configured lead hours -> no join
+    print("  Test 5: octopus_saving_auto_join=True with time before event > octopus_saving_auto_join_lead_hours skips the join")
+    setup_items()
+    my_predbat.expose_config("octopus_saving_auto_join", True, quiet=True)
+    my_predbat.expose_config("octopus_saving_auto_join_lead_hours", 2, quiet=True)
+    ha.service_store_enable = True
+    ha.service_store = []
+    my_predbat.fetch_octopus_sessions()
+    service_result = ha.get_service_store()
+    ha.service_store_enable = False
+
+    join_calls = [svc for svc in service_result if "join" in svc[0]]
+    if join_calls:
+        print(f"ERROR: Expected no join when auto-join enabled time before event > octopus_saving_auto_join_lead_hours, got {join_calls}")
+        failed = True
+    else:
+        print("  PASS: Join skipped when octopus_saving_auto_join is True and time before event > octopus_saving_auto_join_lead_hours")
+
+    # Test 6: auto-join enabled, event within configured lead hours  -> join proceeds
+    print("  Test 6: octopus_saving_auto_join=True with time before event < octopus_saving_auto_join_lead_hours allows the join")
+    setup_items()
+    my_predbat.expose_config("octopus_saving_auto_join", True, quiet=True)
+    my_predbat.expose_config("octopus_saving_auto_join_lead_hours", 3, quiet=True)
+    ha.service_store_enable = True
+    ha.service_store = []
+    my_predbat.fetch_octopus_sessions()
+    service_result = ha.get_service_store()
+    ha.service_store_enable = False
+
+    join_calls = [svc for svc in service_result if "join" in svc[0]]
+    if len(join_calls) != 1:
+        print(f"ERROR: Expected 1 join when immediate auto-join enabled and time before event < octopus_saving_auto_join_lead_hours, got {len(join_calls)}: {service_result}")
+        failed = True
+    else:
+        print("  PASS: Join proceeds when octopus_saving_auto_join is True and time before event < octopus_saving_auto_join_lead_hours")
 
     # Restore default state so we do not leak it to other tests
     my_predbat.expose_config("octopus_saving_auto_join", True, quiet=True)
+    my_predbat.expose_config("octopus_saving_auto_join_lead_hours", 0, quiet=True)
+    my_predbat.now_utc = original_now_utc
     my_predbat.octopus_last_joined_try = None
 
     return failed

docs/energy-rates.md

@@ -171,6 +171,8 @@ available sessions on your behalf.
 
 If an available saving session overlaps an Axle VPP session (any overlap in time), Predbat will **not** auto-join the saving session, as the two events cannot both be honoured for the same period. The Axle session takes priority.
 
+When auto-join is On, and there are no overlapping events, Predbat will join a saving session as soon as the event appears. In some cases this may not be desirable, for example when signed up to Axle short notice events, where a saving session could be announced before a conflicting Axle event. In such cases Predbat would have already joined the saving session, leading to potentially overlapping events. To resolve this, **octopus_saving_auto_join_lead_hours** can be configured to set how soon Predbat is allowed to join a saving session (default 0 = join immediately). Setting a value of e.g. "3" would mean Predbat will wait until 3 hours before the start of the saving session event before attempting to join, giving the opportunity for short notice events from Axle or other sources to be announced and considered first.
+
 Predbat will also **not** auto-join a session whose reward rate doesn't exceed the **octopus_saving_session_min_octopoints_per_kwh** configuration item in `apps.yaml` (default 0 octopoints/kWh - joins any session with a positive reward). Raise this if you want to also skip low-value sessions you don't consider worth the disruption. The default of 0 additionally works around the Octopus Energy integration currently reporting some non-joinable events (national Power Up/free electricity slots) inside the same data set at 0 p/kWh - see [#4593](https://github.com/springfall2008/batpred/issues/4593).
 
 In the Predbat plan, for joined saving sessions the energy rates for import and export will be overridden by adding the assumed saving rate to your normal rate.