feat: Added calendars for representing free electricity and saving sessions. Existing binary sensors have been deprecated. See repair notice for more information (2 hours 15 mins 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/__init__.py

@@ -86,7 +86,7 @@
   REPAIR_UNKNOWN_INTELLIGENT_PROVIDER
 )
 
-ACCOUNT_PLATFORMS = ["sensor", "binary_sensor", "number", "switch", "text", "time", "event", "select", "climate", "water_heater"]
+ACCOUNT_PLATFORMS = ["sensor", "binary_sensor", "number", "switch", "text", "time", "event", "select", "climate", "water_heater", "calendar"]
 TARGET_RATE_PLATFORMS = ["binary_sensor"]
 COST_TRACKER_PLATFORMS = ["sensor"]
 TARIFF_COMPARISON_PLATFORMS = ["sensor"]

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/calendar.py

@@ -0,0 +1,51 @@
+import logging
+
+from homeassistant.util.dt import (utcnow)
+
+
+from .const import (
+  CONFIG_KIND,
+  CONFIG_KIND_ACCOUNT,
+  CONFIG_ACCOUNT_ID,
+  DATA_FREE_ELECTRICITY_SESSIONS_COORDINATOR,
+  DOMAIN,
+
+  DATA_SAVING_SESSIONS_COORDINATOR,
+  DATA_ACCOUNT
+)
+
+from .octoplus.free_electricity_sessions_calendar import OctopusEnergyFreeElectricitySessionsCalendar
+from .octoplus.saving_sessions_calendar import OctopusEnergySavingSessionsCalendar
+
+_LOGGER = logging.getLogger(__name__)
+
+async def async_setup_entry(hass, entry, async_add_entities):
+  """Setup sensors based on our entry"""
+
+  if entry.data[CONFIG_KIND] == CONFIG_KIND_ACCOUNT:
+    await async_setup_main_sensors(hass, entry, async_add_entities)
+
+  return True
+
+async def async_setup_main_sensors(hass, entry, async_add_entities):
+  _LOGGER.debug('Setting up main sensors')
+  config = dict(entry.data)
+
+  account_id = config[CONFIG_ACCOUNT_ID]
+  account_result = hass.data[DOMAIN][account_id][DATA_ACCOUNT]
+  account_info = account_result.account if account_result is not None else None
+  octoplus_enrolled = account_info is not None and account_info["octoplus_enrolled"] == True
+
+  saving_session_coordinator = hass.data[DOMAIN][account_id][DATA_SAVING_SESSIONS_COORDINATOR]
+  free_electricity_session_coordinator = hass.data[DOMAIN][account_id][DATA_FREE_ELECTRICITY_SESSIONS_COORDINATOR]
+
+  now = utcnow()
+  entities = [
+    OctopusEnergySavingSessionsCalendar(hass, saving_session_coordinator, account_id),
+  ]
+
+  if octoplus_enrolled:
+    entities.append(OctopusEnergyFreeElectricitySessionsCalendar(hass, free_electricity_session_coordinator, account_id))    
+
+  if len(entities) > 0:
+    async_add_entities(entities)

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/octoplus/free_electricity_sessions_calendar.py

@@ -0,0 +1,116 @@
+from datetime import datetime
+import logging
+
+from homeassistant.const import (
+    STATE_UNAVAILABLE,
+    STATE_UNKNOWN,
+)
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers.entity import generate_entity_id
+from homeassistant.util.dt import (utcnow)
+
+from homeassistant.helpers.update_coordinator import (
+  CoordinatorEntity
+)
+from homeassistant.components.calendar import (
+    CalendarEntity,
+    CalendarEvent,
+)
+from homeassistant.helpers.restore_state import RestoreEntity
+
+from . import (
+  current_octoplus_sessions_event,
+  get_next_octoplus_sessions_event
+)
+
+from ..utils.attributes import dict_to_typed_dict
+from ..coordinators.free_electricity_sessions import FreeElectricitySessionsCoordinatorResult
+
+_LOGGER = logging.getLogger(__name__)
+
+class OctopusEnergyFreeElectricitySessionsCalendar(CoordinatorEntity, CalendarEntity, RestoreEntity):
+  """Sensor for determining if a free electricity session is active."""
+  
+  _unrecorded_attributes = frozenset({"data_last_retrieved"})
+
+  def __init__(self, hass: HomeAssistant, coordinator, account_id: str):
+    """Init sensor."""
+
+    CoordinatorEntity.__init__(self, coordinator)
+  
+    self._account_id = account_id
+    self._event = None
+    self._events = []
+
+    self.entity_id = generate_entity_id("calendar.{}", self.unique_id, hass=hass)
+
+  @property
+  def unique_id(self):
+    """The id of the sensor."""
+    return f"octopus_energy_{self._account_id}_octoplus_free_electricity_session"
+    
+  @property
+  def name(self):
+    """Name of the sensor."""
+    return f"Octoplus Free Electricity ({self._account_id})"
+  
+  @property
+  def entity_registry_enabled_default(self) -> bool:
+    """Return if the entity should be enabled when first added.
+
+    This only applies when fist added to the entity registry.
+    """
+    return False
+  
+  @property
+  def event(self) -> CalendarEvent | None:
+    """Return the next upcoming event."""
+    return self._event
+  
+  @callback
+  def _handle_coordinator_update(self) -> None:
+    """Determine if the user is in a free electricity session."""
+
+    free_electricity_session: FreeElectricitySessionsCoordinatorResult = self.coordinator.data if self.coordinator is not None else None
+    if (free_electricity_session is not None):
+      self._events = free_electricity_session.events
+    else:
+      self._events = []
+
+    current_date = utcnow()
+    current_event = current_octoplus_sessions_event(current_date, self._events)
+    if (current_event is not None):
+      self._event = CalendarEvent(
+        uid=current_event.code,
+        summary="Octopus Energy Free Electricity",
+        start=current_event.start,
+        end=current_event.end,
+      )
+    else:
+      next_event = get_next_octoplus_sessions_event(current_date, self._events)
+      if (next_event is not None):
+        self._event = CalendarEvent(
+          uid=next_event.code,
+          summary="Octopus Energy Free Electricity",
+          start=next_event.start,
+          end=next_event.end,
+        )
+
+    super()._handle_coordinator_update()
+
+  async def async_get_events(
+    self, hass, start_date: datetime, end_date: datetime
+  ) -> list[CalendarEvent]:
+    """Get all events in a specific time frame."""
+    events = []
+    if self._events is not None:
+      for event in self._events:
+        if event.start < end_date and event.end > start_date:
+          events.append(CalendarEvent(
+            uid=event.code,
+            summary="Octopus Energy Free Electricity",
+            start=event.start,
+            end=event.end,
+          ))
+
+    return events

custom_components/octopus_energy/octoplus/saving_sessions.py

@@ -60,7 +60,7 @@ def unique_id(self):
   @property
   def name(self):
     """Name of the sensor."""
-    return f"Octoplus Saving Session ({self._account_id})"
+    return f"Octoplus Saving Sessions ({self._account_id})"
 
   @property
   def icon(self):