pywmswebcontrolpro 0.1.0__py3-none-any.whl

pywmswebcontrolpro/action.py

@@ -0,0 +1,226 @@
+import math
+from dataclasses import asdict, replace
+from typing import Any
+
+from .const import (
+    WMS_WebControl_pro_API_actionDescription,
+    WMS_WebControl_pro_API_actionType,
+    WMS_WebControl_pro_API_responseType,
+)
+from .store import STORE_VERSION, ActionSettings, JsonStore, TravelDirection
+from .travel import CoverModel, Measurement
+
+_STORED_KEYS = frozenset({"version", "overwrites", "settings", "state"})
+
+
+class ActionList(list):
+    def __init__(self, control) -> None:
+        super().__init__()
+        self._control = control
+
+    async def __call__(
+        self, responseType=WMS_WebControl_pro_API_responseType.Instant
+    ) -> Any:
+        if len(self) == 0:
+            raise ValueError("ActionList is empty")
+        return await self._control._action(
+            actions=self,
+            responseType=responseType,
+        )
+
+
+class Action:
+    def __init__(
+        self, dest, id: int, actionType: int, actionDescription: int, **kwargs
+    ) -> None:
+        self._dest = dest
+        self._id = id
+        self._persist = (dest._persist / f"{id}.json") if dest._persist else None
+        self._store = JsonStore(self._persist)
+        self._actionType = WMS_WebControl_pro_API_actionType(actionType)
+        self._actionDescription = WMS_WebControl_pro_API_actionDescription(
+            actionDescription
+        )
+        self._attrs = kwargs
+        self._params = {}
+        self._overwrites = {}
+        self._needs_load = True
+        self._needs_save = False
+        self._extra: dict[str, Any] = {}
+        self._settings = ActionSettings()
+        self._saved_state: dict[str, Any] | None = None
+        self.model = CoverModel()
+
+    def __str__(self) -> str:
+        return self.actionDescription.name
+
+    def __repr__(self) -> str:
+        return f"<Action {self.id}: {self} ({self.actionType.name})>"
+
+    def __eq__(self, other) -> bool:
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+    # --- Properties ---
+
+    @property
+    def host(self) -> str:
+        return self._dest.host
+
+    @property
+    def id(self) -> int:
+        return self._id
+
+    @property
+    def actionType(self) -> WMS_WebControl_pro_API_actionType:
+        return self._actionType
+
+    @property
+    def actionDescription(self) -> WMS_WebControl_pro_API_actionDescription:
+        return self._actionDescription
+
+    # --- Private methods ---
+
+    def _update_params(self, value: dict) -> None:
+        self._params.update(value)
+
+    async def _load_persists(self) -> None:
+        data = await self._store.load()
+        self._extra = {k: v for k, v in data.items() if k not in _STORED_KEYS}
+        overwrites = data.get("overwrites")
+        if isinstance(overwrites, dict):
+            self._overwrites = overwrites
+        self._settings = ActionSettings.from_dict(data.get("settings"))
+        state = data.get("state")
+        if isinstance(state, dict):
+            self.model.restore(
+                state.get("position"),
+                state.get("tilt"),
+                state.get("target_position"),
+                state.get("target_tilt"),
+            )
+        self._saved_state = self.model.snapshot()
+
+    async def _save_persists(self) -> None:
+        state = self.model.snapshot()
+        await self._store.save(
+            {
+                **self._extra,
+                "version": STORE_VERSION,
+                "overwrites": self._overwrites,
+                "settings": asdict(self._settings),
+                "state": state,
+            }
+        )
+        self._saved_state = state
+        self._needs_save = False
+
+    async def _ensure_loaded(self) -> None:
+        if self._needs_load:
+            self._needs_load = False
+            await self._load_persists()
+
+    # --- Public methods ---
+
+    @property
+    def settings(self) -> ActionSettings:
+        """Return the settings of this action."""
+        return self._settings
+
+    async def set_travel_time(self, direction: TravelDirection, seconds: float) -> None:
+        """Store the travel time of a full drive in seconds, 0 means unknown."""
+        if not (math.isfinite(seconds) and seconds >= 0):
+            raise ValueError(f"Travel time must be a number >= 0: {seconds}")
+        await self._ensure_loaded()
+        self._settings = replace(
+            self._settings, **{f"travel_time_{direction.value}": float(seconds)}
+        )
+        await self._save_persists()
+
+    def start_move(self, now: float, target: float, tilt: int | None = None) -> float:
+        """Handle an accepted drive command with the stored travel times.
+
+        Returns the delay in seconds until the settle poll.
+        """
+        return self.model.start_move(
+            now,
+            target,
+            self._settings.travel_time(TravelDirection.OPEN),
+            self._settings.travel_time(TravelDirection.CLOSE),
+            tilt,
+        )
+
+    def apply_measurement(
+        self, now: float, position: int | None, tilt: int | None
+    ) -> Measurement:
+        """Take over a measured position unless a drive is running."""
+        return self.model.apply_measurement(now, position, tilt)
+
+    async def sync(self) -> None:
+        """Load stored data once and store changes of overwrites, settings and state.
+
+        Call this after commands and measurements. Destination.refresh does it too.
+        """
+        await self._ensure_loaded()
+        if self._needs_save or self.model.snapshot() != self._saved_state:
+            await self._save_persists()
+
+    def __getattr__(self, name: str) -> Any:
+        if name in self._overwrites:
+            return self._overwrites[name]
+        if name.startswith("wms__"):
+            name = name[5:]
+        return self._attrs.get(name)
+
+    def __getitem__(self, name: str) -> Any:
+        if name in self._overwrites:
+            return self._overwrites[name]
+        return self._params.get(name)
+
+    def __setitem__(self, name: str, value: Any) -> None:
+        if name in self._attrs:
+            self._overwrites[name] = value
+            self._needs_save = True
+        elif name in self._params:
+            self._params[name] = value
+
+    def __delitem__(self, name: str) -> None:
+        if name in self._overwrites:
+            del self._overwrites[name]
+            self._needs_save = True
+
+    def prep(self, **kwargs) -> ActionList:
+        actionList = ActionList(self._dest._control)
+        actionList.append(
+            {
+                "destinationId": self._dest.id,
+                "actionId": self.id,
+                "parameters": kwargs,
+            }
+        )
+        return actionList
+
+    async def __call__(
+        self, responseType=WMS_WebControl_pro_API_responseType.Instant, **kwargs
+    ) -> Any:
+        return await self._dest._control._action(
+            actions=self.prep(**kwargs),
+            responseType=responseType,
+        )
+
+    def diag(self) -> dict:
+        return {
+            "id": self.id,
+            "actionType": self.actionType.name,
+            "actionDescription": self.actionDescription.name,
+            "attrs": self._attrs,
+            "params": self._params,
+            "overwrites": self._overwrites,
+            "settings": asdict(self._settings),
+            "model": {
+                **self.model.snapshot(),
+                "source": self.model.source.value if self.model.source else None,
+            },
+        }

