pywmswebcontrolpro 0.1.0__py3-none-any.whl

pywmswebcontrolpro/scene.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+from .room import Room
+
+
+class Scene:
+    def __init__(self, control, id: int, names: list):
+        self._control = control
+        self._id = id
+        self._names = names
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return f"<Scene {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 room(self) -> Room | None:
+        for room in self._control.rooms.values():
+            if self._id in room._scene_ids:
+                return room
+        return None
+
+    # --- Public methods ---
+
+    async def __call__(self, **kwargs) -> Any:
+        return await self._control._sceneActions(self._id, **kwargs)
+
+    def diag(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "room": {self.room.id: self.room.name} if self.room else None,
+        }

pywmswebcontrolpro/store.py

@@ -0,0 +1,104 @@
+"""Persistent settings and last known state of one destination."""
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass, fields
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+import aiofiles
+from aiofiles.os import makedirs, path as aio_path, replace
+
+_LOGGER = logging.getLogger(__name__)
+
+STORE_VERSION = 1
+
+
+class TravelDirection(StrEnum):
+    """Direction of a full drive of a cover."""
+
+    OPEN = "open"
+    CLOSE = "close"
+
+
+@dataclass(frozen=True)
+class ActionSettings:
+    """Settings of a drive action that the user can change.
+
+    A travel time of 0 means unknown, the target of a drive is then taken over
+    at once.
+    """
+
+    travel_time_open: float = 0.0
+    travel_time_close: float = 0.0
+
+    def travel_time(self, direction: TravelDirection) -> float:
+        """Return the travel time of a full drive in seconds."""
+        if direction is TravelDirection.OPEN:
+            return self.travel_time_open
+        return self.travel_time_close
+
+    @classmethod
+    def from_dict(cls, data: Any) -> ActionSettings:
+        """Build settings from stored data, invalid values become 0."""
+        if not isinstance(data, dict):
+            return cls()
+        return cls(**{f.name: _valid_seconds(data.get(f.name)) for f in fields(cls)})
+
+
+def _valid_seconds(value: Any) -> float:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return 0.0
+    return float(value) if value >= 0 else 0.0
+
+
+class JsonStore:
+    """JSON file with the persistent data of one action.
+
+    Reads and writes are serialized and a write replaces the file atomically.
+    Without a path nothing is stored.
+    """
+
+    def __init__(self, path: Path | None) -> None:
+        """Create a store for the given file."""
+        self._path = path
+        self._lock = asyncio.Lock()
+
+    @property
+    def path(self) -> Path | None:
+        """Return the file of this store."""
+        return self._path
+
+    async def load(self) -> dict[str, Any]:
+        """Return the stored data, empty if there is none or it is unreadable."""
+        if self._path is None:
+            return {}
+        async with self._lock:
+            return await self._read(self._path)
+
+    @staticmethod
+    async def _read(path: Path) -> dict[str, Any]:
+        if not await aio_path.exists(path):
+            return {}
+        async with aiofiles.open(path) as file:
+            content = await file.read()
+        try:
+            data = json.loads(content)
+        except json.JSONDecodeError:
+            _LOGGER.warning("Ignoring unreadable file %s", path)
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    async def save(self, data: dict[str, Any]) -> None:
+        """Replace the file with the given data."""
+        if self._path is None:
+            return
+        content = json.dumps(data)
+        temp = self._path.with_name(self._path.name + ".tmp")
+        async with self._lock:
+            await makedirs(self._path.parent, exist_ok=True)
+            async with aiofiles.open(temp, mode="w") as file:
+                await file.write(content)
+            await replace(temp, self._path)

pywmswebcontrolpro/travel.py

