python-qube-heatpump 1.2.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

python_qube_heatpump/__init__.py

@@ -1,3 +1,39 @@
+"""Python library for Qube Heat Pump Modbus communication."""
+
 from .client import QubeClient
+from .const import (
+    DataType,
+    ModbusType,
+    StatusCode,
+    STATUS_CODE_MAP,
+    get_status_code,
+)
+from .entities import (
+    BINARY_SENSORS,
+    EntityDef,
+    InputType,
+    Platform,
+    SENSORS,
+    SWITCHES,
+)
+from .models import QubeState
 
-__all__ = ["QubeClient"]
+__all__ = [
+    # Client
+    "QubeClient",
+    # State
+    "QubeState",
+    # Entity definitions
+    "BINARY_SENSORS",
+    "EntityDef",
+    "InputType",
+    "Platform",
+    "SENSORS",
+    "SWITCHES",
+    # Constants
+    "DataType",
+    "ModbusType",
+    "StatusCode",
+    "STATUS_CODE_MAP",
+    "get_status_code",
+]

python_qube_heatpump/client.py

@@ -1,12 +1,16 @@
 """Client for Qube Heat Pump."""
 
+from __future__ import annotations
+
 import logging
 import struct
-from typing import Optional
+from typing import Any
 
 from pymodbus.client import AsyncModbusTcpClient
 
 from . import const
+from .entities import BINARY_SENSORS, SENSORS, SWITCHES, EntityDef
+from .entities.base import DataType, InputType
 from .models import QubeState
 
 _LOGGER = logging.getLogger(__name__)
@@ -46,15 +50,37 @@ class QubeClient:
         async def _read(const_def):
             return await self.read_value(const_def)
 
-        # Fetch basic sensors
+        # Fetch temperature sensors
         state.temp_supply = await _read(const.TEMP_SUPPLY)
         state.temp_return = await _read(const.TEMP_RETURN)
-        state.temp_outside = await _read(const.TEMP_OUTSIDE)
+        state.temp_source_in = await _read(const.TEMP_SOURCE_IN)
+        state.temp_source_out = await _read(const.TEMP_SOURCE_OUT)
+        state.temp_room = await _read(const.TEMP_ROOM)
         state.temp_dhw = await _read(const.TEMP_DHW)
+        state.temp_outside = await _read(const.TEMP_OUTSIDE)
+
+        # Fetch power and energy sensors
+        state.power_thermic = await _read(const.POWER_THERMIC)
+        state.power_electric = await _read(const.POWER_ELECTRIC_CALC)
+        state.energy_total_electric = await _read(const.ENERGY_ELECTRIC_TOTAL)
+        state.energy_total_thermic = await _read(const.ENERGY_THERMIC_TOTAL)
+        state.cop_calc = await _read(const.COP_CALC)
+
+        # Fetch operation sensors
+        state.status_code = await _read(const.STATUS_CODE)
+        state.compressor_speed = await _read(const.COMPRESSOR_SPEED)
+        state.flow_rate = await _read(const.FLOW_RATE)
+
+        # Fetch setpoints (holding registers)
+        state.setpoint_room_heat_day = await _read(const.SETPOINT_HEAT_DAY)
+        state.setpoint_room_heat_night = await _read(const.SETPOINT_HEAT_NIGHT)
+        state.setpoint_room_cool_day = await _read(const.SETPOINT_COOL_DAY)
+        state.setpoint_room_cool_night = await _read(const.SETPOINT_COOL_NIGHT)
+        state.setpoint_dhw = await _read(const.USER_DHW_SETPOINT)
 
         return state
 
-    async def read_value(self, definition: tuple) -> Optional[float]:
+    async def read_value(self, definition: tuple) -> float | None:
         """Read a single value based on the constant definition."""
         address, reg_type, data_type, scale, offset = definition
 
@@ -134,3 +160,255 @@ class QubeClient:
         except Exception as e:
             _LOGGER.error("Exception reading address %s: %s", address, e)
             return None
