Merge branch 'develop' into beta

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

@@ -84,7 +84,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

@@ -46,6 +46,8 @@
   DATA_ACCOUNT,
   INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLE_CHARGERS,
   INTELLIGENT_DEVICE_KIND_ELECTRIC_VEHICLES,
+  REPAIR_FREE_ELECTRICITY_SESSION_BINARY_SENSOR_DEPRECATED,
+  REPAIR_SAVING_SESSION_BINARY_SENSOR_DEPRECATED,
   REPAIR_TARGET_RATE_REMOVAL_PROPOSAL
 )
 
@@ -138,8 +140,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_ADDED = "intelligent_device_added_{}"
 REPAIR_INTELLIGENT_DEVICE_REMOVED = "intelligent_device_removed_{}"
 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/diagnostics_entities/current_consumption_data_last_retrieved.py

@@ -0,0 +1,22 @@
+from .base import OctopusEnergyBaseDataLastRetrieved
+from ..electricity.base import OctopusEnergyElectricitySensor
+
+class OctopusEnergyElectricityCurrentConsumptionDataLastRetrieved(OctopusEnergyElectricitySensor, OctopusEnergyBaseDataLastRetrieved):
+  """Sensor for displaying the last time the current consumption data was last retrieved."""
+
+  def __init__(self, hass, coordinator, meter, point):
+    """Init sensor."""
+    self._mpan = point["mpan"]
+    self._serial_number = meter["serial_number"]
+    OctopusEnergyElectricitySensor.__init__(self, hass, meter, point)
+    OctopusEnergyBaseDataLastRetrieved.__init__(self, hass, coordinator)
+
+  @property
+  def unique_id(self):
+    """The id of the sensor."""
+    return f"octopus_energy_electricity_{self._serial_number}_{self._mpan}_current_consumption_data_last_retrieved"
+    
+  @property
+  def name(self):
+    """Name of the sensor."""
+    return f"Current Consumption Data Last Retrieved Electricity ({self._serial_number}/{self._mpan})"

custom_components/octopus_energy/diagnostics_entities/current_consumption_home_pro_data_last_retrieved.py

@@ -0,0 +1,22 @@
+from .base import OctopusEnergyBaseDataLastRetrieved
+from ..electricity.base import OctopusEnergyElectricitySensor
+
+class OctopusEnergyElectricityCurrentConsumptionHomeProDataLastRetrieved(OctopusEnergyElectricitySensor, OctopusEnergyBaseDataLastRetrieved):
+  """Sensor for displaying the last time the current consumption home pro data was last retrieved."""
+
+  def __init__(self, hass, coordinator, meter, point):
+    """Init sensor."""
+    self._mpan = point["mpan"]
+    self._serial_number = meter["serial_number"]
+    OctopusEnergyElectricitySensor.__init__(self, hass, meter, point)
+    OctopusEnergyBaseDataLastRetrieved.__init__(self, hass, coordinator)
+
+  @property
+  def unique_id(self):
+    """The id of the sensor."""
+    return f"octopus_energy_electricity_{self._serial_number}_{self._mpan}_home_pro_current_consumption_data_last_retrieved"
+    
+  @property
+  def name(self):
+    """Name of the sensor."""
+    return f"Home Pro Current Consumption Data Last Retrieved Electricity ({self._serial_number}/{self._mpan})"