From 4ecb5ba44fccdb30983bc782862e13ae4ae2de59 Mon Sep 17 00:00:00 2001 From: BottlecapDave Date: Sat, 7 Oct 2023 10:24:55 +0100 Subject: [PATCH] docs: Rearranged docs to have landing page --- README.md | 27 ++----------- _docs/readme.md | 76 +++++++++++++++++++++++++++++++++++ _docs/services.md | 82 ++++++++++++++++++++++++++++++++++++++ _docs/setup_account.md | 46 +-------------------- _docs/setup_target_rate.md | 65 +----------------------------- 5 files changed, 164 insertions(+), 132 deletions(-) create mode 100644 _docs/readme.md create mode 100644 _docs/services.md diff --git a/README.md b/README.md index 017fc5da..e120478e 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,7 @@ - [HACS](#hacs) - [Manual](#manual) - [How to setup](#how-to-setup) - - [Target Rate Sensors](#target-rate-sensors) - - [Events](#events) - - [Energy Dashboard](#energy-dashboard) - - [Community Contributions](#community-contributions) + - [Docs](#docs) - [FAQ](#faq) - [Sponsorship](#sponsorship) @@ -42,29 +39,13 @@ To install, place the contents of `custom_components` into the ` Please note, you will only have the same data exposed in the integration that is available within the app. There has been reports of gas not appearing within the app (and integration) straight away, so you might have to wait a few days for this to appear. Once it's available within the app, if you reload the integration (or restart Home Assistant) then the sensors should become available. + +For electricity sensors, see [here](./sensors/electricity.md#home-mini-sensors). + +For gas sensors, see [here](./sensors/gas.md#home-mini-sensors) + +### Intelligent + +If you are on the [intelligent tariff](https://octopus.energy/smart/intelligent-octopus/), then you'll get a few additional sensors when you install the integration. + +A full list of intelligent sensors can be found [here](./sensors/intelligent.md) + +> Please note: If you switch to the intelligent tariff after you have installed the integration, you will need to reload the integration or restart your Home Assistant instance. + +### Saving Sessions + +To support Octopus Energy's [saving sessions](https://octopus.energy/saving-sessions/). A full list of sensors can be found [here](./sensors/saving_sessions.md). + +## Target Rate Sensors + +These sensors calculate the lowest continuous or intermittent rates **within a 24 hour period** and turn on when these periods are active. If you are targeting an export meter, then the sensors will calculate the highest continuous or intermittent rates **within a 24 hour period** and turn on when these periods are active. + +These sensors can then be used in automations to turn on/off devices that save you (and the planet) energy and money. You can go through this flow as many times as you need target rate sensors. + +Please follow the [setup guide](./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](./events.md). + +## Energy Dashboard + +The core sensors have been designed to work with the energy dashboard. Please see the [guide](./energy_dashboard.md) for instructions on how to set this up. + +## Community Contributions + +A collection of community contributions can be found [here](./community.md). + +## FAQ + +Before raising anything, please read through the [faq](./faq.md). If you have questions, then you can raise a [discussion](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/discussions). If you have found a bug or have a feature request please [raise it](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/issues) using the appropriate report template. \ No newline at end of file diff --git a/_docs/services.md b/_docs/services.md new file mode 100644 index 00000000..6ecba502 --- /dev/null +++ b/_docs/services.md @@ -0,0 +1,82 @@ +# Services + +- [Services](#services) + +There are a few services available within this integration, which are detailed here. + +## Service octopus_energy.purge_invalid_external_statistic_ids + +Service for removing all external statistics that are associated with meters that don't have an active tariff. This is useful if you've been using the integration and obtained new smart meters. + +## Service octopus_energy.refresh_previous_consumption_data + +Service for refreshing the consumption/cost information for a given previous consumption entity. This is useful when you've just installed the integration and want old data brought in or a previous consumption sensor fails to import (e.g. data becomes available outside of the configured offset). The service will raise a notification when the refreshing starts and finishes. + +This service is only available for the following sensors + +- `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_accumulative_consumption` +- `sensor.octopus_energy_gas_{{METER_SERIAL_NUMBER}}_{{MPRN_NUMBER}}_previous_accumulative_consumption` + +## Service octopus_energy.update_target_config + +Service for updating a given [target rate's](./setup_target_rate.md) config. This allows you to change target rates sensors dynamically based on other outside criteria (e.g. you need to adjust the target hours to top up home batteries). + +> Please note this is temporary and will not persist between restarts. + +| Attribute | Optional | Description | +| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | +| `target.entity_id` | `no` | The name of the target sensor whose configuration is to be updated | +| `data.target_hours` | `yes` | The optional number of hours the target rate sensor should come on during a 24 hour period. Must be divisible by 0.5. | +| `data.target_start_time` | `yes` | The optional time the evaluation period should start. Must be in the format of `HH:MM`. | +| `data.target_end_time` | `yes` | The optional time the evaluation period should end. Must be in the format of `HH:MM`. | +| `data.target_offset` | `yes` | The optional offset to apply to the target rate when it starts. Must be in the format `(+/-)HH:MM:SS` | + +This can be used via automations in the following way. Assuming we have the following inputs. + +```yaml +input_number: + octopus_energy_target_hours: + name: Octopus Energy Target Hours + min: 0 + max: 24 + +input_text: + # From/to would ideally use input_datetime, but we need the time in a different format + octopus_energy_target_from: + name: Octopus Energy Target From + initial: "00:00" + octopus_energy_target_to: + name: Octopus Energy Target To + initial: "00:00" + octopus_energy_target_offset: + name: Octopus Energy Target Offset + initial: "-00:00:00" +``` + +Then an automation might look like the following + +```yaml +automations: + - alias: Update target rate config + trigger: + - platform: state + entity_id: + - input_number.octopus_energy_target_hours + - input_text.octopus_energy_target_from + - input_text.octopus_energy_target_to + - input_text.octopus_energy_target_offset + condition: [] + action: + - service: octopus_energy.update_target_config + data: + target_hours: > + "{{ states('input_number.octopus_energy_target_hours') | string }}" + target_start_time: > + {{ states('input_text.octopus_energy_target_from') }} + target_end_time: > + {{ states('input_text.octopus_energy_target_to') }} + target_offset: > + {{ states('input_text.octopus_energy_target_offset') }} + target: + entity_id: binary_sensor.octopus_energy_target_example +``` diff --git a/_docs/setup_account.md b/_docs/setup_account.md index bd299d8a..db2d3337 100644 --- a/_docs/setup_account.md +++ b/_docs/setup_account.md @@ -1,36 +1,15 @@ # Setup Account - [Setup Account](#setup-account) - - [Electricity Sensors](#electricity-sensors) - - [Gas Sensors](#gas-sensors) - - [Saving Sessions](#saving-sessions) - [Home Mini](#home-mini) - [Refresh Rate In Minutes](#refresh-rate-in-minutes) - - [Intelligent Tariff](#intelligent-tariff) - [Previous Consumption Days Offset](#previous-consumption-days-offset) - [Calorific Value](#calorific-value) - [Government Pricing Caps](#government-pricing-caps) - - [Services](#services) - - [Service octopus\_energy.purge\_invalid\_external\_statistic\_ids](#service-octopus_energypurge_invalid_external_statistic_ids) - - [Service octopus\_energy.refresh\_previous\_consumption\_data](#service-octopus_energyrefresh_previous_consumption_data) Setup is done entirely via the [integration UI](https://my.home-assistant.io/redirect/config_flow_start/?domain=octopus_energy). -When you setup your account, you will get a few sensors. - -## Electricity Sensors - -A full list of electricity sensors can be found [here](./sensors/electricity.md). - -## Gas Sensors - -A full list of gas sensors can be found [here](./sensors/gas.md). - -## Saving Sessions - -To support Octopus Energy's [saving sessions](https://octopus.energy/saving-sessions/). A full list of sensors can be found [here](./sensors/saving_sessions.md). - ## Home Mini If you are lucky enough to own an [Octopus Home Mini](https://octopus.energy/blog/octopus-home-mini/), you can now receive this data within Home Assistant. When setting up (or editing) your account within Home Assistant, you will need to check the box next to `I have a Home Mini`. This will gain the following sensors which can be added to the [energy dashboard](https://www.home-assistant.io/blog/2021/08/04/home-energy-management/): @@ -47,14 +26,6 @@ This determines how often data related to your Home Mini is retrieved from Octop You can adjust these independently between gas and electricity. -## Intelligent Tariff - -If you are on the [intelligent tariff](https://octopus.energy/smart/intelligent-octopus/), then you'll get a few additional sensors when you install the integration. - -A full list of intelligent sensors can be found [here](./sensors/intelligent.md) - -> Please note: If you switch to the intelligent tariff after you have installed the integration, you will need to reload the integration or restart your Home Assistant instance. - ## Previous Consumption Days Offset By default, the previous consumptions sensors are set up to pull and record the last days worth of data, to be as up-to-date as possible via the default available data. However, some people may find that Octopus Energy are delayed in being able to retrieve data from their smart meters, typically their gas smart meters. Therefore you can adjust the number of days the previous consumption sensors pull data from. This defaults to the previous day, but increasing to `2` would look at 48 hours behind, and so on. You can adjust this independently between gas and electricity. @@ -65,19 +36,4 @@ When calculating gas costs, a calorific value is included in the calculation. Un ## Government Pricing Caps -There has been inconsistencies across tariffs on whether government pricing caps are included or not. Therefore the ability to configure pricing caps has been added within you account. Please note that while rates are reflected straight away, consumption based sensors may take up to 24 hours to reflect. This is due to how they look at data and cannot be changed. - -## Services - -### Service octopus_energy.purge_invalid_external_statistic_ids - -Service for removing all external statistics that are associated with meters that don't have an active tariff. This is useful if you've been using the integration and obtained new smart meters. - -### Service octopus_energy.refresh_previous_consumption_data - -Service for refreshing the consumption/cost information for a given previous consumption entity. This is useful when you've just installed the integration and want old data brought in or a previous consumption sensor fails to import (e.g. data becomes available outside of the configured offset). The service will raise a notification when the refreshing starts and finishes. - -This service is only available for the following sensors - -- `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_previous_accumulative_consumption` -- `sensor.octopus_energy_gas_{{METER_SERIAL_NUMBER}}_{{MPRN_NUMBER}}_previous_accumulative_consumption` \ No newline at end of file +There has been inconsistencies across tariffs on whether government pricing caps are included or not. Therefore the ability to configure pricing caps has been added within you account. Please note that while rates are reflected straight away, consumption based sensors may take up to 24 hours to reflect. This is due to how they look at data and cannot be changed. \ No newline at end of file diff --git a/_docs/setup_target_rate.md b/_docs/setup_target_rate.md index 4e655018..81f77d05 100644 --- a/_docs/setup_target_rate.md +++ b/_docs/setup_target_rate.md @@ -11,7 +11,6 @@ - [Invert Target Rates](#invert-target-rates) - [Attributes](#attributes) - [Services](#services) - - [Service octopus\_energy.update\_target\_config](#service-octopus_energyupdate_target_config) - [Examples](#examples) - [Continuous](#continuous) - [Intermittent](#intermittent) @@ -104,69 +103,7 @@ The following attributes are available on each sensor ## Services -### Service octopus_energy.update_target_config - -Service for updating a given target rate's config. This allows you to change target rates sensors dynamically based on other outside criteria (e.g. you need to adjust the target hours to top up home batteries). - -> Please note this is temporary and will not persist between restarts. - -| Attribute | Optional | Description | -| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `target.entity_id` | `no` | The name of the target sensor whose configuration is to be updated | -| `data.target_hours` | `yes` | The optional number of hours the target rate sensor should come on during a 24 hour period. Must be divisible by 0.5. | -| `data.target_start_time` | `yes` | The optional time the evaluation period should start. Must be in the format of `HH:MM`. | -| `data.target_end_time` | `yes` | The optional time the evaluation period should end. Must be in the format of `HH:MM`. | -| `data.target_offset` | `yes` | The optional offset to apply to the target rate when it starts. Must be in the format `(+/-)HH:MM:SS` | - -This can be used via automations in the following way. Assuming we have the following inputs. - -```yaml -input_number: - octopus_energy_target_hours: - name: Octopus Energy Target Hours - min: 0 - max: 24 - -input_text: - # From/to would ideally use input_datetime, but we need the time in a different format - octopus_energy_target_from: - name: Octopus Energy Target From - initial: "00:00" - octopus_energy_target_to: - name: Octopus Energy Target To - initial: "00:00" - octopus_energy_target_offset: - name: Octopus Energy Target Offset - initial: "-00:00:00" -``` - -Then an automation might look like the following - -```yaml -automations: - - alias: Update target rate config - trigger: - - platform: state - entity_id: - - input_number.octopus_energy_target_hours - - input_text.octopus_energy_target_from - - input_text.octopus_energy_target_to - - input_text.octopus_energy_target_offset - condition: [] - action: - - service: octopus_energy.update_target_config - data: - target_hours: > - "{{ states('input_number.octopus_energy_target_hours') | string }}" - target_start_time: > - {{ states('input_text.octopus_energy_target_from') }} - target_end_time: > - {{ states('input_text.octopus_energy_target_to') }} - target_offset: > - {{ states('input_text.octopus_energy_target_offset') }} - target: - entity_id: binary_sensor.octopus_energy_target_example -``` +There are services available associated with target rate sensors. Please review them in the [services doc](./services.md). ## Examples