Home Assistant Ista Calista Integration

March 8, 2026 · View on GitHub

GitHub CI Validation codecov HACS Badge GitHub License

This Home Assistant custom component integrates with the ista Calista portal to monitor your heating and water consumption. It provides sensors for your various meters and records historical data using Home Assistant's Long-Term Statistics feature.

Note: This integration currently supports the Spanish (ista.es) portal.

Open your Home Assistant instance and open a repository inside the HACS.

Features

  • Multi-Meter Support: Retrieves data for all supported meter types on your account:
    • Heating (kWh)
    • Hot Water (m³)
    • Cold Water (m³)
  • LTS & Billing History: Imports your full available consumption history AND billing/invoice data into Home Assistant.
  • Seasonal Analysis: Tracks your consumption across different seasons (e.g., Heating Season).
  • Invoice Management: Provides sensors for your latest invoice details and a service to download PDF bills directly.
  • Dynamic Entity Creation: Automatically creates and adds sensors as they appear in your ista account.

Prerequisites

  • An active account on the ista Calista portal.
  • Home Assistant (Version 2026.3.0 or newer).
  • HACS (Home Assistant Community Store) installed.

Installation

  1. Install via HACS (Recommended):

    • Go to HACS > Integrations.
    • Click the three dots in the top right and select "Custom repositories".
    • Add the URL https://github.com/herruzo99/ista-calista with the category "Integration".
    • Find the "Ista Calista" integration in the list and click "Install".
    • Restart Home Assistant when prompted.

  2. Manual Installation:

    • Download the latest release from the Releases page.
    • Copy the custom_components/ista_calista directory into your Home Assistant <config>/custom_components folder.
    • Restart Home Assistant.

Configuration

  1. Navigate to Settings > Devices & Services.
  2. Click Add Integration and search for "Ista Calista".
  3. Enter your ista Calista portal email and password.
  4. Consumption Start Date: Select the date from which to import historical data.
  5. Heating Season Start: Select the day and month when your heating season typically begins (used for seasonal consumption calculation).
  6. Click Submit.

Provided Entities

The integration creates a device for each physical meter, plus a global integration device for account-wide data.

Meter Entities

EntityUnitDescription
HeatingkWhCurrent meter reading for heating consumption
Hot Waterm³Current meter reading for hot water consumption
Waterm³Current meter reading for cold water consumption
Average Daily Consumption—Calculated average based on historical data
Seasonal Consumption—Consumption since the start of the current season

Billing & Invoice Entities (Global)

EntityUnitDescription
Latest Invoice ID—The identification number of your most recent bill
Latest Invoice Amount€The total amount of your latest invoice
Billed Reading Date—The date of the last officially billed reading
Billed Reading—The value of the last officially billed reading
Individual Bill (Multiple)—Binary sensors for each recent invoice with details in attributes

All consumption sensors feed directly into Home Assistant's Long-Term Statistics, making them available in the Energy Dashboard and compatible with history graphs.

How Data Is Updated

On first setup, the integration fetches the full consumption history starting from your chosen Consumption Start Date. This is a one-time operation and may take a moment.

On every subsequent update (default: every 24 hours), the integration fetches the last 30 days of readings. New readings are merged with the existing history, so no data is ever lost. Only net-new readings are pushed into Long-Term Statistics.

Options

After setup, you can adjust the integration's options:

  1. Navigate to the Ista Calista integration on the Devices & Services page.
  2. Click Configure.
  3. Adjust the Update Interval (1–168 hours) and Log Level as needed.

To change your account credentials or start date, click the three dots next to the integration and select Reconfigure.

Use Cases

  • Energy Dashboard: Add your heating (kWh) and water (m³) sensors to the Home Assistant Energy Dashboard to track consumption and costs over time alongside your electricity and gas usage.
  • Monthly Budget Alerts: Create an automation that sends a notification if your monthly heating consumption exceeds a set threshold.
  • Consumption Graphs: Use the history graph card or Apexcharts to visualize daily, monthly, or yearly consumption trends.
  • Comparative Analysis: Compare heating consumption across different months or years to identify seasonal patterns or the effect of home improvements.