pywmswebcontrolpro/const.py

@@ -0,0 +1,81 @@
+from enum import IntEnum
+
+WMS_WebControl_pro_API_protocolVersion = "1.0"
+WMS_WebControl_pro_API_source = 2
+
+WMS_WebControl_pro_API_command_ping = "ping"
+WMS_WebControl_pro_API_command_getConfiguration = "getConfiguration"
+WMS_WebControl_pro_API_command_getStatus = "getStatus"
+WMS_WebControl_pro_API_command_action = "action"
+WMS_WebControl_pro_API_command_sceneActions = "sceneActions"
+
+
+class WMS_WebControl_pro_API_animationType(IntEnum):
+    VenetianBlind = 0
+    Awning = 1
+    RollerShutterBlind = 2
+    SlatRoof = 3
+    Window = 4
+    Switch = 5
+    Dimmer = 6
+    Unknown = 999
+
+
+class WMS_WebControl_pro_API_actionType(IntEnum):
+    Percentage = 0
+    PercentageDelta = 1
+    Rotation = 2
+    RotationDelta = 3
+    Switch = 4
+    Toggle = 5
+    Stop = 6
+    Impulse = 7
+    Identify = 8
+    Enumeration = 9
+    Unknown = 999
+
+
+class WMS_WebControl_pro_API_actionDescription(IntEnum):
+    AwningDrive = 0
+    ValanceDrive = 1
+    SlatDrive = 2
+    SlatRotate = 3
+    RollerShutterBlindDrive = 4
+    WindowDrive = 5
+    LightSwitch = 6
+    LoadSwitch = 7
+    LightDimming = 8
+    LoadDimming = 9
+    LightToggle = 10
+    LastToggle = 11
+    ManualCommand = 12
+    Identify = 13
+    Unknown = 999
+
+
+class WMS_WebControl_pro_API_responseType(IntEnum):
+    Instant = 0
+    Detailed = 1
+
+
+class WMS_WebControl_pro_API_sceneActionType(IntEnum):
+    Relearn = 0
+    Execute = 1
+
+
+class WMS_WebControl_pro_API_drivingCause(IntEnum):
+    _None = 0  # No driving cause
+    Sun = 1
+    DuskDawn = 2
+    Wind = 3
+    Rain = 4
+    Ice = 5
+    Temperature = 6
+    SwitchingTime = 7
+    Scene = 8
+    ControlMode = 9
+    Manual = 10
+    Safety = 11
+    Contact = 12
+    CentralCommand = 13
+    Unknown = 999

