Next Release 2023-10

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/community.md

@@ -34,7 +34,7 @@ type: custom:apexcharts-card
       decimals: 1
   series:
     - entity: >-
-        sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_rate
+        event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_day_rates
       type: column
       name: ''
       color: yellow
@@ -45,7 +45,23 @@ type: custom:apexcharts-card
         in_header: false
         legend_value: false
       data_generator: |
-        return entity.attributes.all_rates.map((entry) => {
+        return entity.attributes.rates.map((entry) => {
+           return [new Date(entry.valid_from), entry.value_inc_vat];
+         });
+      offset: '-15min'
+    - entity: >-
+        event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_next_day_rates
+      type: column
+      name: ''
+      color: yellow
+      opacity: 1
+      stroke_width: 0
+      unit: W
+      show:
+        in_header: false
+        legend_value: false
+      data_generator: |
+        return entity.attributes.rates.map((entry) => {
            return [new Date(entry.valid_from), entry.value_inc_vat];
          });
       offset: '-15min'
@@ -138,9 +154,12 @@ If you're looking to combine import and export rates then create a card with the
 ```yaml
 type: custom:config-template-card
 entities:
-  - sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_rate
+  - event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_day_rates
+  - event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_next_day_rates
+  - >-
+    event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_current_day_rates
   - >-
-    sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_current_rate
+    event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_next_day_rates
 card:
   card_mod:
     style: |
@@ -169,19 +188,34 @@ card:
     stroke_width: 2
     fill_raw: 'null'
   series:
-    - entity: sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_rate
-      name: Import
+    - entity: event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_day_rates
+      name: Import today
+      curve: stepline
+      data_generator: |
+        return entity.attributes.rates.map((entry) => {
+          return [new Date(entry.valid_from), entry.value_inc_vat/100];
+        });
+    - entity: event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_next_day_rates
+      name: Import tomorrow
+      curve: stepline
+      data_generator: |
+        return entity.attributes.rates.map((entry) => {
+          return [new Date(entry.valid_from), entry.value_inc_vat/100];
+        });
+    - entity: >-
+        event.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_current_day_rates
+      name: Export
       curve: stepline
       data_generator: |
-        return entity.attributes.all_rates.map((entry) => {
+        return entity.attributes.rates.map((entry) => {
           return [new Date(entry.valid_from), entry.value_inc_vat/100];
         });
     - entity: >-
-        sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_current_rate
+        sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_export_next_day_rates
       name: Export
       curve: stepline
       data_generator: |
-        return entity.attributes.all_rates.map((entry) => {
+        return entity.attributes.rates.map((entry) => {
           return [new Date(entry.valid_from), entry.value_inc_vat/100];
         });
   apex_config:

_docs/events.md

@@ -0,0 +1,162 @@
+# 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number 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 |
+| `serial_number` | `string` | The serial number of the meter associated with these rates |