KEBA KeEnergy API

A Python wrapper for the KEBA KeEnergy API used by the Web HMI.

coverage-badge

Donation

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

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
from keba_keenergy_api.constants import HeatCircuitOperatingMode

async def main():
    client = KebaKeEnergyAPI(
        host="ap4400.local",
        username="test",
        password="test",
        ssl=True,
        skip_ssl_verification=True
    )

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

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

    # Read multiple values
    data = await client.read_data(
        request=[
            HeatCircuit.TARGET_TEMPERATURE,
            HeatCircuit.TARGET_TEMPERATURE_DAY
        ],
        extra_attributes=True
    )

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

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

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():
    async with ClientSession() as session:
        client = KebaKeEnergyAPI(
            host="ap4400.local",
            username="test",
            password="test",
            ssl=True,
            skip_ssl_verification=True,
            session=session
        )
        ...

asyncio.run(main())

⚠️ Write warnings

This is a low-level API that allows writing values outside the safe operating range. Improper use can damage heating systems and hardware. Always check the attributes, as these may contain minimum and maximum values.

Use at your own risk!

Example:

The upper limit from the hot water tank temperature is 52 °C. Do not write larger values under any circumstances, even if it would be possible.

{
    "name": "APPL.CtrlAppl.sParam.hotWaterTank[0].param.normalSetTempMax.value",
    "attributes": {
        "dynUpperLimit": 1,
        "formatId": "fmtTemp",
        "longText": "Temp. nom.",
        "lowerLimit": "0",
        "unitId": "Temp",
        "upperLimit": "52"
    },
    "value": "50"
}

And one last warning:

Attention! Writing values should remain within normal limits, as is the case with typical use of the Web HMI. Permanent and very frequent writing of values reduces the lifetime of the built-in flash memory. Be carefully!

Documentation

Read the full API documentation on api.superbox.one.

Changelog

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

Get Involved

The KEBA KeEnergy API is an open-source project and contributions are welcome. You can:

Report issues or request new features
Improve documentation
Contribute code
Support the project by starring it on GitHub ⭐

I'm happy about your contributions to the project! You can get started by reading the CONTRIBUTING.md.

Metadata

Release files for keba-keenergy-api 2.12.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for keba-keenergy-api 2.12.2
File	Size	Uploaded
keba_keenergy_api-2.12.2.tar.gz	253.7 kB	Jul 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for keba-keenergy-api 2.12.2
File	Interpreter	ABI	Platform	Reset
keba_keenergy_api-2.12.2-py3-none-any.whl 35.0 kB Jul 18, 2026	Python 3	none	any	Details

Total release size: 288.7 kB

Release files / keba_keenergy_api-2.12.2.tar.gz

Download URL	keba_keenergy_api-2.12.2.tar.gz
Size	253.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`936fd0008c6f8df5b82153912a3aada21164661fcade6380881d89a09d376a96`
BLAKE2b-256 checksum How to use checksums	`917cd6d381b53ccceb3ed5c4e58aa7b3b48c9c60620a08216acf10d31a76bfbf`
Upload date	Jul 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / keba_keenergy_api-2.12.2-py3-none-any.whl

Download URL	keba_keenergy_api-2.12.2-py3-none-any.whl
Size	35.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`939ffea3c9337a8072d96fa4a2c0be21ce71db18a55144a774047ae011171f8c`
BLAKE2b-256 checksum How to use checksums	`4b7b8601cc3875375210a572ed666083b15086a3c8caef72b1fa6f370d7c59fe`
Upload date	Jul 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`