KEBA KeEnergy API

A Python wrapper for the KEBA KeEnergy API.

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_temperature(position=2)

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

    # 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.DAY_TEMPERATURE: (20, None, 5),  # Write heat circuit on position 1 and 3 
            HeatCircuit.NIGHT_TEMPERATURE: (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_lower_limit_temperature(position)	int	Get lower limit temperature.
.get_upper_limit_temperature(position)	int	Get upper limit temperature.
.get_temperature(position)	float	Get 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_temperature(position)	float	Get minimum temperature.
.set_min_temperature(20, position)	float	Set minimum temperature.
.get_max_temperature(position)	float	Get maximum temperature.
.set_max_temperature(22, position)	float	Set maximum 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_inflow_temperature(position)	float	Get inflow temperature.
.get_reflux_temperature(position)	float	Get reflux 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.

Heat circuit

Endpoint	Request/Response	Description
.get_temperature(position)	float	Get temperature.
.get_day_temperature(position)	float	Get day temperature.
.set_day_temperature(20, position)	float	Set day temperature.
.get_day_temperature_threshold(position)	float	Get day temperature threshold.
.get_night_temperature(position)	float	Get night temperature.
.set_night_temperature(16, position)	float	Set night temperature.
.get_night_temperature_threshold(position)	float	Get night temperature threshold.
.get_holiday_temperature(position)	float	Get holiday temperature.
.set_holiday_temperature(14, position)	float	Set holiday temperature.
.get_temperature_offset(position)	float	Get temperature offset.
.set_temperature_offset(2, position)	float	Set 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.