Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/superbox-dev/keba-keenergy-api
A Python wrapper for the KEBA KeEnergy API.
https://github.com/superbox-dev/keba-keenergy-api
api
Last synced: about 2 months ago
JSON representation
A Python wrapper for the KEBA KeEnergy API.
- Host: GitHub
- URL: https://github.com/superbox-dev/keba-keenergy-api
- Owner: superbox-dev
- License: apache-2.0
- Created: 2023-10-05T22:18:08.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-24T12:15:52.000Z (5 months ago)
- Last Synced: 2024-10-29T07:40:27.802Z (2 months ago)
- Topics: api
- Language: Python
- Homepage:
- Size: 170 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/superbox-dev/KEBA-KeEnergy-API/actions/workflows/ci.yml)
[](https://pypi.python.org/pypi/keba-keenergy-api)
[](https://github.com/superbox-dev/KEBA-KeEnergy-API/blob/main/LICENSE)
# KEBA KeEnergy API
A Python wrapper for the KEBA KeEnergy API.
## Getting started
```bash
pip install keba-keenergy-api
```
## Usage
```python
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:
```python
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](CHANGELOG.md) document. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## Contributing
We're happy about your contributions to the project!
You can get started by reading the [CONTRIBUTING.md](CONTRIBUTING.md).
## Donation
We put a lot of time into this project. If you like it, you can support us with a donation.
[](https://ko-fi.com/F2F0KXO6D)