pyryse 0.1.0__py3-none-any.whl

pyryse/__init__.py

@@ -0,0 +1,25 @@
+"""pyryse — local client for RYSE SmartShade via the RYSE SmartBridge."""
+
+from __future__ import annotations
+
+from .bridge import RyseBridge
+from .exceptions import (
+    RyseConnectionError,
+    RyseError,
+    RyseNotFoundError,
+    RyseResponseError,
+)
+from .models import Device, Gear, GearState
+
+__all__ = [
+    "RyseBridge",
+    "Device",
+    "Gear",
+    "GearState",
+    "RyseError",
+    "RyseConnectionError",
+    "RyseResponseError",
+    "RyseNotFoundError",
+]
+
+__version__ = "0.1.0"

pyryse/bridge.py

@@ -0,0 +1,129 @@
+"""Async client for the RYSE SmartBridge local HTTP API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import aiohttp
+
+from .exceptions import (
+    RyseConnectionError,
+    RyseNotFoundError,
+    RyseResponseError,
+)
+from .models import Device, Gear
+
+DEFAULT_TIMEOUT = 10.0
+
+
+class RyseBridge:
+    """Talks to a RYSE SmartBridge over its local HTTP API (no cloud).
+
+    Parameters
+    ----------
+    host:
+        The bridge's IP address or hostname on the LAN.
+    session:
+        An ``aiohttp.ClientSession`` to use for requests.
+    serial:
+        Optional credential. The bridge only requires it when its local
+        security option is enabled; when set it is sent as the
+        ``Authorization`` header on every request.
+    timeout:
+        Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        session: aiohttp.ClientSession,
+        *,
+        serial: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._host = host
+        self._session = session
+        self._serial = serial
+        self._timeout = timeout
+        self._device_id: str | None = None
+
+    @property
+    def device_id(self) -> str | None:
+        """The bridge's ``dvc_id``, known after the first fetch."""
+        return self._device_id
+
+    async def async_get_device(self) -> Device:
+        """Fetch the bridge and all its gears."""
+        data = await self._request("GET", "/lua/device")
+        if isinstance(data, list):
+            if not data:
+                raise RyseResponseError("Empty /lua/device response")
+            data = data[0]
+        if not isinstance(data, dict) or "dvc_id" not in data:
+            raise RyseResponseError("Unexpected /lua/device response")
+        device = Device.from_dict(data)
+        self._device_id = device.id
+        return device
+
+    async def async_get_gears(self) -> list[Gear]:
+        """Convenience: just the gears from :meth:`async_get_device`."""
+        return (await self.async_get_device()).gears
+
+    async def async_get_position(self, gear_id: str) -> Gear:
+        """Fetch one gear's position via the per-gear endpoint.
+
+        Returns a sparse :class:`Gear` carrying ``position`` and
+        ``position_state`` (the endpoint reports only those two fields).
+        """
+        dvc = await self._ensure_device_id()
+        data = await self._request(
+            "GET", f"/lua/device/{dvc}/gear/{gear_id}/position"
+        )
+        if not isinstance(data, dict) or "position" not in data:
+            raise RyseResponseError("Unexpected position response")
+        return Gear.from_dict({"id": gear_id, **data})
+
+    async def async_set_position(self, gear_id: str, position: int) -> None:
+        """Move a gear to ``position`` (0-100, bridge scale: 0 open, 100 closed).
+
+        Values are clamped into range.
+        """
+        dvc = await self._ensure_device_id()
+        position = max(0, min(100, int(position)))
+        await self._request(
+            "POST",
+            f"/lua/device/{dvc}/gear/{gear_id}/position",
+            json={"position": position},
+        )
+
+    async def _ensure_device_id(self) -> str:
+        if self._device_id is None:
+            await self.async_get_device()
+        assert self._device_id is not None  # noqa: S101
+        return self._device_id
+
+    async def _request(
+        self, method: str, path: str, *, json: dict[str, Any] | None = None
+    ) -> Any:
+        url = f"http://{self._host}{path}"
+        headers = {"Authorization": self._serial} if self._serial else None
+        try:
+            async with asyncio.timeout(self._timeout):
+                resp = await self._session.request(
+                    method, url, json=json, headers=headers
+                )
+                if resp.status in (400, 404):
+                    raise RyseNotFoundError(
+                        f"{method} {path} -> {resp.status}", status=resp.status
+                    )
+                if resp.status >= 400:
+                    raise RyseResponseError(
+                        f"{method} {path} -> {resp.status}", status=resp.status
+                    )
+                # Position POST returns an empty/non-JSON body on success.
+                if method == "POST" and json is not None:
+                    return None
+                return await resp.json(content_type=None)
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise RyseConnectionError(f"{method} {path} failed: {err}") from err

