Python Qube Heat Pump Client
Asyncio client for Qube heat pumps via Modbus TCP.
Installation
pip install python-qube-heatpump
Usage
import asyncio
from python_qube_heatpump import QubeClient
async def main():
client = QubeClient("192.168.1.100", port=502, unit_id=1)
await client.connect()
state = await client.read_state()
print(f"Outside temp: {state.temp_outside}°C")
print(f"Supply temp: {state.temp_supply}°C")
print(f"DHW temp: {state.temp_dhw}°C")
await client.disconnect()
asyncio.run(main())
Features
- Async Modbus TCP client using pymodbus
- Entity definitions for sensors, binary sensors, and switches
- FLOAT32 decoding with big endian (ABCD) byte order
- Type-safe dataclasses for entity definitions
- Device verification:
async_verify_device()checks that a host answers like a Qube controller (register 77 readable, also when it reads 0 on recent firmware) - mDNS device information: panel software version, controller firmware and UUID from the controller's advertisement
- Monotonic clamping with reset detection for the energy totals: sub-kWh jitter is clamped, while a drop of more than 1 kWh that persists for 3 consecutive reads is accepted as a counter reset (logged as a warning);
clear_monotonic_cache()forgets all baselines
Device information over mDNS
The controller advertises a _workstation._tcp mDNS service whose TXT record holds the software version shown on the panel, the controller firmware and a stable UUID. Register 77 (async_get_software_version()) reads 0.0 on recent firmware, so use this for the version instead:
from zeroconf.asyncio import AsyncZeroconf
from python_qube_heatpump import async_get_device_info
aiozc = AsyncZeroconf() # in Home Assistant: zeroconf.async_get_async_instance(hass)
info = await async_get_device_info("192.168.1.100", aiozc)
if info:
print(info.software_version, info.controller_firmware, info.uuid)
The lookup returns None when no record is found within the timeout (default 5 s), for example when mDNS is not forwarded between VLANs. parse_device_info(properties) parses TXT properties you already have, such as those from a zeroconf discovery.
Entity Definitions
The library provides pre-defined entity definitions for all Qube Modbus registers:
from python_qube_heatpump.entities import SENSORS, BINARY_SENSORS, SWITCHES
# Access entity definitions by key
temp_supply = SENSORS["temp_supply"]
print(f"Address: {temp_supply.address}, Unit: {temp_supply.unit}")
Vendor Documentation
The official Modbus register documentation from HR-Energy is available at:
- docs/modbus-lijst-qube-totaal.pdf (included in this repo)
- HR-Energy website
Related Projects
- qube_heatpump - Home Assistant HACS integration using this library
License
MIT License
1 maintainer
Metadata
1 maintainer
Release files for python-qube-heatpump 1.17.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| python_qube_heatpump-1.17.1.tar.gz | 103.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| python_qube_heatpump-1.17.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 128.9 kB
Release files / python_qube_heatpump-1.17.1.tar.gz
| Download URL | python_qube_heatpump-1.17.1.tar.gz |
|---|---|
| Size | 103.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2875f1104505a51f57ef0f22d0cb87c0a8f8ad8bb5abc7c1ba53cd2d8f9b250b
|
|
BLAKE2b-256 checksum How to use checksums |
df6dcf51acf6aaae8f832183345cd179c453a5bc18e579c287f8d029078e1101
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logRelease files / python_qube_heatpump-1.17.1-py3-none-any.whl
| Download URL | python_qube_heatpump-1.17.1-py3-none-any.whl |
|---|---|
| Size | 25.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aabcd269a2f4ab97bb456e0d745974e742dcee637e0307be2c1f53edc9cc76fb
|
|
BLAKE2b-256 checksum How to use checksums |
6d4c7224fcb98ea6aa1782546ada12beabe995066ee45b214cf606b158530f28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency log
