keba-keenergy-api

A Python wrapper for the KEBA KeEnergy API.


Keywords
api, component, custom, integration, keba, keenergy, hacs-component, hacs-integration, hacs-repository, hacs, hass, home, assistant, home-assistant, homeassistant, keba-keenergy, m-tec
License
Apache-2.0
Install
pip install keba-keenergy-api==1.12.10

Documentation

KEBA KeEnergy API

A Python wrapper for the KEBA KeEnergy API.

coverage-badge CI Version

license-url Typing: strict Code style: black Code style: Ruff

Getting started

pip install keba-keenergy-api

Usage

import asyncio
from typing import Any

from keba_keenergy_api import KebaKeEnergyAPI
from keba_keenergy_api.constants import HeatCircuit


async def main() -> None:
    client = KebaKeEnergyAPI(host="YOUR-IP-OR-HOSTNAME", ssl=True)

    # Get current outdoor temperature
    outdoor_temperature: float = await client.get_outdoor_temperature()

    # Get heat circuit temperature from heat circuit 2
    heat_circuit_temperature: float = await client.heat_circuit.get_target_temperature(position=2)

    # Read multiple values
    data: dict[str, tuple[float | int | str]] = await client.read_data(
        request=[
            HeatCircuit.TARGET_TEMPERATURE,
            HeatCircuit.TARGET_TEMPERATURE_DAY,
        ],
    )

    # Enable "day" mode for heat circuit 2
    await client.heat_circuit.set_operating_mode(mode="day", position=2)

    # Write multiple values
    await client.write_data(
        request={
            HeatCircuit.TARGET_TEMPERATURE_DAY: (20, None, 5),  # Write heat circuit on position 1 and 3 
            HeatCircuit.TARGET_TEMPERATURE_NIGHT: (16,),  # Write night temperature on position 1
        },
    )


asyncio.run(main())

By default, the library creates a new connection to KEBA KeEnergy API with each coroutine. If you are calling a large number of coroutines, an aiohttp ClientSession() can be used for connection pooling:

import asyncio

from keba_keenergy_api import KebaKeEnergyAPI

from aiohttp import ClientSession

async def main() -> None:
    async with ClientSession() as session:
        client = KebaKeEnergyAPI(host="YOUR-IP-OR-HOSTNAME", session=session, ssl=True)
        ...

asyncio.run(main())

API endpoints

Endpoint Description
.read_data(request, position, human_readable) Get multiple values with one http request.
.write_data(request) Write multiple values with one http request.

System

Endpoint Response Description
.get_info() str Get system information.
.get_device_info() str Get device information.
.get_outdoor_temperature() float Get outdoor temperature.
.get_operating_mode(position, human_readable) int or str Get operating mode as integer (0 is STANDBY, 1 is SUMMER, 2 is AUTO_HEAT, 3 is AUTO_COOL and 4 is AUTO).
.set_operating_mode(0, position, human_readable) int or str Set operating mode.

Hot water tank

Endpoint Request/Response Description
.get_current_temperature(position) float Get current temperature.
.get_operating_mode(position, human_readable) int or str Get operating mode as integer (0 is OFF, 1 is AUTO, 2 is DAY and 3 is NIGHT).
.set_operating_mode(0, position, human_readable) int or str Set operating mode.
.get_min_target_temperature(position) int Get minimum possible target temperature.
.get_max_target_temperature(position) int Get maximum possible target temperature.
.get_standby_temperature(position) float Get standby temperature.
.set_standby_temperature(20, position) float Set standby temperature.
.get_target_temperature(position) float Get target temperature.
.set_target_temperature(22, position) float Set target temperature.
.get_heat_request(position) int or str Get heat request.

Heat pump

Endpoint Response Description
.get_name(position) str Get head pump model name.
.get_state(position, human_readable) int or str Get heat pump state as integer (0 is STANDBY, 1 is FLOW and 2 is AUTO).
.get_operating_mode(position, human_readable) int or str Get operating mode as integer (0 is OFF, 1 is ON, 2 is BACKUP).
.get_circulation_pump(position) float Get circulation pump in percent.
.get_flow_temperature(position) float Get flow temperature.
.get_return_flow_temperature(position) float Get return flow temperature.
.get_source_input_temperature(position) float Get source input temperature.
.get_source_output_temperature(position) float Get source output temperature.
.get_compressor_input_temperature(position) float Get compressor input temperature.
.get_compressor_output_temperature(position) float Get compressor output temperature.
.get_compressor(position) float Get compressor in percent.
.get_high_pressure(position) float Get high pressure.
.get_low_pressure(position) float Get low pressure.
.get_heat_request(position) int or str Get heat request.
.get_compressor_power(position) float Get compressor power.
.get_heating_power(position) float Get heating power.
.get_hot_water_power(position) float Get hot water power.
.get_cop(position) float Get coefficient of performance.
.get_heating_energy(position) float Get heating energy.
.get_heating_energy_consumption(position) float Get heating energy consumption.
.get_heating_spf(position) float Get heating seasonal performance factor.
.get_cooling_energy(position) float Get cooling energy.
.get_cooling_energy_consumption(position) float Get cooling energy consumption.
.get_cooling_spf(position) float Get cooling seasonal performance factor.
.get_hot_water_energy(position) float Get hot water energy.
.get_hot_water_energy_consumption(position) float Get hot water electrical energy.
.get_hot_water_spf(position) float Get hot water seasonal performance factor.
.get_total_thermal_energy(position) float Get total thermal energy.
.get_total_energy_consumption(position) float Get total energy consumption.
.get_total_spf(position) float Get total seasonal performance factor.

Heat circuit

Endpoint Request/Response Description
.get_name(position) str Get heat circuit name.
.has_room_temperature(position) int or str Has room temperature.
.get_room_temperature(position) float Get room temperature.
.has_room_humidity(position) int or str Has room humidity.
.get_room_humidity(position) float Get room humidity.
.get_dew_point(position) float Get dew point.
.get_target_temperature(position) float Get target temperature.
.get_target_temperature_day(position) float Get taget temperature for the day.
.set_target_temperature_day(20, position) float Set taget temperature for the day.
.get_heating_limit_day(position) float Get the heating limit for the day.
.get_target_temperature_night(position) float Get target temperature for the night.
.set_target_temperature_night(16, position) float Set target temperature for the night.
.get_heating_limit_night(position) float Get the heating limit for the night.
.get_target_temperature_away(position) float Get target temperature when away.
.set_target_temperature_away(14, position) float Set target temperature when away.
.get_target_temperature_offset(position) float Get target temperature offset.
.set_target_temperature_offset(2, position) float Set target temperature offset.
.get_operating_mode(position, human_readable) int or str Get operating mode (0 is OFF and 3 is HEAT_UP).
.set_operating_mode(3, position) int or str Set operating mode.
.get_heat_request(position) int or str Get heat request.
.get_external_cool_request(position) int or str Get external cool request.
.get_external_heat_request(position) int or str Get external heat request.

Changelog

The changelog lives in the CHANGELOG.md document. The format is based on Keep a Changelog.

Contributing

We're happy about your contributions to the project!

You can get started by reading the CONTRIBUTING.md.

Donation

We put a lot of time into this project. If you like it, you can support us with a donation.

ko-fi