@@ -0,0 +1,241 @@
+"""Movement model of a WMS cover, free of Home Assistant imports.
+
+The model keeps the displayed position and tilt of one cover. Commands set
+the state, a running drive is interpolated linearly, and a measured value
+from a status poll replaces the calculated one while the cover stands still.
+
+Scale: position and tilt use the Home Assistant scale, 0 is closed and 100
+is open. All times are seconds, "now" is a monotonic clock value.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class PositionSource(StrEnum):
+    """Origin of the displayed position."""
+
+    MEASURED = "measured"
+    CALCULATED = "calculated"
+    RESTORED = "restored"
+
+
+@dataclass(frozen=True)
+class TravelSettings:
+    """Delays and tolerances of the model."""
+
+    settle_after_travel: float = 2.0
+    settle_after_stop: float = 2.0
+    settle_tilt: float = 5.0
+    settle_unknown_travel: float = 120.0
+    position_tolerance: int = 3
+
+
+@dataclass(frozen=True)
+class Measurement:
+    """Result of handing a measured value to the model."""
+
+    applied: bool
+    deviation: bool
+
+
+def clamp_percent(value: float) -> float:
+    """Limit a value to the range 0..100."""
+    return max(0.0, min(100.0, float(value)))
+
+
+def wms_percentage_to_position(percentage: object) -> int | None:
+    """Convert a WMS percentage (0 open, 100 closed) to a position.
+
+    Returns None if the value is missing or outside 0..100.
+    """
+    if isinstance(percentage, bool) or not isinstance(percentage, (int, float)):
+        return None
+    if percentage < 0 or percentage > 100:
+        return None
+    return int(100 - percentage + 0.5)
+
+
+class CoverModel:
+    """Displayed state of one cover."""
+
+    def __init__(self, settings: TravelSettings | None = None) -> None:
+        """Initialize an unknown cover state."""
+        self.settings = settings or TravelSettings()
+        self.position: float | None = None
+        self.tilt: int | None = None
+        self.source: PositionSource | None = None
+        self._start: float | None = None
+        self._target: float | None = None
+        self._started_at: float | None = None
+        self._duration: float | None = None
+        self._pending_tilt: int | None = None
+
+    # --- State ---
+
+    @property
+    def is_travelling(self) -> bool:
+        """Return True while a drive is interpolated."""
+        return self._target is not None
+
+    @property
+    def is_opening(self) -> bool:
+        """Return True while an interpolated drive moves towards open."""
+        return self.is_travelling and self._target > self._start
+
+    @property
+    def is_closing(self) -> bool:
+        """Return True while an interpolated drive moves towards closed."""
+        return self.is_travelling and self._target < self._start
+
+    @property
+    def position_int(self) -> int | None:
+        """Return the displayed position as integer."""
+        if self.position is None:
+            return None
+        return int(self.position + 0.5)
+
+    def _clear_travel(self) -> None:
+        self._start = None
+        self._target = None
+        self._started_at = None
+        self._duration = None
+        self._pending_tilt = None
+
+    # --- Time ---
+
+    def advance(self, now: float) -> bool:
+        """Move the displayed position to the given time.
+
+        Returns True if a drive reached its target with this call.
+        """
+        if not self.is_travelling:
+            return False
+        elapsed = max(0.0, now - self._started_at)
+        if elapsed >= self._duration:
+            self.position = self._target
+            if self._pending_tilt is not None:
+                self.tilt = self._pending_tilt
+            self._clear_travel()
+            return True
+        self.position = self._start + (self._target - self._start) * (
+            elapsed / self._duration
+        )
+        return False
+
+    # --- Commands ---
+
+    def start_move(
+        self,
+        now: float,
+        target: float,
+        time_open: float,
+        time_close: float,
+        tilt: int | None = None,
+    ) -> float:
+        """Handle an accepted drive command.
+
+        Returns the delay in seconds until the settle poll.
+        """
+        self.advance(now)
+        target = clamp_percent(target)
+        start = self.position
+        self._clear_travel()
+        self.source = PositionSource.CALCULATED
+
+        if start is None:
+            self.position = target
+            if tilt is not None:
+                self.tilt = tilt
+            return self.settings.settle_unknown_travel
+
+        distance = abs(target - start)
+        if distance < 0.5:
+            self.position = target
+            if tilt is not None:
+                self.tilt = tilt
+            return self.settings.settle_tilt
+
+        full_time = time_open if target > start else time_close
+        if full_time <= 0:
+            self.position = target
+            if tilt is not None:
+                self.tilt = tilt
+            return self.settings.settle_unknown_travel
+
+        self._start = start
+        self._target = target
+        self._started_at = now
+        self._duration = full_time * distance / 100
+        self._pending_tilt = tilt
+        return self._duration + self.settings.settle_after_travel
+
+    def set_tilt(self, now: float, tilt: int) -> float:
+        """Handle an accepted tilt-only command, it ends a running drive."""
+        self.advance(now)
+        self._clear_travel()
+        self.tilt = int(clamp_percent(tilt) + 0.5)
+        self.source = PositionSource.CALCULATED
+        return self.settings.settle_tilt
+
+    def stop(self, now: float) -> float:
+        """Handle an accepted stop command, the displayed value freezes."""
+        self.advance(now)
+        self._clear_travel()
+        if self.position is not None:
+            self.source = PositionSource.CALCULATED
+        return self.settings.settle_after_stop
+
+    # --- Measurement and restore ---
+
+    def apply_measurement(
+        self, now: float, position: int | None, tilt: int | None
+    ) -> Measurement:
+        """Take over a measured value unless a drive is running."""
+        self.advance(now)
+        if self.is_travelling or position is None:
+            return Measurement(applied=False, deviation=False)
+        old = self.position
+        self.position = clamp_percent(position)
+        if tilt is not None:
+            self.tilt = int(clamp_percent(tilt) + 0.5)
+        self.source = PositionSource.MEASURED
+        deviation = (
+            old is not None
+            and abs(self.position - old) > self.settings.position_tolerance
+        )
+        return Measurement(applied=True, deviation=deviation)
+
+    def restore(
+        self,
+        position: float | None,
+        tilt: int | None,
+        target_position: float | None,
+        target_tilt: int | None,
+    ) -> None:
+        """Take over the state stored before a restart.
+
+        A value that is already known (measured at setup) wins.
+        """
+        if self.position is not None:
+            return
+        if target_position is not None:
+            self.position = clamp_percent(target_position)
+            self.tilt = target_tilt if target_tilt is not None else tilt
+        elif position is not None:
+            self.position = clamp_percent(position)
+            self.tilt = tilt
+        else:
+            return
+        self.source = PositionSource.RESTORED
+
+    def snapshot(self) -> dict[str, int | None]:
+        """Return the state to store for a restart."""
+        return {
+            "position": self.position_int,
+            "tilt": self.tilt,
+            "target_position": (
+                int(self._target + 0.5) if self.is_travelling else None
+            ),
+            "target_tilt": self._pending_tilt if self.is_travelling else None,
+        }

pywmswebcontrolpro/webcontrol.py

@@ -0,0 +1,218 @@
+import asyncio
+import pprint
+import time
+from collections.abc import Mapping
+from datetime import timedelta
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from aiohttp import ClientSession
+
+from .const import (
+    WMS_WebControl_pro_API_actionDescription,
+    WMS_WebControl_pro_API_actionType,
+    WMS_WebControl_pro_API_command_action,
+    WMS_WebControl_pro_API_command_getConfiguration,
+    WMS_WebControl_pro_API_command_getStatus,
+    WMS_WebControl_pro_API_command_ping,
+    WMS_WebControl_pro_API_command_sceneActions,
+    WMS_WebControl_pro_API_protocolVersion,
+    WMS_WebControl_pro_API_responseType,
+    WMS_WebControl_pro_API_sceneActionType,
+    WMS_WebControl_pro_API_source,
+)
+from .destination import Destination
+from .room import Room
+from .scene import Scene
+
+DEFAULT_STALE_WARNING_AFTER = timedelta(hours=24)
+DEFAULT_RETRY_DELAY = 1.0
+DEFAULT_REQUEST_SPACING = 0.5
+
+
+class WebControlPro:
+    def __init__(
+        self,
+        host: str,
+        session: ClientSession,
+        persist: str | None = None,
+        *,
+        stale_warning_after: timedelta = DEFAULT_STALE_WARNING_AFTER,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+        request_spacing: float = DEFAULT_REQUEST_SPACING,
+    ) -> None:
+        """Create a client; stale_warning_after sets how long a destination may
+        stay silent before a warning is logged, retry_delay the pause in
+        seconds between retries after a radio busy answer and request_spacing
+        the minimum pause in seconds between two status requests.
+        """
+        self.stale_warning_after = stale_warning_after
+        self.retry_delay = retry_delay
+        self._common_lock = asyncio.Lock()
+        self._status_lock = asyncio.Lock()
+        self.request_spacing = request_spacing
+        self._status_last = time.monotonic() - self.request_spacing
+        self._host = host
+        self._control = f"http://{host}/commonCommand"
+        self._session = session
+        self._persist = Path(persist) if persist else None
+        self._config = {}
+        self._dests = {}
+        self._rooms = {}
+        self._scenes = {}
+
+    # --- Private methods ---
+
+    async def _commonCommand(self, command: str, **kwargs) -> Any:
+        data = {
+            "protocolVersion": WMS_WebControl_pro_API_protocolVersion,
+            "command": command,
+            "source": WMS_WebControl_pro_API_source,
+        }
+        data.update(kwargs)
+        async with (
+            self._common_lock,
+            self._session.post(url=self._control, json=data, timeout=5) as response,
+        ):
+            return await response.json()
+
+    async def _ping(self) -> Any:
+        return await self._commonCommand(WMS_WebControl_pro_API_command_ping)
+
+    async def _getConfiguration(self) -> Any:
+        return await self._commonCommand(
+            WMS_WebControl_pro_API_command_getConfiguration
+        )
+
+    async def _getStatus(self, destinationId: int) -> Any:
+        async with self._status_lock:
+            elapsed_time = time.monotonic() - self._status_last
+            if elapsed_time < self.request_spacing:
+                await asyncio.sleep(self.request_spacing - elapsed_time)
+            try:
+                return await self._commonCommand(
+                    WMS_WebControl_pro_API_command_getStatus,
+                    destinations=[destinationId],
+                )
+            finally:
+                self._status_last = time.monotonic()
+
+    async def _action(
+        self, actions: list, responseType=WMS_WebControl_pro_API_responseType.Instant
+    ) -> Any:
+        return await self._commonCommand(
+            WMS_WebControl_pro_API_command_action,
+            responseType=responseType,
+            actions=actions,
+        )
+
+    async def _sceneActions(
+        self,
+        sceneId: int,
+        sceneActionType=WMS_WebControl_pro_API_sceneActionType.Execute,
+        responseType=WMS_WebControl_pro_API_responseType.Instant,
+    ) -> Any:
+        return await self._commonCommand(
+            WMS_WebControl_pro_API_command_sceneActions,
+            responseType=responseType,
+            sceneId=sceneId,
+            sceneActionType=sceneActionType,
+        )
+
+    # --- Public methods ---
+
+    async def ping(self) -> bool:
+        ping = await self._ping()
+        return ping["status"] == 0
+
+    async def refresh(self) -> None:
+        config = await self._getConfiguration()
+        self._config = config
+        self._dests = {
+            dest["id"]: Destination(self, **dest) for dest in config["destinations"]
+        }
+        self._rooms = {room["id"]: Room(self, **room) for room in config["rooms"]}
+        self._scenes = {scene["id"]: Scene(self, **scene) for scene in config["scenes"]}
+
+    def dest(self, name: str) -> Destination:
+        for dest in self._dests.values():
+            if dest.name == name:
+                return dest
+        raise KeyError(f"Destination with name '{name}' not found")
+
+    def diag(self) -> dict:
+        return {
+            "host": self._host,
+            "config": self._config,
+            "dests": {k: v.diag() for k, v in self._dests.items()},
+            "rooms": {k: v.diag() for k, v in self._rooms.items()},
+            "scenes": {k: v.diag() for k, v in self._scenes.items()},
+        }
+
+    # --- Properties ---
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def config(self) -> Mapping:
+        return MappingProxyType(self._config)
+
+    @property
+    def dests(self) -> Mapping:
+        return MappingProxyType(self._dests)
+
+    @property
+    def rooms(self) -> Mapping:
+        return MappingProxyType(self._rooms)
+
+    @property
+    def scenes(self) -> Mapping:
+        return MappingProxyType(self._scenes)
+
+
+async def async_main_test():
+    async with ClientSession() as session:
+        control = WebControlPro("webcontrol", session)
+        pprint.pprint(await control.ping())
+        await control.refresh()
+
+        for dest in control.dests.values():
+            print((dest.room, dest, dest.animationType))
+            await dest.refresh()
+            for action in dest.actions.values():
+                print((action, action._attrs, action._params))
+
+        for scene in control.scenes.values():
+            print(scene)
+            if scene.name == "Licht an":
+                response = await scene()
+                print(response)
+
+        action = control.dest("Licht").action(
+            WMS_WebControl_pro_API_actionDescription.LightDimming,
+            WMS_WebControl_pro_API_actionType.Percentage,
+        )
+        print(action)
+        response = await action(
+            percentage=0, responseType=WMS_WebControl_pro_API_responseType.Detailed
+        )
+        print(response)
+
+        action_list = action.prep(percentage=100)
+        action_list += action.prep(percentage=0)
+        print(action_list)
+        response = await action_list(
+            responseType=WMS_WebControl_pro_API_responseType.Detailed
+        )
+        print(response)
+
+        pprint.pprint(control.diag())
+
+
+if __name__ == "__main__":
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    loop.run_until_complete(async_main_test())

pywmswebcontrolpro-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: pywmswebcontrolpro
+Version: 0.1.0
+Summary: Python library for the Warema WMS WebControl pro API
+Author-email: Marc Hoersken <info@marc-hoersken.de>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: warema,webcontrol,wms
+Requires-Python: >=3.14
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.14.1
+Description-Content-Type: text/markdown
+
+# pywmswebcontrolpro
+
+Python library for the Warema WMS WebControl pro API. It is the companion library of the
+Home Assistant integration `ha_wms_webcontrol_pro`.
+
+Reference: https://media.warema.com/dokumente/anleitungen-handbuecher/966664/warema_2064534_alhb_de_v0.pdf
+
+## Origin and license
+
+This project is a fork of [`pywmspro`](https://github.com/mback2k/pywmspro) by
+Marc Hoersken, licensed under the Apache License 2.0. The full history of the original
+is kept in this repository. All files changed since the fork are changed by this
+project's contributors; see the git history for details. The license text is in
+`LICENSE` and applies to this repository unchanged.
+
+## Example usage
+
+See the main section in `pywmswebcontrolpro/webcontrol.py`.
+
+## Status refresh
+
+`Destination.refresh(retries=2)` requests the status of a destination and returns a
+`RefreshOutcome` with the result (`ok`, `busy`, `empty` or `error`) and the values
+of the actions. Only a "radio busy" answer is retried; with `retries=0` exactly one
+request is sent. On any failure the previous values stay unchanged. The outcome is
+truthy only for `ok`.
+
+`WebControlPro(request_spacing=...)` sets the minimum pause between two status requests
+to the hub (default 0.5 seconds).
+
+Failed refreshes are counted per destination (`Destination.stats`, also part of
+`diag()`) instead of being logged. A warning is logged once when a destination has
+failed continuously for `stale_warning_after` (default 24 hours) and once when it
+delivers data again.
+
+## Settings, movement model and stored state
+
+Each action keeps its data in `<persist>/<destination id>/<action id>.json`, the file
+that already holds the `overwrites` (for example the rotation limits). A drive action
+(for example `AwningDrive`, `ValanceDrive` or `RollerShutterBlindDrive`) stores in it:
+
+- `settings`: the travel times for a full drive, open and close, in seconds
+  (`Action.set_travel_time`, 0 means unknown).
+- `state`: the last known position and tilt and the target of a running drive.
+
+The file is written atomically and serialized against concurrent access, unknown keys
+and the `overwrites` of older versions are kept. Without a persist path nothing is
+stored.
+
+`Action.model` is the movement model of the cover driven by this action: `start_move`,
+`stop`, `set_tilt` and `apply_measurement` calculate the displayed position, which is
+replaced by a measured value when the cover stands still. Because the model belongs to
+the drive action, an awning and its valance, which share a destination, move
+independently. After a restart the position is restored from the file and marked as
+`restored` until a measurement arrives. Call `Action.sync()` after commands and
+measurements to store changes; `Destination.refresh` does it as well.
+
+## Development
+
+```bash
+python -m pip install -r requirements_lint.txt -r requirements_test.txt
+ruff check . && ruff format --check .
+python -m pytest
+```
+
+The version is derived from git tags (`hatch-vcs`).