Home Assistant integration for Oma Helen Python module. Periodically fetch your electricity consumption and estimated costs.

💡 Dashboard tip: I recommend using Tile cards for a nice, clean look like in the screenshot above.

The integration works with the following contract types:

• Exchange Electricity (=pörssisähkö) https://www.helen.fi/en/electricity/electricity-products-and-prices/exchange-electricity
• Market Price Electricity https://www.helen.fi/en/electricity/electricity-products-and-prices/marketpriceelectricity
• Fixed Price Electricity https://www.helen.fi/en/electricity/electricity-products-and-prices/fixed-price-basic-electricity

Tested against HA Core 2025.1 (the version pinned by the test suite). Older HA versions may work but are not verified.

The recommended way is to install via HACS

Then restart HA and add the Helen Energy Price integration via the UI in Settings > Devices & Services > Add integration and fill out the config form. Notice that you may now add even more entries directly from the UI in the integration settings!

This is not the recommended way.

Login to your HA with SSH

1. Go to the HA configuration root folder, which is the same folder where your configuration.yaml is located. Run the following commands

cd custom_components # create this folder if it does not exist
git clone https://github.com/carohauta/oma-helen-ha-integration.git helen_energy_temp
mv helen_energy_temp/custom_components/helen_energy/ .
rm -rf helen_energy_temp

2. Restart HA
3. Add the Helen Energy Price integration via the UI in Settings > Devices & Services > Add integration and fill out the config form. Notice that you may now add even more entries directly from the UI in the integration settings!

Follow either of the install steps above. Your old entities will be automatically migrated and historical data retained as you add your first entry. Remove any obsolete legacy yaml config related to this integration afterwards.

Depending on your contract type you will see one of the following new entities:

• sensor.helen_exchange_electricity
• sensor.helen_market_price_electricity
• sensor.helen_fixed_price_electricity

Multiple Entries: If you have multiple Helen Energy Price entries configured, additional entries will have numbered suffixes (e.g., sensor.helen_fixed_price_electricity_2, sensor.helen_monthly_consumption_3).

The state of each entity is the total energy cost of the ongoing month. In the state attributes you may find some other useful information like last month's and current month's energy consumptions, daily average consumption, current electricity price (in fixed contracts) etc. Use template sensors to display the attributes.

If you have chosen to include the transfer costs you will also see the following entity:

• sensor.helen_transfer_costs

The state of the entity shows the total energy transfer costs for the ongoing month. The price is presented in EUR and it includes the base price of your transfer contract. If Helen is not your energy transfer company, this entity does not serve a purpose and shows a default value of 0.0.

You may also see the following legacy entity:

• sensor.helen_monthly_consumption

The state of this sensor is the total energy consumption (in kWh) of the ongoing month. Note: This sensor is now legacy. For energy dashboard integration, use the automatically imported hourly statistics instead (see "Energy Dashboard Integration" section below).

The integration automatically imports hourly consumption statistics into Home Assistant's energy dashboard. This allows you to:

• Track your energy consumption hour-by-hour in the energy dashboard
• View detailed consumption graphs and patterns
• Compare consumption across different time periods
• See cost breakdowns (spot prices, fixed prices, etc.)

Statistics are automatically enabled for new installations. When you first set up the integration, it will:

1. Automatically backfill the last 72 hours of consumption data
2. Continue importing new hourly data as it becomes available from Helen's API

The statistics include:

• Hourly energy consumption (kWh) - Main consumption data for the energy dashboard
• Hourly spot price costs (EUR) - Track hourly costs with spot prices
• Hourly fixed price costs (EUR) - Track hourly costs with fixed price

If you want to import historical consumption data beyond the automatic 72-hour backfill, use the helen_energy.backfill_statistics service.

Call from the UI

You can call actions from the UI in 'Developer Tools → Actions'. Look for helen_energy.backfill_statistics. Then select a start_date and a contract.

Service Parameters:

• start_date (required): The date to start backfilling from (format: YYYY-MM-DD)
• config_entry_id (optional): Target a specific Helen Energy entry. If omitted, backfills all configured contracts.

Limitations:

• Maximum backfill range: 365 days (1 year)
• Always backfills from start_date to today
• All existing consumption/cost/fixed-cost statistics for the targeted contract(s) are cleared first, then rebuilt from start_date to today. This is intentional — keeping the cumulative sum chain consistent prevents positive/negative spikes that would otherwise appear if rows were inserted mid-chain.

Note: Backfilling large date ranges (especially 6+ months) may take several minutes to complete. The service runs in the background, so you can continue using Home Assistant normally.

Primary Method: Energy Dashboard and Statistics Cards

The integration automatically imports hourly consumption and cost statistics into Home Assistant. To visualize this data, use Home Assistant's built-in cards:

• Energy Dashboard (Settings > Dashboards > Energy) - Add the Helen Energy consumption statistic (search for your config entry title, e.g., "Helen Energy (Home) - Consumption") to track detailed hourly consumption patterns
• Statistics Graph Card - Display consumption and cost trends over time using the imported statistics
• Energy Distribution Card - Compare energy usage across different periods

These built-in cards provide the most comprehensive and performant way to visualize your energy data. The statistics offer hour-by-hour granularity, unlike the legacy sensor.helen_monthly_consumption which only provides monthly totals.