+
+    async def read_entity(self, entity: EntityDef) -> Any:
+        """Read a single entity value based on EntityDef.
+
+        Args:
+            entity: The entity definition to read.
+
+        Returns:
+            The read value (float, int, or bool depending on entity type).
+        """
+        # Determine register count based on data type
+        if entity.data_type in (DataType.FLOAT32, DataType.UINT32, DataType.INT32):
+            count = 2
+        else:
+            count = 1
+
+        try:
+            # Read based on input type
+            if entity.input_type == InputType.COIL:
+                result = await self._client.read_coils(
+                    entity.address, count=1, slave=self.unit
+                )
+                if result.isError():
+                    _LOGGER.warning("Error reading coil %s", entity.address)
+                    return None
+                return bool(result.bits[0])
+
+            if entity.input_type == InputType.DISCRETE_INPUT:
+                result = await self._client.read_discrete_inputs(
+                    entity.address, count=1, slave=self.unit
+                )
+                if result.isError():
+                    _LOGGER.warning("Error reading discrete input %s", entity.address)
+                    return None
+                return bool(result.bits[0])
+
+            if entity.input_type == InputType.INPUT_REGISTER:
+                result = await self._client.read_input_registers(
+                    entity.address, count, slave=self.unit
+                )
+            else:  # HOLDING_REGISTER
+                result = await self._client.read_holding_registers(
+                    entity.address, count, slave=self.unit
+                )
+
+            if result.isError():
+                _LOGGER.warning("Error reading address %s", entity.address)
+                return None
+
+            regs = result.registers
+            val: float | int = 0
+
+            # Decode based on data type
+            if entity.data_type == DataType.FLOAT32:
+                int_val = (regs[1] << 16) | regs[0]
+                val = struct.unpack(">f", struct.pack(">I", int_val))[0]
+            elif entity.data_type == DataType.INT16:
+                val = regs[0]
+                if val > 32767:
+                    val -= 65536
+            elif entity.data_type == DataType.UINT16:
+                val = regs[0]
+            elif entity.data_type == DataType.UINT32:
+                val = (regs[1] << 16) | regs[0]
+            elif entity.data_type == DataType.INT32:
+                val = (regs[1] << 16) | regs[0]
+                if val > 2147483647:
+                    val -= 4294967296
+
+            # Apply scale and offset
+            if entity.scale is not None:
+                val = val * entity.scale
+            if entity.offset is not None:
+                val = val + entity.offset
+
+            return val
+
+        except Exception as e:
+            _LOGGER.error("Exception reading entity %s: %s", entity.key, e)
+            return None
+
+    async def read_sensor(self, key: str) -> float | int | None:
+        """Read a sensor value by key.
+
+        Args:
+            key: The sensor key (e.g., 'temp_supply').
+
+        Returns:
+            The sensor value, or None if not found or error.
+        """
+        entity = SENSORS.get(key)
+        if entity is None:
+            _LOGGER.warning("Unknown sensor key: %s", key)
+            return None
+        return await self.read_entity(entity)
+
+    async def read_binary_sensor(self, key: str) -> bool | None:
+        """Read a binary sensor value by key.
+
+        Args:
+            key: The binary sensor key (e.g., 'dout_srcpmp_val').
+
+        Returns:
+            The binary sensor value, or None if not found or error.
+        """
+        entity = BINARY_SENSORS.get(key)
+        if entity is None:
+            _LOGGER.warning("Unknown binary sensor key: %s", key)
+            return None
+        return await self.read_entity(entity)
+
+    async def read_switch(self, key: str) -> bool | None:
+        """Read a switch state by key.
+
+        Args:
+            key: The switch key (e.g., 'bms_summerwinter').
+
+        Returns:
+            The switch state, or None if not found or error.
+        """
+        entity = SWITCHES.get(key)
+        if entity is None:
+            _LOGGER.warning("Unknown switch key: %s", key)
+            return None
+        return await self.read_entity(entity)
+
+    async def read_all_sensors(self) -> dict[str, Any]:
+        """Read all sensor values.
+
+        Returns:
+            Dictionary mapping sensor keys to their values.
+        """
+        result: dict[str, Any] = {}
+        for key, entity in SENSORS.items():
+            result[key] = await self.read_entity(entity)
+        return result
+
+    async def read_all_binary_sensors(self) -> dict[str, bool | None]:
+        """Read all binary sensor values.
+
+        Returns:
+            Dictionary mapping binary sensor keys to their values.
+        """
+        result: dict[str, bool | None] = {}
+        for key, entity in BINARY_SENSORS.items():
+            result[key] = await self.read_entity(entity)
+        return result
+
+    async def read_all_switches(self) -> dict[str, bool | None]:
+        """Read all switch states.
+
+        Returns:
+            Dictionary mapping switch keys to their states.
+        """
+        result: dict[str, bool | None] = {}
+        for key, entity in SWITCHES.items():
+            result[key] = await self.read_entity(entity)
+        return result
+
+    async def write_switch(self, key: str, value: bool) -> bool:
+        """Write a switch state by key.
+
+        Args:
+            key: The switch key (e.g., 'bms_summerwinter').
+            value: True to turn on, False to turn off.
+
+        Returns:
+            True if write succeeded, False otherwise.
+        """
+        entity = SWITCHES.get(key)
+        if entity is None:
+            _LOGGER.warning("Unknown switch key: %s", key)
+            return False
+
+        if not entity.writable:
+            _LOGGER.warning("Switch %s is not writable", key)
+            return False
+
+        try:
+            result = await self._client.write_coil(
+                entity.address, value, slave=self.unit
+            )
+            if result.isError():
+                _LOGGER.warning("Error writing switch %s", key)
+                return False
+            return True
+        except Exception as e:
+            _LOGGER.error("Exception writing switch %s: %s", key, e)
+            return False
+
+    async def write_setpoint(self, key: str, value: float) -> bool:
+        """Write a setpoint value by key.
+
+        Args:
+            key: The sensor key for the setpoint (e.g., 'setpoint_dhw').
+            value: The value to write.
+
+        Returns:
+            True if write succeeded, False otherwise.
+        """
+        entity = SENSORS.get(key)
+        if entity is None:
+            _LOGGER.warning("Unknown sensor key: %s", key)
+            return False
+
+        if not entity.writable:
+            _LOGGER.warning("Sensor %s is not writable", key)
+            return False
+
+        if entity.input_type != InputType.HOLDING_REGISTER:
+            _LOGGER.warning("Sensor %s is not a holding register", key)
+            return False
+
+        try:
+            # Reverse scale/offset if needed
+            write_value = value
+            if entity.offset is not None:
+                write_value = write_value - entity.offset
+            if entity.scale is not None:
+                write_value = write_value / entity.scale
+
+            # Encode based on data type
+            if entity.data_type == DataType.FLOAT32:
+                # Pack as big-endian float, then split into two registers
+                packed = struct.pack(">f", write_value)
+                int_val = struct.unpack(">I", packed)[0]
+                regs = [int_val & 0xFFFF, (int_val >> 16) & 0xFFFF]
+                result = await self._client.write_registers(
+                    entity.address, regs, slave=self.unit
+                )
+            elif entity.data_type == DataType.INT16:
+                if write_value < 0:
+                    write_value = int(write_value) + 65536
+                result = await self._client.write_register(
+                    entity.address, int(write_value), slave=self.unit
+                )
+            elif entity.data_type == DataType.UINT16:
+                result = await self._client.write_register(
+                    entity.address, int(write_value), slave=self.unit
+                )
+            else:
+                _LOGGER.warning("Unsupported data type for writing: %s", entity.data_type)
+                return False
+
+            if result.isError():
+                _LOGGER.warning("Error writing setpoint %s", key)
+                return False
+            return True
+
+        except Exception as e:
+            _LOGGER.error("Exception writing setpoint %s: %s", key, e)
+            return False

