python-swidget 1.4.15__tar.gz → 1.4.16__tar.gz

{python_swidget-1.4.15 → python_swidget-1.4.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-swidget
-Version: 1.4.15
+Version: 1.4.16
 Summary: Python API for Swidget smart devices
 Home-page: https://github.com/swidget/python-swidget
 License: GPL-3.0-or-later

{python_swidget-1.4.15 → python_swidget-1.4.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-swidget"
-version = "1.4.15"
+version = "1.4.16"
 description = "Python API for Swidget smart devices"
 license = "GPL-3.0-or-later"
 authors = ["Swidget"]

{python_swidget-1.4.15 → python_swidget-1.4.16}/swidget/__init__.py

@@ -30,6 +30,7 @@ from swidget.swidgetdevice import (
     SwidgetDevice,
 )
 from swidget.swidgetdimmer import SwidgetDimmer
+from swidget.swidgetfan import SwidgetFan
 from swidget.swidgetoutlet import SwidgetOutlet
 from swidget.swidgetswitch import SwidgetSwitch
 from swidget.swidgettimerswitch import SwidgetTimerSwitch
@@ -50,6 +51,7 @@ __all__ = [
     "SwidgetDevice",
     "SwidgetComponent",
     "SwidgetDimmer",
+    "SwidgetFan",
     "SwidgetOutlet",
     "SwidgetSwitch",
     "SwidgetTimerSwitch",

{python_swidget-1.4.15 → python_swidget-1.4.16}/swidget/cli.py

@@ -11,6 +11,7 @@ import asyncclick as click
 from swidget import (
     SwidgetDevice,
     SwidgetDimmer,
+    SwidgetFan,
     SwidgetOutlet,
     SwidgetSwitch,
     SwidgetTimerSwitch,
@@ -24,6 +25,12 @@ TYPE_TO_CLASS = {
     "switch": SwidgetSwitch,
     "outlet": SwidgetOutlet,
     "pana_switch": SwidgetTimerSwitch,
+    "pesna_fv05": SwidgetFan,
+    "pesna_fv15": SwidgetFan,
+    "pesna_fv20": SwidgetFan,
+    "pesna_IB150": SwidgetFan,
+    "pesna_IB160": SwidgetFan,
+    "pesna_fv05_G5": SwidgetFan,
 }
 
 

{python_swidget-1.4.15 → python_swidget-1.4.16}/swidget/discovery.py

@@ -12,6 +12,7 @@ from swidget.swidgetdevice import DeviceType, SwidgetDevice
 
 from .exceptions import SwidgetException
 from .swidgetdimmer import SwidgetDimmer
+from .swidgetfan import SwidgetFan
 from .swidgetoutlet import SwidgetOutlet
 from .swidgetswitch import SwidgetSwitch
 from .swidgettimerswitch import SwidgetTimerSwitch
@@ -194,6 +195,21 @@ async def discover_single(
     return dev
 
 
+_PESNA_DEVICE_TYPES = frozenset(
+    {
+        DeviceType.PesnaFV05,
+        DeviceType.PesnaFV15,
+        DeviceType.PesnaFV20,
+        DeviceType.PesnaIB150,
+        DeviceType.PesnaIB160,
+        DeviceType.PesnaFV05G5,
+        DeviceType.PesnaFV05WrongSlot,
+        DeviceType.PesnaUnrecognized,
+        DeviceType.PesnaError,
+    }
+)
+
+
 def _get_device_class(device_type: DeviceType) -> Type[SwidgetDevice]:
     """Find SmartDevice subclass for device described by passed data."""
     if device_type in (DeviceType.Outlet, DeviceType.Outlet20A):
@@ -206,4 +222,9 @@ def _get_device_class(device_type: DeviceType) -> Type[SwidgetDevice]:
         return SwidgetTimerSwitch
     elif device_type == DeviceType.RelaySwitch:
         return SwidgetSwitch
+    elif device_type in _PESNA_DEVICE_TYPES:
+        # All Pesna* hosts share the same request surface. Per-variant
+        # differences (max CFM, mode set, available modules) are
+        # surfaced by the device itself in the summary/datapoint.
+        return SwidgetFan
     raise SwidgetException("Unknown device type: %s" % device_type)

{python_swidget-1.4.15 → python_swidget-1.4.16}/swidget/swidgetdevice.py

@@ -995,17 +995,26 @@ class SwidgetAssembly:
     def __init__(self, summary: dict):
         self.type = summary["type"]
         self.components = {
-            c["id"]: SwidgetComponent(c["functions"]) for c in summary["components"]
+            c["id"]: SwidgetComponent(c) for c in summary["components"]
         }
         self.id = summary.get("id")
         self.error = summary.get("error")
 
 
 class SwidgetComponent:
-    """Component-level representation of a Swidget Assembly."""
+    """Component-level representation of a Swidget Assembly.
 
-    def __init__(self, functions):
-        self.functions = {f: None for f in functions}
+    Carries the function-state map plus the optional summary-level
+    fields fan hosts emit alongside ``functions`` (``maxCFM``, ``code``,
+    ``modules``). Non-fan components don't populate them and they stay
+    at their defaults.
+    """
+
+    def __init__(self, component):
+        self.functions = {f: None for f in component.get("functions", [])}
+        self.max_cfm = component.get("maxCFM")
+        self.model_code = component.get("code")
+        self.modules = list(component.get("modules", []))
 
 
 class DeviceConfiguration:

python_swidget-1.4.16/swidget/swidgetfan.py

@@ -0,0 +1,276 @@
+"""Module for SwidgetFan.
+
+Covers the Pesna* host family (Panasonic FV05/FV15/FV20/IB150/IB160 and
+G5/error/unrecognised variants). All variants share the same request
+surface; per-model differences (max CFM, available modes, module
+slots) are reported by the device itself in the summary/datapoint.
+
+Function tags (``exhaust``, ``supply``, ``mode``, ``speed``, ``boost``,
+``timer``, ``light``, ``dutyCycle``, ``filter``, ``raw``) and their
+request/response shapes are documented in
+``swidget-sdk/docs/request_handling.md`` (§"Fan-only host functions")
+and ``swidget-sdk/docs/datapoint_description.md`` (§"Fan-only
+functions"). This class is a thin wrapper around those — it does not
+re-validate the device's capability set; callers should consult
+``component.functions`` (populated from the summary) before invoking a
+function the host doesn't expose.
+"""
+import logging
+from typing import Any, Dict, List, Optional
+
+from swidget.exceptions import SwidgetException
+from swidget.swidgetdevice import DeviceType, SwidgetDevice
+
+_LOGGER = logging.getLogger(__name__)
+
+
+_FAN_FUNCTION_TAGS = frozenset(
+    {
+        "exhaust",
+        "supply",
+        "mode",
+        "speed",
+        "boost",
+        "timer",
+        "light",
+        "dutyCycle",
+        "filter",
+        "indoors",
+        "outdoors",
+        "balancing",
+        "modules",
+        "error",
+        "status",
+        "raw",
+    }
+)
+
+
+class SwidgetFan(SwidgetDevice):
+    """Representation of a Swidget Fan-controller host (Pesna* family)."""
+
+    def __init__(
+        self,
+        host,
+        token_name: str,
+        secret_key: str,
+        use_https: bool,
+        use_websockets: bool,
+    ) -> None:
+        super().__init__(
+            host=host,
+            token_name=token_name,
+            secret_key=secret_key,
+            use_https=use_https,
+            use_websockets=use_websockets,
+        )
+        # Provisional. The real type is overwritten when the summary
+        # arrives — at which point we'll know the exact Pesna* variant.
+        self.device_type = DeviceType.PesnaUnrecognized
+
+    # ---- component lookup ------------------------------------------------
+
+    @property
+    def fan_component_id(self) -> str:
+        """Return the host component id that exposes fan functions.
+
+        Pesna hosts typically expose a single component (``"0"``) but
+        the SDK leaves room for multi-component fan controllers, so we
+        scan rather than hardcoding.
+        """
+        host = self.assemblies.get("host")
+        if host is None:
+            raise SwidgetException("Host assembly not loaded yet.")
+        for component_id, component in host.components.items():
+            if any(fn in _FAN_FUNCTION_TAGS for fn in component.functions):
+                return component_id
+        raise SwidgetException("No fan-capable host component found.")
+
+    def _function(self, name: str) -> Any:
+        """Return the current value of a host function, or ``None``."""
+        host = self.assemblies.get("host")
+        if host is None:
+            return None
+        component = host.components.get(self.fan_component_id)
+        if component is None:
+            return None
+        return component.functions.get(name)
+
+    # ---- read-only properties -------------------------------------------
+
+    @property
+    def max_cfm(self) -> Optional[int]:
+        """Maximum CFM the device hardware supports, from the summary."""
+        host = self.assemblies.get("host")
+        if host is None:
+            return None
+        component = host.components.get(self.fan_component_id)
+        return getattr(component, "max_cfm", None) if component else None
+
+    @property
+    def model_code(self) -> Optional[str]:
+        """Hardware-reported fan model code, from the summary."""
+        host = self.assemblies.get("host")
+        if host is None:
+            return None
+        component = host.components.get(self.fan_component_id)
+        return getattr(component, "model_code", None) if component else None
+
+    @property
+    def detected_modules(self) -> List[str]:
+        """Add-on modules detected at summary time (``condensation``, etc.)."""
+        host = self.assemblies.get("host")
+        if host is None:
+            return []
+        component = host.components.get(self.fan_component_id)
+        return list(getattr(component, "modules", []) or []) if component else []
+
+    @property
+    def exhaust_cfm(self) -> Optional[int]:
+        value = self._function("exhaust")
+        return value.get("cfm") if isinstance(value, dict) else None
+
+    @property
+    def supply_cfm(self) -> Optional[int]:
+        value = self._function("supply")
+        return value.get("cfm") if isinstance(value, dict) else None
+
+    @property
+    def allowed_exhaust_cfms(self) -> Optional[List[int]]:
+        """Discrete CFM values the exhaust accepts, or ``None`` if unavailable."""
+        return self._allowed_cfms("exhaust")
+
+    @property
+    def allowed_supply_cfms(self) -> Optional[List[int]]:
+        return self._allowed_cfms("supply")
+
+    def _allowed_cfms(self, tag: str) -> Optional[List[int]]:
+        value = self._function(tag)
+        if not isinstance(value, dict):
+            return None
+        allowed = value.get("allowed")
+        # Per the SDK doc, ``allowed`` may be the literal string
+        # ``"unavailable"`` instead of a list — treat that as "unknown".
+        if isinstance(allowed, list):
+            return list(allowed)
+        return None
+
+    @property
+    def mode(self) -> Optional[str]:
+        value = self._function("mode")
+        return value if isinstance(value, str) else None
+
+    @property
+    def status(self) -> Optional[str]:
+        value = self._function("status")
+        return value if isinstance(value, str) else None
+
+    @property
+    def speed(self) -> Optional[str]:
+        value = self._function("speed")
+        return value if isinstance(value, str) else None
+
+    @property
+    def boost_state(self) -> Optional[Dict[str, Any]]:
+        value = self._function("boost")
+        return dict(value) if isinstance(value, dict) else None
+
+    @property
+    def fan_timer_minutes(self) -> Optional[int]:
+        """Minutes remaining on the fan timer; ``None`` when no timer is active."""
+        value = self._function("timer")
+        if not isinstance(value, dict):
+            return None
+        return value.get("minutes")
+
+    @property
+    def light_on(self) -> Optional[bool]:
+        value = self._function("light")
+        return value.get("on") if isinstance(value, dict) else None
+
+    @property
+    def duty_cycle_minutes(self) -> Optional[int]:
+        value = self._function("dutyCycle")
+        return value.get("minutes") if isinstance(value, dict) else None
+
+    @property
+    def error_code(self) -> Optional[str]:
+        value = self._function("error")
+        return value.get("code") if isinstance(value, dict) else None
+
+    @property
+    def filter_state(self) -> Optional[Dict[str, bool]]:
+        value = self._function("filter")
+        return dict(value) if isinstance(value, dict) else None
+
+    @property
+    def indoor_climate(self) -> Optional[Dict[str, float]]:
+        value = self._function("indoors")
+        return dict(value) if isinstance(value, dict) else None
+
+    @property
+    def outdoor_climate(self) -> Optional[Dict[str, float]]:
+        value = self._function("outdoors")
+        return dict(value) if isinstance(value, dict) else None
+
+    @property
+    def balancing_offset(self) -> Optional[int]:
+        value = self._function("balancing")
+        return value.get("offset") if isinstance(value, dict) else None
+
+    @property
+    def module_states(self) -> Dict[str, str]:
+        """Live ``triggered``/``dormant`` state for each fan add-on module."""
+        value = self._function("modules")
+        return dict(value) if isinstance(value, dict) else {}
+
+    # ---- commands -------------------------------------------------------
+
+    async def set_exhaust_cfm(self, cfm: int) -> None:
+        await self._send_fan_command("exhaust", {"cfm": int(cfm)})
+
+    async def set_supply_cfm(self, cfm: int) -> None:
+        await self._send_fan_command("supply", {"cfm": int(cfm)})
+
+    async def set_mode(self, mode: str) -> None:
+        await self._send_fan_command("mode", {"mode": mode})
+
+    async def set_speed(self, speed: str) -> None:
+        # ``speed`` requests are a bare string per request_handling.md,
+        # but ``send_command`` always wraps the payload, so the device's
+        # request envelope ends up as ``{ "speed": "<str>" }`` either
+        # way (we send the value unwrapped to match).
+        await self._send_fan_command("speed", speed)
+
+    async def set_boost(
+        self, mode: str, minutes: Optional[int] = None
+    ) -> None:
+        """Configure boost. ``mode`` is one of ``"off"``, ``"timer"``, ``"on"``."""
+        payload: Dict[str, Any] = {"mode": mode}
+        if minutes is not None:
+            payload["minutes"] = int(minutes)
+        await self._send_fan_command("boost", payload)
+
+    async def set_fan_timer(self, minutes: int) -> None:
+        await self._send_fan_command("timer", {"minutes": int(minutes)})
+
+    async def set_light(self, on: bool) -> None:
+        await self._send_fan_command("light", {"on": bool(on)})
+
+    async def set_duty_cycle(self, minutes: int) -> None:
+        await self._send_fan_command("dutyCycle", {"minutes": int(minutes)})
+
+    async def clean_filter(self) -> None:
+        await self._send_fan_command("filter", {"clean": True})
+
+    async def send_raw(self, cmd: str) -> None:
+        """Send a raw passthrough command. Diagnostic only."""
+        await self._send_fan_command("raw", {"cmd": cmd})
+
+    async def _send_fan_command(self, function: str, command: Any) -> None:
+        await self.send_command(
+            assembly="host",
+            component=self.fan_component_id,
+            function=function,
+            command=command,
+        )