Skip to content

Commit

Permalink
Update docs for easyEnergy integration (home-assistant#36292)
Browse files Browse the repository at this point in the history 
* Update the action parameter tables

* Add template section with examples

* Add instructions to remove the integration

* Add sections about use cases, data updates and known limitations
  • Loading branch information
@klaasnicolaas
klaasnicolaas authored Dec 12, 2024
1 parent c1c92c0 commit f4c9bc0
Showing 1 changed file with 68 additions and 23 deletions.
91 changes: 68 additions & 23 deletions source/_integrations/easyenergy.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ ha_platforms:
ha_integration_type: integration
---

The easyEnergy integration integrates the [easyEnergy](https://www.easyenergy.com) API platform with Home Assistant.
The **easyEnergy** {% term integration %} integrates the [easyEnergy](https://www.easyenergy.com) API platform with Home Assistant.

The integration makes it possible to retrieve the dynamic energy/gas prices
from easyEnergy in order to gain insight into the price trend of the day and
Expand All @@ -28,6 +28,18 @@ Companies that use the data from easyEnergy:

{% include integrations/config_flow.md %}

## Use cases

With the [energy dashboard](/energy) you can use the `current hour` price entity to calculate how much the electricity or gas has cost each hour based on the prices from easyEnergy. Or use one of the actions in combination with a [template sensor](#prices-sensor-with-response-data) to show the prices for the next 24 hours in a chart on your dashboard.

## Data updates

The integration will poll the easyEnergy API every 10 minutes to update the data in Home Assistant.

## Known limitations

The prices retrieved via the API are bare prices including VAT, however an energy company also charges other rates such as **energy tax** and **purchase costs**. The integration has no configuration option to add these values, but you could create a [template sensor](#all-in-price-sensor) for this.

## Sensors

The easyEnergy integration creates a number of sensor entities for both gas
Expand Down Expand Up @@ -73,12 +85,12 @@ The energy and gas prices are exposed using [actions](/docs/scripts/perform-acti

Fetches the hourly prices for gas.

| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `config_entry` | no | Config entry to use. | 013713c172577bada2874a32dbe44feb
| `incl_vat` | no | Defines whether the prices include or exclude VAT. Defaults to True | False
| `start` | yes | Start time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00
| `end` | yes | End time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00
| Data attribute | Optional | Description | Example |
| -------------- | -------- | ---------------------------------------------------- | -------------------------------- |
| `config_entry` | no | Config entry ID to use. | 013713c172577bada2874a32dbe44feb |
| `incl_vat` | no | Defines whether the prices include or exclude VAT. | False |
| `start` | yes | Start time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00 |
| `end` | yes | End time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00 |

#### Response data

Expand All @@ -103,12 +115,12 @@ The response data is a dictionary with the gas timestamps and prices as string a

Fetches the hourly prices for energy that you use (buy).

| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `config_entry` | no | Config entry to use. | 013713c172577bada2874a32dbe44feb
| `incl_vat` | no | Defines whether the prices include or exclude VAT. Defaults to True | False
| `start` | yes | Start time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00
| `end` | yes | End time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00
| Data attribute | Optional | Description | Example |
| -------------- | -------- | ---------------------------------------------------- | -------------------------------- |
| `config_entry` | no | Config entry ID to use. | 013713c172577bada2874a32dbe44feb |
| `incl_vat` | no | Defines whether the prices include or exclude VAT. | False |
| `start` | yes | Start time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00 |
| `end` | yes | End time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00 |

#### Response data

Expand All @@ -133,11 +145,11 @@ The response data is a dictionary with the energy timestamps as strings and pric

Fetches the hourly prices for energy that you return (sell).

| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `config_entry` | no | Config entry to use. | 013713c172577bada2874a32dbe44feb
| `start` | yes | Start time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00
| `end` | yes | End time to get prices from. Defaults to today 00:00:00 | 2023-01-01 00:00:00
| Data attribute | Optional | Description | Example |
| -------------- | -------- | ------------------------------------------------------- | -------------------------------- |
| `config_entry` | no | Config entry ID to use. | 013713c172577bada2874a32dbe44feb |
| `start` | yes | Start time to get prices. Defaults to today 00:00:00 | 2023-01-01 00:00:00 |
| `end` | yes | End time to get prices from. Defaults to today 00:00:00 | 2023-01-01 00:00:00 |

#### Response data

Expand All @@ -158,9 +170,13 @@ The response data is a dictionary with the energy timestamps as strings and pric
}
```

### Add response to template sensor
## Templates

You can use the response data in a template sensor that is updated every hour:
Create template sensors to display the prices in a chart or to calculate the all-in hour price.

### Prices sensor with response data

To use the response data from the actions, you can create a template sensor that updates every hour.

{% raw %}

Expand All @@ -171,16 +187,45 @@ template:
seconds: "*"
actions:
- action: easyenergy.get_energy_usage_prices
response_variable: response
response_variable: prices
data:
config_entry: "013713c172577bada2874a32dbe44feb"
config_entry: 013713c172577bada2874a32dbe44feb
incl_vat: true
sensor:
- name: Energy prices
device_class: timestamp
state: "{{ now() }}"
attributes:
prices: "{{ response.prices }}"
prices: "{{ prices }}"
```
{% endraw %}
### All-in price sensor
To calculate the all-in hour price, you can create a template sensor that calculates the price based on the current price, energy tax, and purchase costs.
{% raw %}
```yaml
template:
- sensor:
- name: easyEnergy all-in current price
unique_id: allin_current_price
icon: mdi:cash
unit_of_measurement: "€/kWh"
state_class: measurement
state: >
{% set energy_tax = PUT_HERE_THE_PRICE %}
{% set purch_costs = PUT_HERE_THE_PRICE %}
{% set current_price = states('sensor.easyenergy_today_energy_usage_current_hour_price') | float(0) %}
{{ (current_price + energy_tax + purch_costs) | round(2) }}
```
{% endraw %}
## Removing the integration
This integration follows standard integration removal steps. If you also use the template sensors, you need to remove them manually.
{% include integrations/remove_device_service.md %}

0 comments on commit f4c9bc0

Please sign in to comment.