pywmswebcontrolpro/destination.py

@@ -0,0 +1,250 @@
+import asyncio
+import logging
+import time
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+import aiohttp
+
+from .action import Action
+from .const import (
+    WMS_WebControl_pro_API_actionDescription,
+    WMS_WebControl_pro_API_actionType,
+    WMS_WebControl_pro_API_animationType,
+    WMS_WebControl_pro_API_drivingCause,
+)
+from .refresh import (
+    ERROR_RADIO_BUSY,
+    RefreshOutcome,
+    RefreshResult,
+    RefreshStats,
+    StaleChange,
+)
+from .room import Room
+
+DEFAULT_REFRESH_RETRIES = 2
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Destination:
+    def __init__(
+        self, control, id: int, names: list, actions: list, animationType: int
+    ) -> None:
+        self._control = control
+        self._id = id
+        self._names = names
+        self._persist = (control._persist / str(id)) if control._persist else None
+        self._actions = {action["id"]: Action(self, **action) for action in actions}
+        self._animationType = WMS_WebControl_pro_API_animationType(animationType)
+        self._drivingCause = WMS_WebControl_pro_API_drivingCause.Unknown
+        self._unknownProducts = {}
+        self._heartbeatError = None
+        self._blocking = None
+        self._status = {}
+        self._stats = RefreshStats()
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return f"<Destination {self.id}: {self}>"
+
+    def __eq__(self, other) -> bool:
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+    # --- Properties ---
+
+    @property
+    def host(self) -> str:
+        return self._control.host
+
+    @property
+    def id(self) -> int:
+        return self._id
+
+    @property
+    def name(self) -> str:
+        return self._names[0]
+
+    @property
+    def actions(self) -> dict:
+        return self._actions
+
+    @property
+    def animationType(self) -> WMS_WebControl_pro_API_animationType:
+        return self._animationType
+
+    @property
+    def drivingCause(self) -> WMS_WebControl_pro_API_drivingCause:
+        return self._drivingCause
+
+    @property
+    def room(self) -> Room | None:
+        for room in self._control.rooms.values():
+            if self._id in room._destination_ids:
+                return room
+        return None
+
+    @property
+    def available(self) -> bool:
+        return not (self._heartbeatError or self._blocking)
+
+    @property
+    def status(self) -> Mapping:
+        return MappingProxyType(self._status)
+
+    @property
+    def stats(self) -> RefreshStats:
+        """Return a snapshot of the refresh counters of this destination."""
+        return self._stats.snapshot()
+
+    # --- Public methods ---
+
+    async def sync(self) -> None:
+        """Load stored data once and store changes of all actions."""
+        for action in self._actions.values():
+            await action.sync()
+
+    async def refresh(
+        self, retries: int = DEFAULT_REFRESH_RETRIES, *, raise_on_error: bool = False
+    ) -> RefreshOutcome:
+        """Request the status once and retry up to retries times if radio busy.
+
+        With retries=0 exactly one request is sent. On any failure the
+        previously known values stay unchanged. The outcome is counted in
+        stats instead of being logged for every failure.
+        """
+        await self.sync()
+
+        outcome = await self._request_status(retries, raise_on_error)
+        self._record(outcome.result)
+        return outcome
+
+    async def _request_status(
+        self, retries: int, raise_on_error: bool
+    ) -> RefreshOutcome:
+        status: dict = {}
+        for attempt in range(retries + 1):
+            try:
+                status = await self._control._getStatus(self._id)
+            except aiohttp.ClientError, TimeoutError:
+                if raise_on_error:
+                    raise
+                return RefreshOutcome(RefreshResult.ERROR)
+            if ERROR_RADIO_BUSY not in ((status or {}).get("errors") or ()):
+                break
+            if attempt < retries:
+                await asyncio.sleep(self._control.retry_delay)
+        else:
+            return RefreshOutcome(RefreshResult.BUSY)
+
+        if not status:
+            return RefreshOutcome(RefreshResult.EMPTY)
+
+        self._status = status
+        values = self._apply_status(status)
+        if values is None:
+            return RefreshOutcome(RefreshResult.EMPTY)
+        return RefreshOutcome(RefreshResult.OK, values)
+
+    def _apply_status(self, status: dict) -> dict[int, dict[str, Any]] | None:
+        values: dict[int, dict[str, Any]] = {}
+        refreshed = False
+        for detail in status.get("details") or ():
+            if detail.get("destinationId") != self._id or "data" not in detail:
+                continue
+
+            refreshed = True
+            data = detail["data"]
+            if "drivingCause" in data:
+                self._drivingCause = WMS_WebControl_pro_API_drivingCause(
+                    data["drivingCause"]
+                )
+            if "heartbeatError" in data:
+                self._heartbeatError = data["heartbeatError"]
+            if "blocking" in data:
+                self._blocking = data["blocking"]
+
+            for product in data.get("productData", []):
+                action_id = product["actionId"]
+                if action_id in self._actions and "value" in product:
+                    self._actions[action_id]._update_params(product["value"])
+                    values[action_id] = dict(product["value"])
+                    continue
+
+                _LOGGER.debug(
+                    "Unknown actionId %s in productData for %s (%s)",
+                    action_id,
+                    self,
+                    self._id,
+                )
+                self._unknownProducts[action_id] = product
+
+        return values if refreshed else None
+
+    def _record(self, result: RefreshResult) -> None:
+        change = self._stats.record(
+            result,
+            now=time.monotonic(),
+            stale_after=self._control.stale_warning_after.total_seconds(),
+        )
+        if change is StaleChange.STALE:
+            _LOGGER.warning(
+                "No status for %s (%s) for %s, last result: %s",
+                self,
+                self._id,
+                self._control.stale_warning_after,
+                result.value,
+            )
+        elif change is StaleChange.RECOVERED:
+            _LOGGER.warning("Status for %s (%s) is available again", self, self._id)
+
+    def hasAction(
+        self,
+        actionDescription: WMS_WebControl_pro_API_actionDescription,
+        actionType: WMS_WebControl_pro_API_actionType | None = None,
+    ) -> bool:
+        for action in self._actions.values():
+            if action.actionDescription == actionDescription and (
+                actionType is None or actionType == action.actionType
+            ):
+                return True
+        return False
+
+    def action(
+        self,
+        actionDescription: WMS_WebControl_pro_API_actionDescription,
+        actionType: WMS_WebControl_pro_API_actionType | None = None,
+    ) -> Action:
+        for action in self._actions.values():
+            if action.actionDescription == actionDescription and (
+                actionType is None or actionType == action.actionType
+            ):
+                return action
+        description = actionDescription.name if actionDescription else "*"
+        type_name = actionType.name if actionType else "*"
+        raise NotImplementedError(
+            f"Failed to find action with description {description} "
+            f"and type {type_name} in {self} ({self._id})"
+        )
+
+    def diag(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "room": {self.room.id: self.room.name} if self.room else None,
+            "actions": {k: v.diag() for k, v in self._actions.items()},
+            "animationType": self.animationType.name,
+            "drivingCause": self.drivingCause.name,
+            "available": self.available,
+            "unknownProducts": self._unknownProducts,
+            "heartbeatError": self._heartbeatError,
+            "blocking": self._blocking,
+            "status": self._status,
+            "stats": self._stats.as_dict(),
+        }

