chore: Added repair notice around sensors and updated docs (45 minutes dev time)

Author: BottlecapDave

_docs/architecture_decision_records/0003_move_to_calendar_entities_for_octoplus_events.md

@@ -0,0 +1,33 @@
+# 0003 - Move to calendar entities for Octoplus events
+
+## Status
+Accepted
+
+## Context
+
+Currently binary sensors are provided to indicate when a saving or free electricity session is active for the current account. This also provides attributes for current and next start/end times.
+
+Since the introduction of the saving session binary sensor, calendar entities have received more love within Home Assistant and become the preferred way of showing events. These are better supports in UI automations as you can offset calendar events easily (e.g. reminder 10 minutes before) without having to do template gymnastics. The calendar view of Home Assistant is also used by house hold members who are not as involved as other members in things like wall tablets. A few users move the data from the sensor data into a local calendar to produce this.
+
+This request has been made on a few occasions, below are some samples
+
+* https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/issues/561#issuecomment-1826830172
+* https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/issues/1397
+
+## Decision
+
+With more people coming on board to Home Assistant who don't necessarily come from a technological background, the automation UI becoming the preferred way of creating automations and the calendar entity getting more love, it has been decided to convert the saving session and free electricity sessions into calendar entities.
+
+The old sensors will continue to be available until **May 2026** when they will be removed, to ease with the transition.
+
+## Consequences 
+
+### Positive
+- Automations around sessions will be easier via the calendar trigger
+- Past and present sessions will be easily viewable in the Home Assistant Calendar view
+- Standard approach for people used to calendar entities.
+
+### Negative
+- Users using effected entities will need to update all references
+- Some short-term disruption may occur as users adapt to the new entity behaviour.
+- Event duration (e.g. 60 minutes) will require templating still

_docs/entities/octoplus.md

@@ -18,6 +18,10 @@ Determines the current Octoplus points balance. This sensor will only be availab
 
 ## Saving Sessions
 
