Next release (#1557)

Author: BottlecapDave

_docs/blueprints.md

@@ -24,7 +24,7 @@ This blueprint will fire a configured action when the consumption has 24 hours w
 
 ### Alert when consumption data is late
 
-[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%octopus_energy_late_consumption_data.yaml) | [Source](./blueprints/octopus_energy_late_consumption_data.yaml)
+[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%2Foctopus_energy_late_consumption_data.yaml) | [Source](./blueprints/octopus_energy_late_consumption_data.yaml)
 
 This blueprint will fire a configured action when the latest available consumption data is x hours old, where x is configured via the blueprint.
 
@@ -52,7 +52,7 @@ This blueprint will automatically redeem all redeemable points for account credi
 
 ### Alert when current consumption is approaching saving sessions baseline
 
-[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%octopus_energy_baseline_alert.yaml) | [Source](./blueprints/octopus_energy_baseline_alert.yaml)
+[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%2Foctopus_energy_baseline_alert.yaml) | [Source](./blueprints/octopus_energy_baseline_alert.yaml)
 
 This blueprint will fire a configured action when the consumption for the current interval (i.e. the current 30 minute period) reaches a configured percentage of the saving session baseline.
 
@@ -62,7 +62,7 @@ This blueprint will fire a configured action when the consumption for the curren
 
 ### Alert when current consumption has reached free electricity sessions baseline
 
-[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%octopus_energy_free_electricity_baseline_reached.yaml) | [Source](./blueprints/octopus_energy_free_electricity_baseline_reached.yaml)
+[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%2Foctopus_energy_free_electricity_baseline_reached.yaml) | [Source](./blueprints/octopus_energy_free_electricity_baseline_reached.yaml)
 
 This blueprint will fire a configured action when the consumption for the current interval (i.e. the current 30 minute period) reaches the current free electricity session baseline.
 
@@ -74,7 +74,7 @@ This blueprint will fire a configured action when the consumption for the curren
 
 ## Manual Intelligent Dispatch Refreshes
 
-[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%octopus_energy_manual_intelligent_refresh.yaml) | [Source](./blueprints/octopus_energy_manual_intelligent_refresh.yaml)
+[Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBottlecapDave%2FHomeAssistant-OctopusEnergy%2Fblob%2Fmain%2F_docs%2Fblueprints%2Foctopus_energy_manual_intelligent_refresh.yaml) | [Source](./blueprints/octopus_energy_manual_intelligent_refresh.yaml)
 
 This blueprint will fire the [intelligent dispatches service](./services.md#octopus_energyrefresh_intelligent_dispatches) either when a sensor from another integration determines the car has been plugged in (e.g. the plug status from the [MyEnergi integration](https://github.com/CJNE/ha-myenergi)) or when the data is stale and overdue a refresh (in case the dispatch information has changed).
 

_docs/entities/electricity.md

@@ -157,6 +157,10 @@ This is `on` when you're within your tariff's off peak period, and `off` at all
 
     * OHME
 
+!!! note
+
+    Sensor came on when you did/didn't expected it to and you're on an intelligent tariff? You can see what the state of your dispatches were at the time by using the [get_point_in_time_intelligent_dispatch_history service](../services.md#octopus_energyget_point_in_time_intelligent_dispatch_history)
+
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `current_start` | `datetime` | The date/time when the off peak rate started |

_docs/entities/greenness_forecast.md

@@ -1,6 +1,6 @@
 # Greenness Forecast
 
-To support the [greenness forecast](https://octopus.energy/smart/greener-days/) supported by Octopus Energy, the following entities are provided.
+To support the [greener nights](https://octopus.energy/smart/greener-nights/) supported by Octopus Energy, the following entities are provided.
 
 ## Current Index
 
@@ -87,4 +87,45 @@ For `current`, the following attributes are provided
 
 !!! info
 
-    You can use the [data_last_retrieved sensor](./diagnostics.md#greenness-forecast-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
+    You can use the [data_last_retrieved sensor](./diagnostics.md#greenness-forecast-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
+
+## Greener Nights Calendar
+
+`calendar.octopus_energy_{{ACCOUNT_ID}}_greener_nights`
+
+Read only [calendar](https://www.home-assistant.io/integrations/calendar) sensor to record nights that are highlighted as "greener nights". Will be `on` when a greener night is active. Calendar events will be automatically added/removed by the integration when greener nights are discovered. 
+
+Standard calendar attributes will indicate the current/next highlighted greener night.
+
+!!! warning
+
+    The sensor does not store past events indefinitely. Past events could be removed without notice.
+
+!!! info
+
+    You can use the [data_last_retrieved sensor](./diagnostics.md#greenness-forecast-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `greenness_index` | `int` | The index for the current/next forecast |
+| `greenness_score` | `string` | The score associated by Octopus Energy for the current/next forecast |
+
+### Automation Example
+
+Below is an example of raising a persistent notification 5 minutes before a saving session starts.
+
+```yaml
+triggers:
+- trigger: calendar
+  entity_id: calendar.octopus_energy_{{ACCOUNT_ID}}_greener_nights
+  event: start
+  offset: -00:05:00
+actions:
+- action: persistent_notification.create
+  data:
+    title: Greener Night Starting
+    message: >
+      {% set minutes = ((state_attr(trigger.entity_id, 'end_time') | as_datetime - state_attr(trigger.entity_id, 'start_time') | as_datetime).seconds / 60) | round(0) | string %}
+      {% set start_time = (state_attr(trigger.entity_id, 'start_time') | as_datetime).strftime('%H:%M') %}
+      Greener night starts at {{ start_time }} for {{ minutes }} minutes.
+```

_docs/entities/intelligent.md

@@ -14,10 +14,6 @@ This sensor is used to determine if you're within a dispatching period (i.e. "sm
 
 Depending on your [account configuration](../setup/account.md#intelligent-rates-mode), what is determined as an active dispatching period will change. If you have configured to accept [planned or started dispatches](../setup/account.md#planned-and-started-dispatches-will-turn-into-off-peak-rates), then the sensor will turn on when you're are within an active planned or started dispatch period. If you have configured to accept [only started dispatches](../setup/account.md#only-started-dispatches-will-turn-into-off-peak-rates), then the sensor will turn on when you're are within an active started dispatch period, but not planned dispatch.
 
-!!! info
-
-    This sensor will only turn on during dispatches for a single intelligent device. If you're after a sensor that turns on during the standard off peak rates as well or cover multiple intelligent devices then you're best to use the [off peak sensor](./electricity.md#off-peak).
-
 !!! warning
 
     If you are using this to drive other automations for cheap rates (e.g. to fill batteries), you should perform additional checks to make sure your vehicle is actually charging. If it isn't, this sensor could be incorrectly on if during a dispatch outside of the standard off peak period and you will therefore not receive the off peak rate.
@@ -32,6 +28,14 @@ Depending on your [account configuration](../setup/account.md#intelligent-rates-
 
     If you are supplied by one of the above providers, this sensor will never turn on. 
 
+!!! info
+
+    This sensor will only turn on during dispatches for a single intelligent device. If you're after a sensor that turns on during the standard off peak rates as well or cover multiple intelligent devices then you're best to use the [off peak sensor](./electricity.md#off-peak).
+
+!!! note
+
+    Sensor came on when you did/didn't expected it to? You can see what the state of your dispatches were at the time by using the [get_point_in_time_intelligent_dispatch_history service](../services.md#octopus_energyget_point_in_time_intelligent_dispatch_history)
+
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `planned_dispatches` | `array` | An array of the dispatches that are currently planned by Octopus Energy. |

_docs/entities/octoplus.md

@@ -16,7 +16,11 @@ Determines the current Octoplus points balance. This sensor will only be availab
 | `redeemable_points` | `integer` | The number of points that can be redeemed into account credit |
 | `data_last_retrieved` | `datetime` | The date/time the underlying data was last retrieved from Octopus Energy APIs |
 
-## Saving Sessions
+## Octopus Saving Sessions
+
+These sensors are for [Octopus Saving Sessions](https://octopus.energy/saving-sessions/).
+
+### Saving Sessions
 
 !!! warning 
 
@@ -39,7 +43,7 @@ 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
+### Saving Sessions Calendar
 
 `calendar.octopus_energy_{{ACCOUNT_ID}}_octoplus_saving_sessions`
 
@@ -55,7 +59,7 @@ Standard calendar attributes will indicate the current/next saving session.
 
     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.
 
-### Automation Example
+#### Automation Example
 
 Below is an example of raising a persistent notification 5 minutes before a saving session starts.
 
@@ -75,7 +79,7 @@ actions:
       Saving session starts at {{ start_time }} for {{ minutes }} minutes.
 ```
 
-## Saving Session Events
+### Saving Session Events
 
 `event.octopus_energy_{{ACCOUNT_ID}}_octoplus_saving_session_events`
 
@@ -111,7 +115,7 @@ Each joined event item will include the following attributes
 | `rewarded_octopoints` | `integer` | The total number of octopoints that were awarded (if any or known) |
 | `octopoints_per_kwh` | `integer` | The number of octopoints that are/were awarded per kwh saved during the event (if known) |
 
-## Saving Session Baseline
+### Saving Session Baseline
 
 `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_octoplus_saving_session_baseline`
 
@@ -159,7 +163,11 @@ Each item within `baselines` consists of the following attributes
 
     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.
 
-## Free Electricity Sessions
+## Octopus Free Electricity
+
+These sensors are for [Octopus Free Electricity](https://octopus.energy/free-electricity/).
+
+### Free Electricity Sessions
 
 !!! warning 
 
@@ -188,7 +196,7 @@ Binary sensor to indicate if a free electricity session is active.
 
     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
+### Free Electricity Sessions Calendar
 
 `calendar.octopus_energy_{{ACCOUNT_ID}}_octoplus_free_electricity_session`
 
@@ -210,7 +218,7 @@ Standard calendar attributes will indicate the current/next saving session.
 
     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.
 
-### Automation Example
+#### Automation Example
 
 Below is an example of raising a persistent notification 5 minutes before a free electricity session starts.
 
@@ -230,7 +238,7 @@ actions:
       Free electricity session starts at {{ start_time }} for {{ minutes }} minutes.
 ```
 
-## Free Electricity Session Events
+### Free Electricity Session Events
 
 `event.octopus_energy_{{ACCOUNT_ID}}_octoplus_free_electricity_session_events`
 
@@ -255,7 +263,7 @@ Each item in the `events` attribute will include the following attributes
 | `end` | `datetime` | The date/time the event starts |
 | `duration_in_minutes` | `integer` | The duration of the event in minutes |
 
-## Free Electricity Session Baseline
+### Free Electricity Session Baseline
 
 `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_octoplus_free_electricity_session_baseline`
 

_docs/faq.md

@@ -221,6 +221,25 @@ where states_meta.entity_id = 'binary_sensor.octopus_energy_xxx_intelligent_disp
 order by last_updated_ts desc
 ```
 
+## I was expecting the saving session/free electricity session sensor to turn on during a period, but it didn't. Is there a reason for this?
+
+One thing that people get confused about these sensors is that they represent two different programs held by Octopus, and recently Octopus have sometimes been confusing the messaging around these programs (e.g. at the time of writing one is implied to be a subset of the other).
+
+Saving session sensors are in relation to [Octopus Saving Sessions](https://octopus.energy/saving-sessions/). These sessions are about using **less** energy that you normally use, where any energy saved is credited back to your account in the form of octopoints. These sessions typically occur within the winter when renewable energy is low.
+
+Free electricity session sensors are in relation to [Octopus Free Electricity](https://octopus.energy/free-electricity/). These sessions are about using **more** energy than you normally use, where any energy used above your standard consumption is credited back to your account, basically making that excess energy free. These sessions typically occur when there's an excess of renewable energy (e.g. high wind).
+
+If you think the sensor is still not coming on when it should, then please raise any issue.
+
+## Current rate sensors were not zero during a free electricity session. Is this expected?
+
+The current rate sensor will not be adjusted during free electricity sessions. This is by design, for a couple of reasons
+
+1. The electricity price is only £0 for any electricity that you use within each applicable 30 minute period that is above your average consumption for that period. Therefore you are still charged the standard rate for any consumption below or equal to this average consumption. So the entire period is not technically free and so changing the rate sensor in my opinion is misleading.
+2. The electricity is charged at your standard rate and then credited back. This means that while any electricity is technically free over your consumption, you are still "billed" at your standard rate. Because of this latter reason, to my knowledge none of the OE charts take this into account and the cost sensors are designed to match as close as possible to the costs appearing on the website when you look at your history.
+
+There are no plans to change this. If you are wanting to drive automations, it is advised to use the [free electricity sensor](./entities/octoplus.md#free-electricity-sessions-calendar) for these situations.
+
 ## Do you support older versions of the integration?
 
 Due to time constraints, I will only ever support the latest version of the integration. If you have an issue with an older version of the integration, my initial answer will always be to update to the latest version. This might be different to what HACS is reporting if you are not on the minimum supported Home Assistant version (which is highlighted in each release's changelog). 

_docs/services.md

@@ -308,6 +308,25 @@ Refreshes intelligent dispatches for a given account.
 
 For an automation example, please refer to the available [blueprint](./blueprints.md#manual-intelligent-dispatch-refreshes).
 
+### octopus_energy.get_point_in_time_intelligent_dispatch_history
+
+Retrieve the intelligent dispatch history which was active for a given point in time based on up to the last 48 hours of intelligent dispatches that have been captured locally. This can be used to determine why [is dispatching](./entities/intelligent.md#is-dispatching) or [off peak](./entities/electricity.md#off-peak) might have turned on during a certain time period.
+
+!!! info
+
+    The OE API doesn't provide historic intelligent dispatch information, so this information is stored locally as it changes. Therefore depending on how often your dispatch information refreshes, it can take a while for data to become available.
+
+!!! note
+
+    The data that powers this service is available at `config/.storage/octopus_energy.intelligent_dispatches_history_{{DEVICE_ID}}`
+
+
+| Attribute                | Optional | Description                                                                                                           |
+| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `target.entity_id`       | `no`     | The [dispatching](./entities/intelligent.md#is-dispatching) entity that you want to refresh the content for (e.g. `binary_sensor.octopus_energy_{{DEVICE_ID}}_intelligent_dispatching`). |
+| `data.point_in_time`     | `no`     | The point in time to get the historic dispatch information that was active at the time.
+
+
 ## Miscellaneous
 
 ### octopus_energy.purge_invalid_external_statistic_ids