feat(octopus): broaden saving/free session entity regex to match Power Down/Up rename

Octopus Energy integration v19.0.0 renamed the saving-session and
free-electricity event entities to Power Down and Power Up
(event.octopus_energy_ACCOUNT_ID_octoplus_power_down_events /
..._power_up_events). Both old and new entities remain registered
until January 2027 (ADR-0004), and resolve_arg_re()'s regex
matching against HA state keys is a one-off startup resolution, so
broadening the 're:' alternation to match either name is enough -
no runtime try-new-then-old logic is needed here, unlike the join
service rename in point 3.

Updates the octopus_saving_session/octopus_free_session regex in
apps.yaml (default, coverage test fixture, and all 23 inverter
templates that configure them), plus docs/energy-rates.md to
mention the rename, the entity_registry_enabled_default=False
gotcha, and the January 2027 cutoff.

Part of #4548 (point 2).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: chalfontchubby

apps/predbat/config/apps.yaml

@@ -393,12 +393,12 @@ pred_bat:
 
   # Octopus saving session points to the saving session Sensor in the Octopus plugin, when enabled saving sessions will be at the assumed
   # Rate is read automatically from the add-in and converted to pence using the conversion rate below (default is 8)
-  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_saving_session_event(s|))'
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
   octopus_saving_session_octopoints_per_penny: 8
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 
   # Alternative scraper from Octopus web site if the above is not working
   # octopus_free_url: 'http://octopus.energy/free-electricity'

apps/predbat/tests/test_saving_session.py

@@ -845,3 +845,45 @@ def test_saving_session_default_rate(my_predbat):
             print(f"PASS: Default rate correctly injected for null octopoints: {expected_rate} p/kWh")
 
     return failed
+
+
+def test_saving_session_entity_regex_power_rename(my_predbat):
+    """
+    Test that the octopus_saving_session/octopus_free_session apps.yaml 're:' patterns
+    match both the deprecated saving-session/free-electricity entity names and the
+    replacement Power Down/Power Up entity names introduced by Octopus integration
+    v19.0.0, and that each pattern does not cross-match the other event type.
+    Covers GitHub issue #4548 point 2.
+    """
+    print("Test octopus_saving_session/octopus_free_session entity regex Power Down/Up rename (issue #4548 point 2)")
+    failed = False
+
+    saving_pattern = "re:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))"
+    free_pattern = "re:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))"
+
+    cases = [
+        # (arg, pattern, state_keys, expected_match, description)
+        ("octopus_saving_session", saving_pattern, ["event.octopus_energy_a4dd6c5ee_octoplus_saving_session_events"], "event.octopus_energy_a4dd6c5ee_octoplus_saving_session_events", "deprecated saving-session entity"),
+        ("octopus_saving_session", saving_pattern, ["event.octopus_energy_a4dd6c5ee_octoplus_power_down_events"], "event.octopus_energy_a4dd6c5ee_octoplus_power_down_events", "new Power Down entity"),
+        ("octopus_saving_session", saving_pattern, ["event.octopus_energy_a4dd6c5ee_octoplus_power_up_events"], None, "Power Up entity must not match the saving-session/Power Down pattern"),
+        ("octopus_free_session", free_pattern, ["event.octopus_energy_a4dd6c5ee_octoplus_free_electricity_session_events"], "event.octopus_energy_a4dd6c5ee_octoplus_free_electricity_session_events", "deprecated free-electricity entity"),
+        ("octopus_free_session", free_pattern, ["event.octopus_energy_a4dd6c5ee_octoplus_power_up_events"], "event.octopus_energy_a4dd6c5ee_octoplus_power_up_events", "new Power Up entity"),
+        ("octopus_free_session", free_pattern, ["event.octopus_energy_a4dd6c5ee_octoplus_power_down_events"], None, "Power Down entity must not match the free-session/Power Up pattern"),
+    ]
+
+    for arg, pattern, state_keys, expected, description in cases:
+        matched, resolved = my_predbat.resolve_arg_re(arg, pattern, state_keys)
+        if expected is None:
+            if matched:
+                print(f"ERROR: {description} - expected no match, got {resolved}")
+                failed = True
+            else:
+                print(f"PASS: {description} correctly did not match")
+        else:
+            if not matched or resolved != expected:
+                print(f"ERROR: {description} - expected {expected}, got matched={matched} resolved={resolved}")
+                failed = True
+            else:
+                print(f"PASS: {description} resolved to {resolved}")
+
+    return failed

