idealclima 0.1.0__py3-none-any.whl

idealclima/__init__.py

@@ -0,0 +1,18 @@
+"""Async Modbus library for Idealclima fan coil units."""
+
+from .enums import FanSpeed, IkaroMode, SkudoMode, TemperatureUnit
+from .ikaro import IkaroHW, IkaroReadings, IkaroSettings
+from .skudo import SkudoDCInverter, SkudoReadings, SkudoSettings
+
+__all__ = [
+    "FanSpeed",
+    "IkaroHW",
+    "IkaroMode",
+    "IkaroReadings",
+    "IkaroSettings",
+    "SkudoDCInverter",
+    "SkudoMode",
+    "SkudoReadings",
+    "SkudoSettings",
+    "TemperatureUnit",
+]

idealclima/base.py

@@ -0,0 +1,85 @@
+"""Shared base components and device logic for Idealclima units."""
+
+from __future__ import annotations
+
+from modbus_connection import ModbusUnit
+from modbus_connection.model import (
+    Component,
+    Device,
+    UpdateReport,
+    boolean,
+    enum,
+    gauge,
+)
+
+from .enums import FanSpeed
+
+
+class BaseIdealclimaReadings(Component):
+    """Common input registers shared by Idealclima fan coil units."""
+
+    register_space = "input"
+
+    ambient_temperature = gauge(46801, 0.1, signed=True, unit="°C")
+
+
+class BaseIdealclimaSettings(Component):
+    """Common holding registers shared by Idealclima fan coil units."""
+
+    register_space = "holding"
+    max_gap = 0
+
+    power = boolean(28301, writable=True, force_fc16=True)
+    fan_speed = enum(28303, FanSpeed, signed=True, writable=True, force_fc16=True)
+    target_temp_cool = gauge(
+        28310, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+    target_temp_heat = gauge(
+        28311, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+
+
+class BaseIdealclimaDevice[
+    R: BaseIdealclimaReadings,
+    S: BaseIdealclimaSettings,
+](Device):
+    """Base device wrapping readings and settings components."""
+
+    readings: R
+    settings: S
+
+    def __init__(self, unit: ModbusUnit, readings: R, settings: S) -> None:
+        """Initialize the device with a shared Modbus unit and its components."""
+        super().__init__(unit)
+        self.readings = readings
+        self.settings = settings
+
+    async def async_update_readings(self) -> UpdateReport:
+        """Poll input registers (live sensor readings)."""
+        return await self.async_poll(("readings",))
+
+    async def async_update_settings(self) -> UpdateReport:
+        """Poll holding registers (configuration and setpoints)."""
+        return await self.async_poll(("settings",))
+
+    async def async_update(self) -> UpdateReport:
+        """Poll both readings and settings."""
+        return await self.async_poll(("readings", "settings"))
+
+    async def _async_set_power(self, enabled: bool, *, stop_fan: bool) -> None:
+        """Set unit power and optionally stop the fan when turning off."""
+        await self.settings.write("power", enabled)
+        if not enabled and stop_fan:
+            await self.settings.write("fan_speed", FanSpeed.OFF)
+
+    async def async_set_fan_speed(self, speed: FanSpeed) -> None:
+        """Set the target fan speed (register 28303)."""
+        await self.settings.write("fan_speed", speed)
+
+    async def async_set_target_temp_cool(self, temperature: float) -> None:
+        """Set the cooling target temperature in °C (register 28310)."""
+        await self.settings.write("target_temp_cool", temperature)
+
+    async def async_set_target_temp_heat(self, temperature: float) -> None:
+        """Set the heating target temperature in °C (register 28311)."""
+        await self.settings.write("target_temp_heat", temperature)

idealclima/enums.py

@@ -0,0 +1,43 @@
+"""Enumerations for Idealclima Modbus fan coil units."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class FanSpeed(IntEnum):
+    """Fan speed values for holding register 28303."""
+
+    OFF = 0
+    SUPER_SILENCE = 1
+    LOW = 2
+    MEDIUM = 3
+    HIGH = 4
+    AUTO = 6
+
+
+class IkaroMode(IntEnum):
+    """Operating mode values for Comfosplit IKARO HW (register 28302)."""
+
+    OFF = 0
+    COOL = 1
+    DRY = 2
+    FAN_ONLY = 3
+    HEAT = 4
+
+
+class SkudoMode(IntEnum):
+    """Operating mode values for Radiantore SKUDO DC Inverter (register 28302)."""
+
+    AUTO = 0
+    COOL = 1
+    DRY = 2
+    FAN_ONLY = 3
+    HEAT = 4
+
+
+class TemperatureUnit(IntEnum):
+    """Display temperature unit for SKUDO DC Inverter (register 28319)."""
+
+    CELSIUS = 0
+    FAHRENHEIT = 1

idealclima/ikaro.py

@@ -0,0 +1,39 @@
+"""Comfosplit IKARO HW Modbus device model."""
+
+from __future__ import annotations
+
+from modbus_connection import ModbusUnit
+from modbus_connection.model import enum
+
+from .base import (
+    BaseIdealclimaDevice,
+    BaseIdealclimaReadings,
+    BaseIdealclimaSettings,
+)
+from .enums import IkaroMode
+
+
+class IkaroReadings(BaseIdealclimaReadings):
+    """Input registers for Comfosplit IKARO HW."""
+
+
+class IkaroSettings(BaseIdealclimaSettings):
+    """Holding registers for Comfosplit IKARO HW."""
+
+    mode = enum(28302, IkaroMode, signed=True, writable=True, force_fc16=True)
+
+
+class IkaroHW(BaseIdealclimaDevice[IkaroReadings, IkaroSettings]):
+    """Comfosplit IKARO HW fan coil unit."""
+
+    def __init__(self, unit: ModbusUnit) -> None:
+        """Initialize an IKARO HW device bound to a ModbusUnit."""
+        super().__init__(unit, IkaroReadings(unit), IkaroSettings(unit))
+
+    async def async_set_power(self, enabled: bool, *, stop_fan: bool = True) -> None:
+        """Turn the unit on or off; stops the fan by default when turning off."""
+        await self._async_set_power(enabled, stop_fan=stop_fan)
+
+    async def async_set_mode(self, mode: IkaroMode) -> None:
+        """Set the operating mode (register 28302)."""
+        await self.settings.write("mode", mode)

idealclima/py.typed

@@ -0,0 +1 @@
+

idealclima/skudo.py

@@ -0,0 +1,161 @@
+"""Radiantore SKUDO DC Inverter Modbus device model."""
+
+from __future__ import annotations
+
+from modbus_connection import ModbusUnit
+from modbus_connection.model import boolean, enum, gauge, integer
+
+from .base import (
+    BaseIdealclimaDevice,
+    BaseIdealclimaReadings,
+    BaseIdealclimaSettings,
+)
+from .enums import SkudoMode, TemperatureUnit
+
+
+def _validate_timer_hours(value: int) -> int:
+    """Validate SKUDO timer hours (0 = disabled, 1-11 hours)."""
+    if not 0 <= value <= 11:
+        raise ValueError(f"Timer hours must be between 0 and 11, got {value}")
+    return value
+
+
+class SkudoReadings(BaseIdealclimaReadings):
+    """Input registers for Radiantore SKUDO DC Inverter (46801-46810).
+
+    Uses ``max_gap = 1`` so 46801-46810 are polled in a single 0x04 request
+    while skipping 46803 and 46807.
+    """
+
+    max_gap = 1
+
+    coil_temperature = gauge(46802, 0.1, signed=True, unit="°C")
+    fan_rpm = integer(46804, signed=True, unit="rpm")
+    valve_command = boolean(46805)
+    power_state = boolean(46806)
+    motor_alarm = boolean(46808)
+    ambient_sensor_alarm = boolean(46809)
+    coil_sensor_alarm = boolean(46810)
+
+
+class SkudoSettings(BaseIdealclimaSettings):
+    """Holding registers for Radiantore SKUDO DC Inverter (28301-28327)."""
+
+    mode = enum(28302, SkudoMode, signed=True, writable=True, force_fc16=True)
+    key_lock = boolean(28304, writable=True, force_fc16=True)
+    sleep = boolean(28305, writable=True, force_fc16=True)
+    timer_off_hours = integer(
+        28306, signed=True, writable=_validate_timer_hours, force_fc16=True
+    )
+    timer_on_hours = integer(
+        28307, signed=True, writable=_validate_timer_hours, force_fc16=True
+    )
+    max_target_temp = gauge(
+        28308, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+    min_target_temp = gauge(
+        28309, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+    target_temp_auto_cool = gauge(
+        28312, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+    target_temp_auto_heat = gauge(
+        28313, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+    anti_draft_threshold = gauge(
+        28314, 0.1, signed=True, writable=True, unit="°C", force_fc16=True
+    )
+    anti_draft_enabled = boolean(28315, writable=True, force_fc16=True)
+    super_silence_enabled = boolean(28316, writable=True, force_fc16=True)
+    valve_present = boolean(28317, writable=True, force_fc16=True)
+    temperature_unit = enum(
+        28319, TemperatureUnit, signed=True, writable=True, force_fc16=True
+    )
+    key_lock_enabled = boolean(28322, writable=True, force_fc16=True)
+    remote_enabled_with_key_lock = boolean(28323, writable=True, force_fc16=True)
+    password_enabled = boolean(28324, writable=True, force_fc16=True)
+    fan_intermittent = boolean(28327, writable=True, force_fc16=True)
+
+
+class SkudoDCInverter(BaseIdealclimaDevice[SkudoReadings, SkudoSettings]):
+    """Radiantore SKUDO DC Inverter fan coil unit."""
+
+    def __init__(self, unit: ModbusUnit) -> None:
+        """Initialize a SKUDO DC Inverter device bound to a ModbusUnit."""
+        super().__init__(unit, SkudoReadings(unit), SkudoSettings(unit))
+
+    async def async_set_power(self, enabled: bool, *, stop_fan: bool = False) -> None:
+        """Turn the unit on or off."""
+        await self._async_set_power(enabled, stop_fan=stop_fan)
+
+    async def async_set_mode(self, mode: SkudoMode) -> None:
+        """Set the operating mode (register 28302)."""
+        await self.settings.write("mode", mode)
+
+    async def async_set_key_lock(self, locked: bool) -> None:
+        """Lock or unlock the onboard panel keys (register 28304)."""
+        await self.settings.write("key_lock", locked)
+
+    async def async_set_sleep(self, enabled: bool) -> None:
+        """Enable or disable sleep mode (register 28305)."""
+        await self.settings.write("sleep", enabled)
+
+    async def async_set_timer_off_hours(self, hours: int) -> None:
+        """Set auto-off timer in hours, 0 to disable or 1-11 (register 28306)."""
+        await self.settings.write("timer_off_hours", hours)
+
+    async def async_set_timer_on_hours(self, hours: int) -> None:
+        """Set auto-on timer in hours, 0 to disable or 1-11 (register 28307)."""
+        await self.settings.write("timer_on_hours", hours)
+
+    async def async_set_max_target_temp(self, temperature: float) -> None:
+        """Set maximum allowed target temperature in °C (register 28308)."""
+        await self.settings.write("max_target_temp", temperature)
+
+    async def async_set_min_target_temp(self, temperature: float) -> None:
+        """Set minimum allowed target temperature in °C (register 28309)."""
+        await self.settings.write("min_target_temp", temperature)
+
+    async def async_set_target_temp_auto_cool(self, temperature: float) -> None:
+        """Set cooling target temperature in auto mode in °C (register 28312)."""
+        await self.settings.write("target_temp_auto_cool", temperature)
+
+    async def async_set_target_temp_auto_heat(self, temperature: float) -> None:
+        """Set heating target temperature in auto mode in °C (register 28313)."""
+        await self.settings.write("target_temp_auto_heat", temperature)
+
+    async def async_set_anti_draft_threshold(self, temperature: float) -> None:
+        """Set coil anti-draft threshold temperature in °C (register 28314)."""
+        await self.settings.write("anti_draft_threshold", temperature)
+
+    async def async_set_anti_draft_enabled(self, enabled: bool) -> None:
+        """Enable or disable the anti-draft function (register 28315)."""
+        await self.settings.write("anti_draft_enabled", enabled)
+
+    async def async_set_super_silence_enabled(self, enabled: bool) -> None:
+        """Enable or disable super silence speed availability (register 28316)."""
+        await self.settings.write("super_silence_enabled", enabled)
+
+    async def async_set_valve_present(self, present: bool) -> None:
+        """Configure whether a water valve actuator is present (register 28317)."""
+        await self.settings.write("valve_present", present)
+
+    async def async_set_temperature_unit(self, unit: TemperatureUnit) -> None:
+        """Set display temperature unit (register 28319)."""
+        await self.settings.write("temperature_unit", unit)
+
+    async def async_set_key_lock_enabled(self, enabled: bool) -> None:
+        """Enable or disable the key lock feature (register 28322)."""
+        await self.settings.write("key_lock_enabled", enabled)
+
+    async def async_set_remote_enabled_with_key_lock(self, enabled: bool) -> None:
+        """Allow or block IR remote control when key lock is active (register 28323)."""
+        await self.settings.write("remote_enabled_with_key_lock", enabled)
+
+    async def async_set_password_enabled(self, enabled: bool) -> None:
+        """Enable or disable onboard terminal password protection (register 28324)."""
+        await self.settings.write("password_enabled", enabled)
+
+    async def async_set_fan_intermittent(self, enabled: bool) -> None:
+        """Enable or disable intermittent fan at target temperature (register 28327)."""
+        await self.settings.write("fan_intermittent", enabled)

idealclima-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.5
+Name: idealclima
+Version: 0.1.0
+Summary: Async Modbus library for Idealclima fan coil units (Comfosplit IKARO HW and Radiantore SKUDO DC Inverter)
+Project-URL: Homepage, https://github.com/crug80/idealclima
+Project-URL: Issues, https://github.com/crug80/idealclima/issues
+Author-email: crug80 <claudio@cr-tech.it>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: home-assistant,hvac,idealclima,ikaro,modbus,skudo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: modbus-connection>=4.12.7
+Provides-Extra: tmodbus
+Requires-Dist: modbus-connection[tmodbus]>=4.12.7; extra == 'tmodbus'
+Description-Content-Type: text/markdown
+
+# idealclima
+
+Async Python library for controlling Idealclima Modbus fan coil units ([**Comfosplit IKARO HW**](https://www.idealclima.eu/it/radiantori/terminali-idronici/ikaro) and [**Radiantore SKUDO DC Inverter**](https://www.idealclima.eu/it/radiantori/terminali-idronici/radiantore-skudo-dc-inverter)), built on [`modbus-connection`](https://github.com/home-assistant-libs/modbus-connection) for Home Assistant Core integrations and standalone use.
+
+## Requirements & Notes
+
+- **Modbus Unit Address**: Units ship with default Modbus address `15`, which only allows changing the address. **You must assign a unique address** (`1–32`) to each unit before using this library.
+- **Serial Settings**: `9600 bps`, `8N1`.
+- **Write Function**: Both models only support Modbus function `0x10` (Write Multiple Registers), which is enforced automatically via `force_fc16=True`.
+
+## Installation
+
+For Home Assistant or when providing your own `ModbusUnit`:
+
+```bash
+pip install idealclima
+```
+
+For standalone usage with `tmodbus`:
+
+```bash
+pip install "idealclima[tmodbus]"
+```
+
+## Usage
+
+```python
+import asyncio
+from modbus_connection import ModbusSerialParams
+from modbus_connection.tmodbus import ModbusConnection
+from idealclima import FanSpeed, IkaroHW, IkaroMode
+
+async def main() -> None:
+    conn = ModbusConnection(
+        ModbusSerialParams(device="/dev/ttyUSB0", baudrate=9600)
+    )
+    async with conn:
+        unit = conn.for_unit(20)
+        ikaro = IkaroHW(unit)
+        await ikaro.async_update()
+        print(ikaro.readings.ambient_temperature)
+        await ikaro.async_set_mode(IkaroMode.COOL)
+        await ikaro.async_set_fan_speed(FanSpeed.LOW)
+        await ikaro.async_set_power(True)
+
+asyncio.run(main())
+```

idealclima-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+idealclima/__init__.py,sha256=tFDCuGAdcP2UKj0-psm5FRGlBf8f_LnpyZHMAlI8MfI,458
+idealclima/base.py,sha256=487vkHEWi0kfmHVbPUVIE5bXh2PIduKcDdOPMKRLSEM,2930
+idealclima/enums.py,sha256=zUGQQ8z3H4DXWyf7bhsHMR2Uv-1a_YqT8AN2X99qmq4,784
+idealclima/ikaro.py,sha256=zliH-DuGfC4DaEodcdgFyQzwOBGnqKOMwBrP_bYPmEY,1281
+idealclima/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+idealclima/skudo.py,sha256=3c4irI71coumuWFW4dNPc-B9MZkd2L9LU-di8hqzEPs,7252
+idealclima-0.1.0.dist-info/METADATA,sha256=xq7va_v8rD-GWzfxVlouBpQaWYtqtDeJN1eFYTijDwY,2729
+idealclima-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+idealclima-0.1.0.dist-info/licenses/LICENSE,sha256=WF-SvnZSYa4oYEy6mMcwVLiVaJ6Nv9oa8uL4J_-VNR0,1082
+idealclima-0.1.0.dist-info/RECORD,,

idealclima-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

idealclima-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claudio Ruggeri - CR-Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.