Automation Examples

Alert when monthly heating exceeds a threshold

automation:
  - alias: "High heating consumption alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.living_room_heating
        above: 500
    action:
      - service: notify.mobile_app
        data:
          message: "Heating consumption has exceeded 500 kWh this period."

Log daily water reading

automation:
  - alias: "Log daily water reading"
    trigger:
      - platform: time
        at: "23:55:00"
    action:
      - service: logbook.log
        data:
          name: "Daily Water Reading"
          message: "{{ states('sensor.kitchen_water') }} m³"

Known Limitations

  • Spain only: This integration connects to the Spanish ista portal (oficina.ista.es). Other regional portals are not supported.
  • Polling only: Data is not pushed in real time. The integration polls the portal on a schedule (minimum 1 hour, default 24 hours). Readings from the portal itself may be delayed by days depending on your meter type.
  • Historical data window: The ista portal typically retains 1–2 years of history. Data older than that cannot be retrieved.
  • No meter control: This is a read-only integration. It cannot submit readings or interact with your meters in any way.
  • Single account per instance: Each integration entry corresponds to one ista account. If you have meters under multiple accounts, add the integration again for each account.

Troubleshooting

  • Authentication Failed: Double-check your credentials. If the problem persists, log in to the official ista portal to confirm your password is correct. If you are notified of an authentication error in Home Assistant, go to the integration and select Re-authenticate.
  • Sensors Not Appearing: After the initial setup, it can take a few minutes for the first data pull to complete. Check the Home Assistant logs for any errors related to ista_calista. Ensure the "Consumption Start Date" is set to a reasonable past date.
  • No History in Energy Dashboard: Long-Term Statistics are imported asynchronously after each coordinator update. Wait a few minutes after the first successful update and then refresh the Energy Dashboard.
  • Checking Logs: Set the Log Level to Debug in the integration options (under Configure) to get detailed output. Remember to set it back to Info once you are done troubleshooting to avoid log bloat.

For persistent issues, please open an issue on GitHub and include any relevant logs.

Removal

  1. Navigate to Settings > Devices & Services.
  2. Find the Ista Calista integration and click the three dots menu.
  3. Select Delete.

Removing the integration will delete all associated config entries. The Long-Term Statistics data recorded in your Home Assistant database will also be cleared automatically.

Development

This project uses Nix with flakes to provide a reproducible development environment. All dependencies, including the correct Python version, Home Assistant test libraries, and linters, are defined in flake.nix.

Prerequisites

  1. Install Nix: Follow the instructions at nixos.org/download.html.
  2. Enable Flakes: Enable flakes by editing your Nix configuration.
    • For NixOS: Add nix.settings.experimental-features = [ "nix-command" "flakes" ]; to your configuration.nix.
    • For other systems: Add experimental-features = nix-command flakes to ~/.config/nix/nix.conf.

Environment Setup

  1. Clone the repository:

    git clone https://github.com/herruzo99/ista-calista.git
cd ista-calista

  2. Activate the development shell:

    nix develop

    The first time you run this command, Nix will download and build all the necessary dependencies. This may take some time. Subsequent runs will be much faster as the dependencies will be cached. Once complete, you will be in a shell with all the required tools available.

Running Tests

The test suite is built using pytest and the pytest-homeassistant-custom-component library.

To run all tests:

pytest

To run a specific test file:

pytest tests/test_sensor.py

Contributing

Contributions to this project are welcome! Please follow standard development practices: lint your code, add tests for new functionality, and ensure existing tests pass. Use the Nix development environment to ensure consistency.

Disclaimer

This is an unofficial, third-party integration. It is not affiliated with, authorized, maintained, sponsored, or endorsed by ista International GmbH. Use this at your own risk. The developer is not responsible for any issues or damages that may arise from its use.