pyryse/exceptions.py

@@ -0,0 +1,23 @@
+"""Exceptions for pyryse."""
+
+from __future__ import annotations
+
+
+class RyseError(Exception):
+    """Base error for all pyryse failures."""
+
+
+class RyseConnectionError(RyseError):
+    """Raised when the bridge cannot be reached (network error or timeout)."""
+
+
+class RyseResponseError(RyseError):
+    """Raised when the bridge returns an unexpected HTTP status or body."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class RyseNotFoundError(RyseResponseError):
+    """Raised when a device or gear id is not known to the bridge."""

pyryse/models.py

@@ -0,0 +1,136 @@
+"""Typed models for RYSE SmartBridge data.
+
+These mirror the bridge's own representation faithfully. In particular,
+``position`` uses the bridge's native scale, which is the *inverse* of Home
+Assistant's cover convention:
+
+* ``0``   = fully open (observed on real hardware, 2026-11)
+* ``100`` = fully closed
+
+Consumers that need Home Assistant semantics (100 = open) should invert.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any
+
+
+class GearState(IntEnum):
+    """Movement state reported by a gear (``position_state``).
+
+    Values observed on firmware 5.3.2:
+
+    * ``IDLE``    (0) — stopped / settled.
+    * ``OPENING`` (1) — moving toward position 0.
+    * ``CLOSING`` (2) — moving toward position 100.
+
+    A gear that is offline may report a stale non-idle value, so check
+    :attr:`Gear.online` before trusting it.
+    """
+
+    IDLE = 0
+    OPENING = 1
+    CLOSING = 2
+
+    @classmethod
+    def _missing_(cls, value: object) -> GearState:
+        # Be forgiving about unknown values from other firmware.
+        return cls.IDLE
+
+
+@dataclass(slots=True)
+class Gear:
+    """A single shade (RYSE calls them "gears")."""
+
+    id: str
+    name: str
+    position: int
+    position_state: GearState
+    online: bool
+    battery: int | None = None  # power_level, 0-100
+    speed: int | None = None
+    gear_type: int | None = None
+    power_type: int | None = None
+    obstacle_detection: int | None = None
+    machine_state: int | None = None
+    fw_version: str | None = None
+    hw_version: str | None = None
+    msp_fw_version: str | None = None
+    serial_number: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def is_moving(self) -> bool:
+        """Whether the gear is currently in motion."""
+        return self.online and self.position_state is not GearState.IDLE
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Gear:
+        return cls(
+            id=str(data["id"]),
+            name=str(data.get("name", data["id"])),
+            position=int(data.get("position", 0)),
+            position_state=GearState(int(data.get("position_state", 0))),
+            online=bool(data.get("online", False)),
+            battery=_opt_int(data.get("power_level")),
+            speed=_opt_int(data.get("speed")),
+            gear_type=_opt_int(data.get("gear_type")),
+            power_type=_opt_int(data.get("power_type")),
+            obstacle_detection=_opt_int(data.get("obstacle_detection")),
+            machine_state=_opt_int(data.get("machine_state")),
+            fw_version=_opt_str(data.get("fw_version")),
+            hw_version=_opt_str(data.get("hw_version")),
+            msp_fw_version=_opt_str(data.get("msp_fw_version")),
+            serial_number=_opt_str(data.get("serial_number")),
+            raw=data,
+        )
+
+
+@dataclass(slots=True)
+class Device:
+    """A RYSE SmartBridge and the gears attached to it."""
+
+    id: str
+    name: str
+    mac: str | None
+    ip: str | None
+    online: bool
+    fw_version: str | None
+    hw_version: str | None
+    app_version: str | None
+    local_security_enable: bool
+    gears: list[Gear] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def gear(self, gear_id: str) -> Gear | None:
+        """Return the gear with ``gear_id``, or ``None``."""
+        return next((g for g in self.gears if g.id == gear_id), None)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Device:
+        return cls(
+            id=str(data["dvc_id"]),
+            name=str(data.get("dvc_name", "RYSE SmartBridge")),
+            mac=_opt_str(data.get("dvc_mac")),
+            ip=_opt_str(data.get("dvc_ip")),
+            online=bool(data.get("dvc_online", True)),
+            fw_version=_opt_str(data.get("dvc_fw_version")),
+            hw_version=_opt_str(data.get("dvc_hw_version")),
+            app_version=_opt_str(data.get("dvc_app_version")),
+            local_security_enable=bool(data.get("local_security_enable", False)),
+            gears=[Gear.from_dict(g) for g in data.get("gears", []) if g.get("id")],
+            raw=data,
+        )
+
+
+def _opt_int(value: Any) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _opt_str(value: Any) -> str | None:
+    return str(value) if value is not None else None