python_qube_heatpump/const.py

@@ -20,6 +20,42 @@ class DataType(str, Enum):
     UINT32 = "uint32"
 
 
+class StatusCode(str, Enum):
+    """Heat pump status codes."""
+
+    STANDBY = "standby"
+    ALARM = "alarm"
+    KEYBOARD_OFF = "keyboard_off"
+    COMPRESSOR_STARTUP = "compressor_startup"
+    COMPRESSOR_SHUTDOWN = "compressor_shutdown"
+    COOLING = "cooling"
+    HEATING = "heating"
+    START_FAIL = "start_fail"
+    HEATING_DHW = "heating_dhw"
+    UNKNOWN = "unknown"
+
+
+# Map numeric status codes to StatusCode enum values
+STATUS_CODE_MAP: dict[int, StatusCode] = {
+    1: StatusCode.STANDBY,
+    2: StatusCode.ALARM,
+    6: StatusCode.KEYBOARD_OFF,
+    8: StatusCode.COMPRESSOR_STARTUP,
+    9: StatusCode.COMPRESSOR_SHUTDOWN,
+    14: StatusCode.STANDBY,
+    15: StatusCode.COOLING,
+    16: StatusCode.HEATING,
+    17: StatusCode.START_FAIL,
+    18: StatusCode.STANDBY,
+    22: StatusCode.HEATING_DHW,
+}
+
+
+def get_status_code(code: int) -> StatusCode:
+    """Convert numeric status code to StatusCode enum."""
+    return STATUS_CODE_MAP.get(code, StatusCode.UNKNOWN)
+
+
 # Register definitions (Address, Type, Data Type, Scale, Offset)
 # Scale/Offset are None if not used.
 # Format: KEY = (Address, ModbusType, DataType, Scale, Offset)