+!!! warning 
+
+    This sensor has been deprecated in favour of [Saving Session Calendar](#saving-sessions-calendar) and will be removed around **May 2026**
+
 `binary_sensor.octopus_energy_{{ACCOUNT_ID}}_octoplus_saving_sessions`
 
 Binary sensor to indicate if a saving session that the account has joined is active.
@@ -35,6 +39,20 @@ Binary sensor to indicate if a saving session that the account has joined is act
 
     You can use the [data_last_retrieved sensor](./diagnostics.md#saving-sessions-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
 
+## Saving Sessions Calendar
+
+`calendar.octopus_energy_{{ACCOUNT_ID}}_octoplus_saving_sessions`
+
+Calendar sensor to record saving sessions. Will be `on` when a saving session that the account has joined is active. Standard calendar attributes will indicate the current/next saving session.
+
+!!! info
+
+    You can use the [data_last_retrieved sensor](./diagnostics.md#saving-sessions-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
+
+!!! note
+
+    The events are supplied by OE API and does not store past events indefinitely. Past events could be removed without notice.
+
 ## Saving Session Events
 
 `event.octopus_energy_{{ACCOUNT_ID}}_octoplus_saving_session_events`
@@ -121,6 +139,10 @@ Each item within `baselines` consists of the following attributes
 
 ## Free Electricity Sessions
 
+!!! warning 
+
+    This sensor has been deprecated in favour of [Free Electricity Sessions Calendar](#free-electricity-sessions-calendar) and will be removed around **May 2026**
+
 `binary_sensor.octopus_energy_{{ACCOUNT_ID}}_octoplus_free_electricity_session`
 
 Binary sensor to indicate if a free electricity session is active.
@@ -140,6 +162,22 @@ Binary sensor to indicate if a free electricity session is active.
 | `next_event_end` | `datetime` | The datetime the next free electricity session will end |
 | `next_event_duration_in_minutes` | `float` | The duration in minutes of the next free electricity session |
 
+!!! info
+
+    You can use the [data_last_retrieved sensor](./diagnostics.md#free-electricity-sessions-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
+
+## Free Electricity Sessions Calendar
+
+`calendar.octopus_energy_{{ACCOUNT_ID}}_octoplus_free_electricity_session`
+
+Calendar sensor to record free electricity sessions. Will be `on` when a free electricity session is active. Standard calendar attributes will indicate the current/next saving session.
+
+!!! note
+    This will only be available if you have enrolled into Octoplus. Once enrolled, reload the integration to gain access to this sensor. This is only applicable if you have signed up to [free electricity sessions](https://octopus.energy/free-electricity/). This sensor uses public information supplied by https://github.com/BottlecapDave/OctopusEnergyApi.
+
+!!! note
+    This is [disabled by default](../faq.md#there-are-entities-that-are-disabled-why-are-they-disabled-and-how-do-i-enable-them). 
+
 !!! info
 
     You can use the [data_last_retrieved sensor](./diagnostics.md#free-electricity-sessions-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.

custom_components/octopus_energy/binary_sensor.py

@@ -45,6 +45,8 @@
   DATA_ELECTRICITY_RATES_COORDINATOR_KEY,
   DATA_SAVING_SESSIONS_COORDINATOR,
   DATA_ACCOUNT,
+  REPAIR_FREE_ELECTRICITY_SESSION_BINARY_SENSOR_DEPRECATED,
+  REPAIR_SAVING_SESSION_BINARY_SENSOR_DEPRECATED,
   REPAIR_TARGET_RATE_REMOVAL_PROPOSAL
 )
 
@@ -137,8 +139,27 @@ async def async_setup_main_sensors(hass, entry, async_add_entities):
     OctopusEnergyGreennessForecastHighlighted(hass, greenness_forecast_coordinator, account_id)
   ]
 
+  ir.async_create_issue(
+    hass,
+    DOMAIN,
+    REPAIR_SAVING_SESSION_BINARY_SENSOR_DEPRECATED,
+    is_fixable=False,
+    severity=ir.IssueSeverity.WARNING,
+    learn_more_url="https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/architecture_decision_records/0003_move_to_calendar_entities_for_octoplus_events",
+    translation_key="saving_session_binary_sensor_deprecated",
+  )
+
   if octoplus_enrolled:
-    entities.append(OctopusEnergyFreeElectricitySessions(hass, free_electricity_session_coordinator, account_id))    
+    entities.append(OctopusEnergyFreeElectricitySessions(hass, free_electricity_session_coordinator, account_id))   
+    ir.async_create_issue(
+      hass,
+      DOMAIN,
+      REPAIR_FREE_ELECTRICITY_SESSION_BINARY_SENSOR_DEPRECATED,
+      is_fixable=False,
+      severity=ir.IssueSeverity.WARNING,
+      learn_more_url="https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/architecture_decision_records/0003_move_to_calendar_entities_for_octoplus_events",
+      translation_key="free_electricity_session_binary_sensor_deprecated",
+    ) 
 
   if len(account_info["electricity_meter_points"]) > 0:
 

custom_components/octopus_energy/const.py

@@ -214,6 +214,8 @@
 REPAIR_INTELLIGENT_DEVICE_NOT_FOUND = "intelligent_device_not_found_{}"
 REPAIR_INTELLIGENT_DEVICE_CHANGED = "intelligent_device_changed_{}"
 REPAIR_TARIFF_RATES_EMPTY = "tariff_rates_empty_{}_{}"
+REPAIR_SAVING_SESSION_BINARY_SENSOR_DEPRECATED = "saving_session_binary_sensor_deprecated"
+REPAIR_FREE_ELECTRICITY_SESSION_BINARY_SENSOR_DEPRECATED = "saving_session_binary_sensor_deprecated"
 
 # During BST, two records are returned before the rest of the data is available
 MINIMUM_CONSUMPTION_DATA_LENGTH = 3

custom_components/octopus_energy/translations/en.json

@@ -411,6 +411,14 @@
     "tariff_rates_empty": {
       "title": "{meter_type} {tariff_code} rates are empty for {account_id} ({mprn_mpan}/{serial_number})",
       "description": "One of your meters ({mprn_mpan}/{serial_number}) is associated with tariff \"{tariff_code}\" for product \"{product_code}\", but no longer seems to be returning new rates. Please click \"Learn More\" with details on how to rectify this."
+    },
+    "saving_session_binary_sensor_deprecated": {
+      "title": "Saving session binary sensor deprecated",
+      "description": "The saving session binary sensor has been deprecated in favour of using calendar entities. This will allow for better integration with automations and the calendar view. Please click \"Learn More\" for more information on this change."
+    },
+    "free_electricity_session_binary_sensor_deprecated": {
+      "title": "Free electricity session binary sensor deprecated",
+      "description": "The free electricity session binary sensor has been deprecated in favour of using calendar entities. This will allow for better integration with automations and the calendar view. Please click \"Learn More\" for more information on this change."
     }
   }
 }