pywmswebcontrolpro/refresh.py

@@ -0,0 +1,95 @@
+"""Result and statistics of status requests to a destination."""
+
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+# Error code of the hub: the radio channel is occupied and nothing was sent.
+ERROR_RADIO_BUSY = 0x50005
+
+
+class RefreshResult(StrEnum):
+    """Outcome of one status refresh of a destination."""
+
+    OK = "ok"
+    BUSY = "busy"
+    EMPTY = "empty"
+    ERROR = "error"
+
+
+class StaleChange(StrEnum):
+    """Change of the silent state of a destination."""
+
+    STALE = "stale"
+    RECOVERED = "recovered"
+
+
+@dataclass(frozen=True)
+class RefreshOutcome:
+    """Result of a refresh and the values the hub delivered for each action.
+
+    The outcome is truthy only if the hub delivered data for the destination.
+    """
+
+    result: RefreshResult
+    values: dict[int, dict[str, Any]] = field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        """Return True if the hub delivered data for the destination."""
+        return self.result is RefreshResult.OK
+
+
+@dataclass
+class RefreshStats:
+    """Counters of the refresh outcomes of one destination."""
+
+    ok: int = 0
+    busy: int = 0
+    empty: int = 0
+    error: int = 0
+    last_ok: datetime | None = None
+    last_result: RefreshResult | None = None
+    failing_since: float | None = field(default=None, repr=False)
+    stale_reported: bool = field(default=False, repr=False)
+
+    def record(
+        self, result: RefreshResult, *, now: float, stale_after: float
+    ) -> StaleChange | None:
+        """Count a result and report when the silent state changes.
+
+        now is a monotonic time in seconds. A destination is stale when its
+        refreshes have failed continuously for stale_after seconds.
+        """
+        setattr(self, result.value, getattr(self, result.value) + 1)
+        self.last_result = result
+
+        if result is RefreshResult.OK:
+            self.last_ok = datetime.now(UTC)
+            was_stale = self.stale_reported
+            self.failing_since = None
+            self.stale_reported = False
+            return StaleChange.RECOVERED if was_stale else None
+
+        if self.failing_since is None:
+            self.failing_since = now
+            return None
+        if not self.stale_reported and now - self.failing_since >= stale_after:
+            self.stale_reported = True
+            return StaleChange.STALE
+        return None
+
+    def snapshot(self) -> RefreshStats:
+        """Return a copy that does not change with later refreshes."""
+        return replace(self)
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return the counters for diagnostics."""
+        return {
+            "ok": self.ok,
+            "busy": self.busy,
+            "empty": self.empty,
+            "error": self.error,
+            "last_ok": self.last_ok.isoformat() if self.last_ok else None,
+            "last_result": self.last_result.value if self.last_result else None,
+        }

pywmswebcontrolpro/room.py

@@ -0,0 +1,55 @@
+class Room:
+    def __init__(self, control, id: int, name: str, destinations: list, scenes: list):
+        self._control = control
+        self._id = id
+        self._name = name
+        self._destination_ids = destinations
+        self._scene_ids = scenes
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return f"<Room {self.id}: {self}>"
+
+    def __eq__(self, other) -> bool:
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+    # --- Properties ---
+
+    @property
+    def host(self) -> str:
+        return self._control.host
+
+    @property
+    def id(self) -> int:
+        return self._id
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def destinations(self) -> dict:
+        return {
+            dest_id: self._control.dests[dest_id] for dest_id in self._destination_ids
+        }
+
+    @property
+    def scenes(self) -> dict:
+        return {
+            scene_id: self._control.scenes[scene_id] for scene_id in self._scene_ids
+        }
+
+    # --- Public methods ---
+
+    def diag(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "destinations": {dest.id: dest.name for dest in self.destinations.values()},
+            "scenes": {scene.id: scene.name for scene in self.scenes.values()},
+        }