python_qube_heatpump/entities/__init__.py

@@ -0,0 +1,16 @@
+"""Entity definitions for Qube Heat Pump."""
+
+from .base import DataType, EntityDef, InputType, Platform
+from .binary_sensors import BINARY_SENSORS
+from .sensors import SENSORS
+from .switches import SWITCHES
+
+__all__ = [
+    "BINARY_SENSORS",
+    "DataType",
+    "EntityDef",
+    "InputType",
+    "Platform",
+    "SENSORS",
+    "SWITCHES",
+]

python_qube_heatpump/entities/base.py

@@ -0,0 +1,77 @@
+"""Base classes and enums for entity definitions."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class InputType(str, Enum):
+    """Modbus input type for reading values."""
+
+    COIL = "coil"
+    DISCRETE_INPUT = "discrete_input"
+    INPUT_REGISTER = "input"
+    HOLDING_REGISTER = "holding"
+
+
+class DataType(str, Enum):
+    """Data type for register values."""
+
+    FLOAT32 = "float32"
+    INT16 = "int16"
+    UINT16 = "uint16"
+    INT32 = "int32"
+    UINT32 = "uint32"
+
+
+class Platform(str, Enum):
+    """Home Assistant platform type."""
+
+    SENSOR = "sensor"
+    BINARY_SENSOR = "binary_sensor"
+    SWITCH = "switch"
+
+
+@dataclass(frozen=True)
+class EntityDef:
+    """Definition of a Qube heat pump entity.
+
+    This dataclass defines the protocol-level properties of an entity.
+    Home Assistant-specific metadata (device_class, state_class, etc.)
+    should be added by the integration, not here.
+    """
+
+    # Identity
+    key: str
+    """Unique identifier, e.g., 'temp_supply'."""
+
+    name: str
+    """Human-readable name, e.g., 'Supply temperature'."""
+
+    # Modbus specifics
+    address: int
+    """Register or coil address."""
+
+    input_type: InputType
+    """How to read from device (coil, discrete_input, input, holding)."""
+
+    data_type: DataType | None = None
+    """Data type for registers. None for coils/discrete inputs."""
+
+    # Platform hint
+    platform: Platform = Platform.SENSOR
+    """Which HA platform this entity belongs to."""
+
+    # Value transformation
+    scale: float | None = None
+    """Multiply raw value by this factor."""
+
+    offset: float | None = None
+    """Add this to the scaled value."""
+
+    # Unit (protocol-level)
+    unit: str | None = None
+    """Unit of measurement, e.g., '°C', 'kWh', 'W'."""
+
+    # Write capability
+    writable: bool = False
+    """Whether this entity can be written to."""