apps/predbat/unit_test.py

@@ -73,6 +73,7 @@
     test_saving_session_join_service_fallback,
     test_saving_session_auto_join_toggle,
     test_saving_session_custom_entity_no_rewrite_match,
+    test_saving_session_entity_regex_power_rename,
 )
 from tests.test_secrets import run_secrets_tests
 from tests.test_ge_cloud import test_ge_cloud
@@ -447,6 +448,7 @@ def main():
         ("saving_session_join_service_fallback", test_saving_session_join_service_fallback, "Saving session join service fallback test (issue #4548 point 3)", False),
         ("saving_session_auto_join_toggle", test_saving_session_auto_join_toggle, "Saving session auto-join toggle test (issue #4120)", False),
         ("saving_session_custom_entity_no_rewrite_match", test_saving_session_custom_entity_no_rewrite_match, "Saving session custom entity no rewrite match test (issue #4573)", False),
+        ("saving_session_entity_regex_power_rename", test_saving_session_entity_regex_power_rename, "Saving/free session entity regex Power Down/Up rename test (issue #4548 point 2)", False),
         ("alert_feed", test_alert_feed, "Alert feed tests", False),
         ("fox_api", run_fox_api_tests, "Fox API tests", False),
         ("deye_const", run_deye_const_tests, "DEYE constants tests", False),

coverage/apps.yaml

@@ -333,7 +333,7 @@ pred_bat:
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  #octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  #octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
   octopus_free_url: 'http://octopus.energy/free-electricity'
 
   # Energy rates

docs/energy-rates.md

@@ -143,16 +143,24 @@ if you don't want the standing charge (and only have consumption usage) to be in
 Note that this configuration option to suppress the standing charge only applies if you are using the Octopus Integration from Predbat.
 If you are using the Octopus Energy direct method of Predbat directly connecting to Octopus then the standing charge will always be included in the plan and charts.
 
-### Octopus Saving sessions
+### Octopus Saving sessions (Power Down events)
 
-Predbat can automatically join you to Octopus saving sessions and plan battery activity for the saving session period to maximise your income.
+Predbat can automatically join you to Octopus saving sessions - now called Power Down events - and plan battery activity for the session period to maximise your income.
 
-Note: **You must have signed up to both the Octopus Octoplus and then the Saving Session schemes to benefit from these events**
+Note: **You must have signed up to both the Octopus Octoplus and then the Saving Session/Power Down schemes to benefit from these events**
 
 For Predbat to automatically manage Octopus saving sessions the following additional configuration item in `apps.yaml` is used.
 Like the electricity rates, this is set in the `apps.yaml` template to a regular expression that should auto-discover the Octopus Energy integration.
 
-- **octopus_saving_session** - Indicates if a saving session is active, should point to the sensor 'event.octopus_energy_ACCOUNT_ID_saving_session_event'.
+- **octopus_saving_session** - Indicates if a saving session/Power Down event is active, should point to the sensor 'event.octopus_energy_ACCOUNT_ID_octoplus_power_down_events'.
+
+```yaml
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
+```
+
+Octopus Energy integration v19.0.0 renamed this sensor from `..._octoplus_saving_session_events` to `..._octoplus_power_down_events`. The above pattern matches either name, so existing configurations keep working unchanged.
+The old sensor is retained by the integration until **January 2027**, after which only the Power Down naming will exist. The new sensor ships disabled by default in Home Assistant
+(`entity_registry_enabled_default: False`) - if Predbat's Octopus entity list does not show a Power Down sensor, [enable it in the entity registry first](https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/faq/#there-are-entities-that-are-disabled-why-are-they-disabled-and-how-do-i-enable-them), otherwise Predbat will keep silently using the old sensor with no visible warning.
 
 When a saving session is available it will be automatically joined by Predbat and should then appear as a joined session within the next 30 minutes.
 
@@ -180,9 +188,9 @@ If you do not have an export tariff then forced export will not apply and Predba
 If you do not want Predbat to automatically join Octopus saving sessions and manage your battery activity for the session,
 simply delete or comment out the **octopus_saving_session** entry in `apps.yaml`.
 
-### Octopus free (power up) events
+### Octopus free (Power Up) events
 
-Predbat can automatically detect Octopus free events and adjust your battery plan according. Note that this is derived from external sources, which do not verify your eligibility for free sessions.
+Predbat can automatically detect Octopus free events - now called Power Up events - and adjust your battery plan accordingly. Note that this is derived from external sources, which do not verify your eligibility for free sessions.
 
 For Predbat to automatically manage Octopus free sessions the following additional configuration item in apps.yaml is used.
 