pyryse-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: pyryse
+Version: 0.1.0
+Summary: Local (no-cloud) async client for RYSE SmartShade via the RYSE SmartBridge.
+Project-URL: Homepage, https://github.com/johnnyxmas/pyryse
+Project-URL: Issues, https://github.com/johnnyxmas/pyryse/issues
+Author: Johnny Xmas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blinds,home-assistant,ryse,shades,smartbridge,smartshade
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: test
+Requires-Dist: aioresponses>=0.7.6; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pyryse
+
+Local (no-cloud) async Python client for [RYSE SmartShade](https://helloryse.com)
+motorized shades, driven through a RYSE **SmartBridge** over its LAN HTTP API.
+
+Built to back the Home Assistant integration
+[`ha-ryse-local`](https://github.com/johnnyxmas/ha-ryse-local), but usable on its
+own. Not affiliated with or endorsed by RYSE; "RYSE", "SmartBridge" and
+"SmartShade" are trademarks of their owner.
+
+## Install
+
+```sh
+pip install pyryse
+```
+
+## Usage
+
+```python
+import aiohttp
+from pyryse import RyseBridge
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        bridge = RyseBridge("192.168.0.123", session)
+        device = await bridge.async_get_device()
+        for gear in device.gears:
+            print(gear.name, gear.position, gear.position_state.name, gear.online)
+
+        # Move a shade. Bridge scale: 0 = open, 100 = closed.
+        await bridge.async_set_position(device.gears[0].id, 0)   # open
+```
+
+If your bridge has local security enabled, pass the serial:
+`RyseBridge(host, session, serial="...")`.
+
+## Position convention
+
+The bridge's `position` is the **inverse** of Home Assistant's cover scale:
+
+* `0` = fully open
+* `100` = fully closed
+
+`pyryse` reports the bridge's native values unchanged; invert in your consumer
+if you need HA semantics. See [`docs/PROTOCOL.md`](docs/PROTOCOL.md) for the full
+reverse-engineered API.
+
+## License
+
+MIT

pyryse-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyryse/__init__.py,sha256=T7yYtZ0cRNFwXokgKcNibXlBKhHWuPYTT6o7VKbL0sI,495
+pyryse/bridge.py,sha256=XrE0nkGD5ZFpkzlO1t9jDmMOe3kh3QvANoBoxn5anuw,4534
+pyryse/exceptions.py,sha256=rbet76YaKOkfYpOe-7zHmzj-0hqJxnT5h0skEvVi-Rs,627
+pyryse/models.py,sha256=EF8SwWg8APXesh4k5AxsDfJG3rA-9q7OWCxVOnlZWig,4473
+pyryse-0.1.0.dist-info/METADATA,sha256=KE1_7jUa5HNO6gxBCtXWnyb0X_v7jIicA1cZZbciVsE,2386
+pyryse-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pyryse-0.1.0.dist-info/licenses/LICENSE,sha256=sYmOWeyyMLyYBvLxgDaAQYmGtUSfTytwnrTQkIpn5YE,1068
+pyryse-0.1.0.dist-info/RECORD,,

pyryse-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

pyryse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johnny Xmas
+
+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.