If you want to extract additional data from the sensor entity attributes (such as unit price, daily average consumption, or last month's values), you can create template sensors using the examples below.

Note: If you have added multiple Helen Energy Price entries, adjust the entity names in the templates below to match your specific entity names (e.g., sensor.helen_fixed_price_electricity_2 for the second entry).

Note: There can only be one template: section in configuration.yaml. If you already have one, add the - sensor: block inside it without repeating the template: key.

template:
  - sensor:
      - unique_id: helen_fixed_price_electricity_consumption
        name: helen_fixed_price_electricity_consumption
        unit_of_measurement: "kWh"
        device_class: energy
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_fixed_price_electricity', 'current_month_consumption') == None else state_attr('sensor.helen_fixed_price_electricity', 'current_month_consumption') | round() }}
      - unique_id: helen_fixed_price_electricity_consumption_last_month
        name: helen_fixed_price_electricity_consumption_last_month
        unit_of_measurement: "kWh"
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_fixed_price_electricity', 'last_month_consumption') == None else state_attr('sensor.helen_fixed_price_electricity', 'last_month_consumption') | round() }}
      - unique_id: helen_fixed_price_electricity_unit_price
        name: helen_fixed_price_electricity_unit_price
        unit_of_measurement: "c/kWh"
        icon: mdi:currency-eur
        state: >
          {{ 0 if state_attr('sensor.helen_fixed_price_electricity', 'fixed_unit_price') == None else state_attr('sensor.helen_fixed_price_electricity', 'fixed_unit_price') | round(2) }}
      - unique_id: helen_fixed_price_electricity_daily_average_consumption
        name: helen_fixed_price_electricity_daily_average_consumption
        unit_of_measurement: "kWh"
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_fixed_price_electricity', 'daily_average_consumption') == None else state_attr('sensor.helen_fixed_price_electricity', 'daily_average_consumption') | round() }}
      - unique_id: helen_fixed_price_electricity_total_cost_last_month
        name: helen_fixed_price_electricity_total_cost_last_month
        unit_of_measurement: "EUR"
        icon: mdi:currency-eur
        state: >
          {{ 0 if state_attr('sensor.helen_fixed_price_electricity', 'last_month_consumption') == None else (state_attr('sensor.helen_fixed_price_electricity', 'last_month_consumption') * state_attr('sensor.helen_fixed_price_electricity', 'fixed_unit_price') / 100 + state_attr('sensor.helen_fixed_price_electricity', 'contract_base_price')) | round() }}

template:
  - sensor:
      - unique_id: helen_exchange_energy_consumption
        name: helen_exchange_energy_consumption
        unit_of_measurement: "kWh"
        device_class: energy
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_exchange_electricity', 'current_month_consumption') == None else state_attr('sensor.helen_exchange_electricity', 'current_month_consumption') | round() }}
      - unique_id: helen_exchange_energy_consumption_last_month
        name: helen_exchange_energy_consumption_last_month
        unit_of_measurement: "kWh"
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_exchange_electricity', 'last_month_consumption') == None else state_attr('sensor.helen_exchange_electricity', 'last_month_consumption') | round() }}
      - unique_id: helen_exchange_energy_last_month_total_cost
        name: helen_exchange_energy_last_month_total_cost
        unit_of_measurement: "EUR"
        icon: mdi:currency-eur
        state: >
          {{ 0 if state_attr('sensor.helen_exchange_electricity', 'last_month_total_cost') == None else state_attr('sensor.helen_exchange_electricity', 'last_month_total_cost') | round() }}
      - unique_id: helen_exchange_energy_daily_average_consumption
        name: helen_exchange_energy_daily_average_consumption
        unit_of_measurement: "kWh"
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_exchange_electricity', 'daily_average_consumption') == None else state_attr('sensor.helen_exchange_electricity', 'daily_average_consumption') | round() }}

template:
  - sensor:
      - unique_id: helen_market_price_energy_consumption
        name: helen_market_price_energy_consumption
        unit_of_measurement: "kWh"
        device_class: energy
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_market_price_electricity', 'current_month_consumption') == None else state_attr('sensor.helen_market_price_electricity', 'current_month_consumption') | round() }}
      - unique_id: helen_market_price_energy_consumption_last_month
        name: helen_market_price_energy_consumption_last_month
        unit_of_measurement: "kWh"
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_market_price_electricity', 'last_month_consumption') == None else state_attr('sensor.helen_market_price_electricity', 'last_month_consumption') | round() }}
      - unique_id: helen_market_price_energy_last_month_total_cost
        name: helen_market_price_energy_last_month_total_cost
        unit_of_measurement: "EUR"
        icon: mdi:currency-eur
        state: >
          {{ 0 if state_attr('sensor.helen_market_price_electricity', 'last_month_total_cost') == None else state_attr('sensor.helen_market_price_electricity', 'last_month_total_cost') | round() }}
      - unique_id: helen_market_price_energy_daily_average_consumption
        name: helen_market_price_energy_daily_average_consumption
        unit_of_measurement: "kWh"
        icon: mdi:lightning-bolt
        state: >
          {{ 0 if state_attr('sensor.helen_market_price_electricity', 'daily_average_consumption') == None else state_attr('sensor.helen_market_price_electricity', 'daily_average_consumption') | round() }}
      - unique_id: helen_market_price_energy_price_current_month
        name: helen_market_price_energy_price_current_month
        unit_of_measurement: "c/kWh"
        icon: mdi:currency-eur
        state: >
          {{ 0 if state_attr('sensor.helen_market_price_electricity', 'price_current_month') == None else state_attr('sensor.helen_market_price_electricity', 'price_current_month') | round(2) }}