feat: Added new sensors and events to expose various rate information

README.md

@@ -7,6 +7,7 @@
     - [Manual](#manual)
   - [How to setup](#how-to-setup)
   - [Target Rate Sensors](#target-rate-sensors)
+  - [Events](#events)
   - [Energy Dashboard](#energy-dashboard)
   - [Community Contributions](#community-contributions)
   - [FAQ](#faq)
@@ -39,7 +40,7 @@ To install, place the contents of `custom_components` into the `<config director
 
 ## How to setup
 
-Please follow the [setup guide](./_docs/setup_account.md) to setup your initial account. This will include a few sensors be default depending on your account.
+Please follow the [setup guide](./_docs/setup_account.md) to setup your initial account. This guide details the configuration, along with the sensors that will be available to you.
 
 ## Target Rate Sensors
 
@@ -49,6 +50,10 @@ These sensors can then be used in automations to turn on/off devices that save y
 
 Please follow the [setup guide](./_docs/setup_target_rate.md) to setup.
 
+## Events
+
+This integration raises several events, which can be used for various tasks like automations. For more information, please see the [events docs](./_docs/events.md).
+
 ## Energy Dashboard
 
 The core sensors have been designed to work with the energy dashboard. Please see the [guide](./_docs/energy_dashboard.md) for instructions on how to set this up.

_docs/events.md

@@ -0,0 +1,152 @@
+# Events
+
+- [Events](#events)
+  - [Electricity Current Day Rates](#electricity-current-day-rates)
+  - [Electricity Previous Day Rates](#electricity-previous-day-rates)
+  - [Electricity Next Day Rates](#electricity-next-day-rates)
+  - [Electricity Previous Consumption Rates](#electricity-previous-consumption-rates)
+  - [Electricity Previous Consumption Override Rates](#electricity-previous-consumption-override-rates)
+  - [Gas Current Day Rates](#gas-current-day-rates)
+  - [Gas Previous Day Rates](#gas-previous-day-rates)
+  - [Gas Next Day Rates](#gas-next-day-rates)
+  - [Gas Previous Consumption Rates](#gas-previous-consumption-rates)
+  - [Gas Previous Consumption Override Rates](#gas-previous-consumption-override-rates)
+
+The following events are raised by the integration. These events power various sensors mentioned above. They can also be used to trigger automations. An example automation might look like the following
+
+```yaml
+- alias: OE rates change
+  trigger:
+  - platform: event
+    event_type: octopus_energy_electricity_next_day_rates
+  condition: []
+  action:
+  - event: notify_channels
+    event_data_template:
+      mode: message
+      title: OE price changes
+      message: >
+        New rates available for {{ trigger.event.data.mpan }}. Starting value is {{ trigger.event.data.rates[0]["value_inc_vat"] }}
+      target: <@ULU7111GU>
+      length_hint: 00:00:04
+```
+
+## Electricity Current Day Rates
+
+`octopus_energy_electricity_current_day_rates`
+
+This is fired when the current day rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the current day |
+| `tariff_code` | `string` | The tariff code associated with current day's rates |
+| `mpan` | `string` | The mpan of the meter associated with these rates |
+
+## Electricity Previous Day Rates
+
+`octopus_energy_electricity_previous_day_rates`
+
+This is fired when the previous day rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous day |
+| `tariff_code` | `string` | The tariff code associated with previous day's rates |
+| `mpan` | `string` | The mpan of the meter associated with these rates |
+
+## Electricity Next Day Rates
+
+`octopus_energy_electricity_next_day_rates`
+
+This is fired when the next day rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the next day |
+| `tariff_code` | `string` | The tariff code associated with next day's rates |
+| `mpan` | `string` | The mpan of the meter associated with these rates |
+
+## Electricity Previous Consumption Rates
+
+`octopus_energy_electricity_previous_consumption_rates`
+
+This is fired when the [previous consumption's](./sensors/electricity.md#previous-accumulative-consumption) rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous consumption |
+| `tariff_code` | `string` | The tariff code associated with previous consumption's rates |
+| `mpan` | `string` | The mpan of the meter associated with these rates |
+
+## Electricity Previous Consumption Override Rates
+
+`octopus_energy_electricity_previous_consumption_override_rates`
+
+This is fired when the [previous consumption override's](./sensors/electricity.md#tariff-overrides) rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous consumption override |
+| `tariff_code` | `string` | The tariff code associated with previous consumption override's rates |
+| `mpan` | `string` | The mpan of the meter associated with these rates |
+
+## Gas Current Day Rates
+
+`octopus_energy_gas_current_day_rates`
+
+This is fired when the current day rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the current day |
+| `tariff_code` | `string` | The tariff code associated with current day's rates |
+| `mprn` | `string` | The mprn of the meter associated with these rates |
+
+## Gas Previous Day Rates
+
+`octopus_energy_gas_previous_day_rates`
+
+This is fired when the previous day rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous day |
+| `tariff_code` | `string` | The tariff code associated with previous day's rates |
+| `mprn` | `string` | The mprn of the meter associated with these rates |
+
+## Gas Next Day Rates
+
+`octopus_energy_gas_next_day_rates`
+
+This is fired when the next day rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the next day |
+| `tariff_code` | `string` | The tariff code associated with next day's rates |
+| `mprn` | `string` | The mprn of the meter associated with these rates |
+
+## Gas Previous Consumption Rates
+
+`octopus_energy_gas_previous_consumption_rates`
+
+This is fired when the [previous consumption's](./sensors/gas.md#previous-accumulative-consumption) rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous consumption |
+| `tariff_code` | `string` | The tariff code associated with previous consumption's rates |
+| `mprn` | `string` | The mprn of the meter associated with these rates |
+
+## Gas Previous Consumption Override Rates
+
+`octopus_energy_gas_previous_consumption_override_rates`
+
+This is fired when the [previous consumption override's](./sensors/gas.md#tariff-overrides) rates are updated.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous consumption override |
+| `tariff_code` | `string` | The tariff code associated with previous consumption override's rates |
+| `mprn` | `string` | The mprn of the meter associated with these rates |

_docs/sensors/electricity.md

@@ -6,6 +6,9 @@ You'll get the following sensors for each electricity meter with an active agree
   - [Current Rate](#current-rate)
   - [Previous Rate](#previous-rate)
   - [Next rate](#next-rate)
+  - [Current Day Rates](#current-day-rates)
+  - [Previous Day Rates](#previous-day-rates)
+  - [Next Day Rates](#next-day-rates)
   - [Off Peak](#off-peak)
   - [Smart Meter Sensors](#smart-meter-sensors)
     - [Previous Accumulative Consumption](#previous-accumulative-consumption)
@@ -14,6 +17,7 @@ You'll get the following sensors for each electricity meter with an active agree
     - [Previous Accumulative Cost](#previous-accumulative-cost)
     - [Previous Accumulative Cost (Peak Rate)](#previous-accumulative-cost-peak-rate)
     - [Previous Accumulative Cost (Off Peak Rate)](#previous-accumulative-cost-off-peak-rate)
+  - [Previous Consumption Day Rates](#previous-consumption-day-rates)
   - [Export Sensors](#export-sensors)
   - [Home Mini Sensors](#home-mini-sensors)
     - [Current Consumption](#current-consumption)
@@ -25,9 +29,10 @@ You'll get the following sensors for each electricity meter with an active agree
     - [Current Accumulative Cost (Peak Rate)](#current-accumulative-cost-peak-rate)
     - [Current Accumulative Cost (Off Peak Rate)](#current-accumulative-cost-off-peak-rate)
   - [Tariff Overrides](#tariff-overrides)
-    - [Previous Accumulative Cost Override Tariff (Electricity)](#previous-accumulative-cost-override-tariff-electricity)
+    - [Previous Accumulative Cost Override Tariff](#previous-accumulative-cost-override-tariff)
       - [How To Use](#how-to-use)
-    - [Previous Accumulative Cost Override (Electricity)](#previous-accumulative-cost-override-electricity)
+    - [Previous Accumulative Cost Override](#previous-accumulative-cost-override)
+  - [Previous Consumption Override Day Rates](#previous-consumption-override-day-rates)
 
 ## Current Rate
 
@@ -85,6 +90,39 @@ The next/upcoming rate that energy consumption will be charged at (including VAT
 | `valid_from` | `datetime` | The date/time when the rate is valid from |
 | `valid_to` | `datetime` | The date/time when the rate is valid to |
 
+## Current Day Rates
+
+`event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_day_rates`
+
+The state of this sensor states when the current day's rates were last updated. The attributes of this sensor exposes the current day's rates. This is disabled by default. 
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the current day |
+| `tariff_code` | `string` | The tariff code associated with current day's rates |
+
+## Previous Day Rates
+
+`event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_day_rates`
+
+The state of this sensor states when the previous day's rates were last updated. The attributes of this sensor exposes the previous day's rates. This is disabled by default. 
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous day |
+| `tariff_code` | `string` | The tariff code associated with previous day's rates |
+
+## Next Day Rates
+
+`event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_next_day_rates`
+
+The state of this sensor states when the next day's rates were last updated. The attributes of this sensor exposes the next day's rates. This is disabled by default. 
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the next day |
+| `tariff_code` | `string` | The tariff code associated with today's rates |
+
 ## Off Peak
 
 `binary_sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_off_peak`
@@ -185,6 +223,17 @@ The total cost for the previous day that applied during off peak hours. This is
 | `is_export` | `boolean` | Determines if the meter exports energy rather than imports |
 | `is_smart_meter` | `boolean` | Determines if the meter is considered smart by Octopus Energy |
 
+## Previous Consumption Day Rates
+
+`event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_consumption_rates`
+
+The state of this sensor states when the previous consumption's rates were last updated. This is typically the same as the previous day's rates, but could differ if the default offset is changed. The attributes of this sensor exposes the previous consumption's rates. This is disabled by default. 
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous consumption |
+| `tariff_code` | `string` | The tariff code associated with previous consumption's rates |
+
 ## Export Sensors
 
 If you export energy, then in addition you'll gain the above sensors with the name `export` present. E.g. `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_current_rate`.
@@ -313,7 +362,7 @@ See [below](#previous-accumulative-cost-override-tariff-electricity) for instruc
 
 > Please note: When updating the tariff depending on what previous consumption data is available, it can take up to 24 hours to update the cost. This will be improved in the future.
 
-### Previous Accumulative Cost Override Tariff (Electricity)
+### Previous Accumulative Cost Override Tariff
 
 `text.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_accumulative_cost_override_tariff`
 
@@ -330,10 +379,21 @@ Once you have found your target tariff
 
 > Please note: When updating the tariff depending on what previous consumption data is available, it can take up to 24 hours to update the cost. This will be improved in the future.
 
-### Previous Accumulative Cost Override (Electricity)
+### Previous Accumulative Cost Override
 
 `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_accumulative_cost_override`
 
 This is the cost of the previous electricity accumulation based on the specified tariff override.
 
 For attributes, see [Previous Accumulative Cost](#previous-accumulative-cost).
+
+## Previous Consumption Override Day Rates
+
+`event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_consumption_override_rates`
+
+The state of this sensor states when the previous consumption override's rates were last updated. The attributes of this sensor exposes the previous consumption override's rates. This is disabled by default. 
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `rates` | `list` | The list of rates applicable for the previous consumption override |
+| `tariff_code` | `string` | The tariff code associated with previous consumption override's rates |