@@ -194,10 +202,14 @@ Like the electricity rates, this is set in the apps.yaml template to a regular e
 all the free events.
 
 ```yaml
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 ```
 
-Note: **This event may need to be enabled in Home Assistant first** - see [How to Enable Octopus events](https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/faq/#there-are-entities-that-are-disabled-why-are-they-disabled-and-how-do-i-enable-them)
+Octopus Energy integration v19.0.0 renamed this sensor from `..._octoplus_free_electricity_session_events` to `..._octoplus_power_up_events`. The above pattern matches either name, so existing
+configurations keep working unchanged. The old sensor is retained by the integration until **January 2027**, after which only the Power Up naming will exist.
+
+Note: **This event may need to be enabled in Home Assistant first** - the new Power Up sensor ships disabled by default (`entity_registry_enabled_default: False`), so if it is not appearing in
+Predbat's entity list, enable it in the entity registry - see [How to Enable Octopus events](https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/faq/#there-are-entities-that-are-disabled-why-are-they-disabled-and-how-do-i-enable-them)
 
 If you normally increase your house usage during a free session then you can change **input_number.predbat_load_scaling_free** to allow Predbat to assume an energy
 increase in this period. E.g. setting to a value of 1.2 would indicate you will use 20% more energy than normal during this period. (Default is 1.2)

templates/enphase_cloud.yaml

@@ -184,12 +184,12 @@ pred_bat:
 
   # Octopus saving session points to the saving session Sensor in the Octopus plugin, when enabled saving sessions will be at the assumed
   # Rate is read automatically from the add-in and converted to pence using the conversion rate below (default is 8)
-  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_saving_session_event(s|))'
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
   octopus_saving_session_octopoints_per_penny: 8
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 
   # Alternative scraper from Octopus web site if the above is not working
   # octopus_free_url: 'http://octopus.energy/free-electricity'

templates/fox.yaml

@@ -275,12 +275,12 @@ pred_bat:
 
   # Octopus saving session points to the saving session Sensor in the Octopus plugin, when enabled saving sessions will be at the assumed
   # Rate is read automatically from the add-in and converted to pence using the conversion rate below (default is 8)
-  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_saving_session_event(s|))'
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
   octopus_saving_session_octopoints_per_penny: 8
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 
   # Energy rates
   # Please set one of these three, if multiple are set then Octopus is used first, second rates_import/rates_export and latest basic metric

templates/fox_cloud.yaml

@@ -175,12 +175,12 @@ pred_bat:
 
   # Octopus saving session points to the saving session Sensor in the Octopus plugin, when enabled saving sessions will be at the assumed
   # Rate is read automatically from the add-in and converted to pence using the conversion rate below (default is 8)
-  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_saving_session_event(s|))'
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
   octopus_saving_session_octopoints_per_penny: 8
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 
   # Alternative scraper from Octopus web site if the above is not working
   # octopus_free_url: 'http://octopus.energy/free-electricity'

templates/fronius.yaml

@@ -328,12 +328,12 @@ pred_bat:
 
   # Octopus saving session points to the saving session Sensor in the Octopus plugin, when enabled saving sessions will be at the assumed
   # Rate is read automatically from the add-in and converted to pence using the conversion rate below (default is 8)
-  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_saving_session_event(s|))'
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
   octopus_saving_session_octopoints_per_penny: 8
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 
   # Energy rates
   # Please set one of these three, if multiple are set then Octopus is used first, second rates_import/rates_export and latest basic metric

templates/ginlong_solis.yaml

@@ -262,12 +262,12 @@ pred_bat:
 
   # Octopus saving session points to the saving session Sensor in the Octopus plugin, when enabled saving sessions will be at the assumed
   # Rate is read automatically from the add-in and converted to pence using the conversion rate below (default is 8)
-  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_saving_session_event(s|))'
+  octopus_saving_session: 're:(event.octopus_energy([0-9a-z_]+|)_(saving_session_events?|power_down_events))'
   octopus_saving_session_octopoints_per_penny: 8
 
   # Octopus free session points to the free session Sensor in the Octopus plugin
   # Note: You must enable this event sensor in the Octopus Integration in Home Assistant for it to work
-  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_(free_electricity_session_events|power_up_events))'
 
   # Energy rates
   # Please set one of these three, if multiple are set then Octopus is used first, second rates_import/rates_export and latest basic metric