pyremootio 0.1.0__py3-none-any.whl

pyremootio/__init__.py

@@ -0,0 +1,47 @@
+"""Async Python client for the Remootio Websocket API."""
+
+from pyremootio.client import RemootioClient
+from pyremootio.exceptions import (
+    RemootioActionError,
+    RemootioAuthenticationError,
+    RemootioConnectionError,
+    RemootioCryptoError,
+    RemootioError,
+    RemootioTimeoutError,
+)
+from pyremootio.models import (
+    ActionErrorCode,
+    ActionResponse,
+    ActionType,
+    ConnectionVia,
+    Credentials,
+    DeviceErrorMessage,
+    DoorState,
+    EventType,
+    KeyType,
+    RemootioEvent,
+    ServerHello,
+)
+
+__all__ = [
+    "ActionErrorCode",
+    "ActionResponse",
+    "ActionType",
+    "ConnectionVia",
+    "Credentials",
+    "DeviceErrorMessage",
+    "DoorState",
+    "EventType",
+    "KeyType",
+    "RemootioActionError",
+    "RemootioAuthenticationError",
+    "RemootioClient",
+    "RemootioConnectionError",
+    "RemootioCryptoError",
+    "RemootioError",
+    "RemootioEvent",
+    "RemootioTimeoutError",
+    "ServerHello",
+]
+
+__version__ = "0.1.0"

pyremootio/client.py

@@ -0,0 +1,691 @@
+"""Async Remootio Websocket API client."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from inspect import isawaitable
+from typing import Any, Self
+
+import aiohttp
+
+from pyremootio.const import (
+    ACTION_ID_MASK,
+    DEFAULT_ACTION_TIMEOUT,
+    DEFAULT_AUTH_TIMEOUT,
+    DEFAULT_HELLO_TIMEOUT,
+    DEFAULT_PING_INTERVAL,
+    DEFAULT_PORT,
+    INITIAL_RECONNECT_DELAY,
+    MAX_RECONNECT_DELAY,
+    MIN_API_VERSION_DURATION,
+)
+from pyremootio.crypto import compact_json, decrypt_frame, encrypt_payload
+from pyremootio.exceptions import (
+    RemootioActionError,
+    RemootioAuthenticationError,
+    RemootioConnectionError,
+    RemootioCryptoError,
+    RemootioError,
+    RemootioTimeoutError,
+)
+from pyremootio.models import (
+    ActionResponse,
+    ActionType,
+    Challenge,
+    Credentials,
+    DoorState,
+    RemootioEvent,
+    ServerHello,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+EventCallback = Callable[[RemootioEvent], Awaitable[None] | None]
+ConnectionCallback = Callable[[bool], Awaitable[None] | None]
+
+
+class RemootioClient:
+    """Async client for one Remootio device."""
+
+    def __init__(
+        self,
+        host: str,
+        secret_key: str,
+        auth_key: str,
+        session: aiohttp.ClientSession,
+        *,
+        port: int = DEFAULT_PORT,
+        ping_interval: float = DEFAULT_PING_INTERVAL,
+        action_timeout: float = DEFAULT_ACTION_TIMEOUT,
+        auth_timeout: float = DEFAULT_AUTH_TIMEOUT,
+    ) -> None:
+        if ping_interval <= 0:
+            raise ValueError("ping_interval must be positive")
+        self._host = host
+        self._port = port
+        self._credentials = Credentials(secret_key=secret_key, auth_key=auth_key)
+        self._session = session
+        self._ping_interval = ping_interval
+        self._ping_timeout = ping_interval / 2
+        self._action_timeout = action_timeout
+        self._auth_timeout = auth_timeout
+
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self._session_key: str | None = None
+        self._last_action_id: int | None = None
+        self._authenticated = False
+        self._state = DoorState.UNKNOWN
+        self._server_hello: ServerHello | None = None
+
+        self._receive_task: asyncio.Task[None] | None = None
+        self._ping_task: asyncio.Task[None] | None = None
+        self._ping_watchdog: asyncio.Task[None] | None = None
+        self._reconnect_task: asyncio.Task[None] | None = None
+
+        self._reconnect = False
+        self._closed_by_user = False
+        self._shutting_down = False
+        self._action_lock = asyncio.Lock()
+        self._pending: dict[int, asyncio.Future[ActionResponse]] = {}
+        self._authenticated_event = asyncio.Event()
+        self._hello_event = asyncio.Event()
+        self._auth_error: BaseException | None = None
+        self._disconnect_reason: str | None = None
+        self._listeners: list[EventCallback] = []
+        self._connection_listeners: list[ConnectionCallback] = []
+        self._callback_tasks: set[asyncio.Task[None]] = set()
+
+    @classmethod
+    def from_credentials(
+        cls,
+        host: str,
+        credentials: Credentials,
+        session: aiohttp.ClientSession,
+        *,
+        port: int = DEFAULT_PORT,
+        ping_interval: float = DEFAULT_PING_INTERVAL,
+        action_timeout: float = DEFAULT_ACTION_TIMEOUT,
+        auth_timeout: float = DEFAULT_AUTH_TIMEOUT,
+    ) -> RemootioClient:
+        return cls(
+            host,
+            credentials.secret_key,
+            credentials.auth_key,
+            session,
+            port=port,
+            ping_interval=ping_interval,
+            action_timeout=action_timeout,
+            auth_timeout=auth_timeout,
+        )
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    @property
+    def credentials(self) -> Credentials:
+        return self._credentials
+
+    @property
+    def state(self) -> DoorState:
+        return self._state
+
+    @property
+    def serial_number(self) -> str | None:
+        if self._server_hello is None:
+            return None
+        return self._server_hello.serial_number
+
+    @property
+    def api_version(self) -> int | None:
+        if self._server_hello is None:
+            return None
+        return self._server_hello.api_version
+
+    @property
+    def remootio_version(self) -> str | None:
+        if self._server_hello is None:
+            return None
+        return self._server_hello.remootio_version
+
+    @property
+    def connected(self) -> bool:
+        return self._ws is not None and not self._ws.closed
+
+    @property
+    def authenticated(self) -> bool:
+        return self.connected and self._authenticated and self._session_key is not None
+
+    def __repr__(self) -> str:
+        return (
+            f"RemootioClient(host={self._host!r}, port={self._port}, "
+            f"authenticated={self.authenticated})"
+        )
+
+    def listen(self, callback: EventCallback) -> Callable[[], None]:
+        """Subscribe to decrypted device events. Returns an unsubscribe callback."""
+        self._listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            with suppress(ValueError):
+                self._listeners.remove(callback)
+
+        return _unsubscribe
+
+    def listen_connection(self, callback: ConnectionCallback) -> Callable[[], None]:
+        """Subscribe to connection availability changes (True = authenticated)."""
+        self._connection_listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            with suppress(ValueError):
+                self._connection_listeners.remove(callback)
+
+        return _unsubscribe
+
+    async def connect(self, *, reconnect: bool = False) -> None:
+        """Open the websocket, authenticate, and optionally keep reconnecting."""
+        self._reconnect = reconnect
+        self._closed_by_user = False
+        await self._establish()
+        if reconnect and (self._reconnect_task is None or self._reconnect_task.done()):
+            self._reconnect_task = asyncio.create_task(
+                self._reconnect_loop(),
+                name="pyremootio-reconnect",
+            )
+
+    async def disconnect(self) -> None:
+        """Close the session and disable automatic reconnect."""
+        self._closed_by_user = True
+        self._reconnect = False
+        self._set_disconnect_reason("client requested disconnect")
+        if self._reconnect_task is not None:
+            self._reconnect_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._reconnect_task
+            self._reconnect_task = None
+        await self._shutdown()
+
+    async def __aenter__(self) -> Self:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.disconnect()
+
+    async def query(self) -> ActionResponse:
+        return await self._request_action(ActionType.QUERY)
+
+    async def trigger(self, duration_minutes: int | None = None) -> ActionResponse:
+        return await self._request_action(ActionType.TRIGGER, duration_minutes)
+
+    async def trigger_secondary(self, duration_minutes: int | None = None) -> ActionResponse:
+        return await self._request_action(ActionType.TRIGGER_SECONDARY, duration_minutes)
+
+    async def open(self, duration_minutes: int | None = None) -> ActionResponse:
+        return await self._request_action(ActionType.OPEN, duration_minutes)
+
+    async def close(self, duration_minutes: int | None = None) -> ActionResponse:
+        return await self._request_action(ActionType.CLOSE, duration_minutes)
+
+    async def restart(self) -> ActionResponse:
+        return await self._request_action(ActionType.RESTART)
+
+    async def _establish(self) -> None:
+        if self.connected:
+            self._set_disconnect_reason("replaced by new connection")
+            await self._shutdown(notify=False)
+
+        self._reset_session()
+        url = f"ws://{self._host}:{self._port}/"
+        _LOGGER.debug("Connecting to %s", url)
+        try:
+            self._ws = await self._session.ws_connect(
+                url,
+                heartbeat=None,
+                autoping=False,
+                compress=0,
+            )
+        except (aiohttp.ClientError, OSError) as err:
+            raise RemootioConnectionError(f"Could not connect to {url}") from err
+
+        _LOGGER.info("Connected to Remootio websocket (%s:%s)", self._host, self._port)
+
+        self._receive_task = asyncio.create_task(
+            self._receive_loop(),
+            name="pyremootio-receive",
+        )
+        self._ping_task = asyncio.create_task(
+            self._ping_loop(),
+            name="pyremootio-ping",
+        )
+
+        await self._send_basic({"type": "HELLO"})
+        # The device parses only one websocket frame per recv(). Sending AUTH in
+        # the same TCP packet as HELLO would drop AUTH and stall authentication.
+        with suppress(TimeoutError):
+            await asyncio.wait_for(self._hello_event.wait(), timeout=DEFAULT_HELLO_TIMEOUT)
+        await self._send_basic({"type": "AUTH"})
+
+        try:
+            await asyncio.wait_for(self._authenticated_event.wait(), timeout=self._auth_timeout)
+        except TimeoutError as err:
+            self._set_disconnect_reason("authentication timed out")
+            await self._shutdown(notify=False)
+            raise RemootioAuthenticationError("Authentication timed out") from err
+
+        if self._auth_error is not None:
+            error = self._auth_error
+            self._set_disconnect_reason(str(error))
+            await self._shutdown(notify=False)
+            raise error
+
+        if not self._authenticated:
+            self._set_disconnect_reason("authentication failed")
+            await self._shutdown(notify=False)
+            raise RemootioAuthenticationError("Authentication failed")
+
+        _LOGGER.info(
+            "Authenticated with Remootio (%s:%s serial=%s api=%s state=%s)",
+            self._host,
+            self._port,
+            self.serial_number,
+            self.api_version,
+            self._state,
+        )
+        self._notify_connection(True)
+
+    async def _reconnect_loop(self) -> None:
+        delay = INITIAL_RECONNECT_DELAY
+        while self._reconnect and not self._closed_by_user:
+            if self.authenticated:
+                if self._receive_task is None:
+                    return
+                with suppress(asyncio.CancelledError):
+                    await self._receive_task
+            if self._closed_by_user or not self._reconnect:
+                return
+            _LOGGER.warning(
+                "Remootio connection lost (%s:%s): %s; reconnecting in %.1fs",
+                self._host,
+                self._port,
+                self._disconnect_reason or "unknown",
+                delay,
+            )
+            await asyncio.sleep(delay)
+            if self._closed_by_user or not self._reconnect:
+                return
+            try:
+                await self._establish()
+                delay = INITIAL_RECONNECT_DELAY
+            except RemootioError as err:
+                _LOGGER.warning("Reconnect failed (%s:%s): %s", self._host, self._port, err)
+                delay = min(delay * 2, MAX_RECONNECT_DELAY)
+
+    def _reset_session(self) -> None:
+        self._session_key = None
+        self._last_action_id = None
+        self._authenticated = False
+        self._auth_error = None
+        self._shutting_down = False
+        self._authenticated_event = asyncio.Event()
+        self._hello_event = asyncio.Event()
+        self._disconnect_reason = None
+        self._fail_pending(RemootioConnectionError("Connection was reset"))
+
+    async def _shutdown(self, *, notify: bool = True, from_receive: bool = False) -> None:
+        if self._shutting_down:
+            return
+        self._shutting_down = True
+        was_authenticated = self._authenticated
+        had_connection = self._ws is not None or was_authenticated
+        self._authenticated = False
+        self._session_key = None
+        self._fail_pending(RemootioConnectionError("Disconnected from Remootio"))
+
+        tasks = [self._ping_watchdog, self._ping_task, *self._callback_tasks]
+        if not from_receive:
+            tasks.append(self._receive_task)
+        for task in tasks:
+            if task is not None and not task.done():
+                task.cancel()
+        for task in tasks:
+            if task is not None:
+                with suppress(asyncio.CancelledError):
+                    await task
+        self._callback_tasks.clear()
+        self._ping_watchdog = None
+        self._ping_task = None
+        if not from_receive:
+            self._receive_task = None
+
+        if self._ws is not None and not self._ws.closed:
+            with suppress(aiohttp.ClientError):
+                await self._ws.close()
+        self._ws = None
+        reason = self._disconnect_reason or "unknown"
+        if had_connection:
+            _LOGGER.info(
+                "Disconnected from Remootio (%s:%s): %s",
+                self._host,
+                self._port,
+                reason,
+            )
+        self._shutting_down = False
+
+        if notify and was_authenticated:
+            self._notify_connection(False)
+
+    async def _receive_loop(self) -> None:
+        ws = self._ws
+        if ws is None:
+            return
+        try:
+            async for message in ws:
+                self._clear_ping_watchdog()
+                if message.type in {aiohttp.WSMsgType.TEXT, aiohttp.WSMsgType.BINARY}:
+                    raw = message.data
+                    if isinstance(raw, bytes):
+                        raw = raw.decode("utf-8", errors="replace")
+                    await self._handle_message(raw)
+                elif message.type == aiohttp.WSMsgType.ERROR:
+                    exception = ws.exception()
+                    self._set_disconnect_reason(f"websocket error: {exception or 'unknown'}")
+                    break
+                elif message.type in {
+                    aiohttp.WSMsgType.CLOSED,
+                    aiohttp.WSMsgType.CLOSING,
+                }:
+                    close_code = ws.close_code
+                    if close_code is not None:
+                        self._set_disconnect_reason(f"websocket closed (code={close_code})")
+                    else:
+                        self._set_disconnect_reason("websocket closed")
+                    break
+        except asyncio.CancelledError:
+            raise
+        except Exception as err:
+            self._set_disconnect_reason(f"receive loop failed: {err}")
+            _LOGGER.exception("Remootio receive loop failed")
+        finally:
+            if self._disconnect_reason is None:
+                self._set_disconnect_reason("websocket closed")
+            if not self._closed_by_user:
+                await self._shutdown(from_receive=True)
+
+    async def _handle_message(self, raw: str) -> None:
+        try:
+            frame = json.loads(raw)
+        except json.JSONDecodeError:
+            _LOGGER.debug("Ignoring non-JSON frame")
+            return
+        if not isinstance(frame, dict):
+            return
+
+        frame_type = frame.get("type")
+        if frame_type == "SERVER_HELLO":
+            self._server_hello = ServerHello.from_frame(frame)
+            self._hello_event.set()
+            return
+        if frame_type == "PONG":
+            _LOGGER.debug("Received PONG from Remootio (%s:%s)", self._host, self._port)
+            return
+        if frame_type == "ERROR":
+            self._handle_error_frame(str(frame.get("errorMessage", "")))
+            return
+        if frame_type != "ENCRYPTED":
+            _LOGGER.debug("Ignoring frame type %s", frame_type)
+            return
+
+        try:
+            payload = decrypt_frame(
+                frame,
+                auth_key=self._credentials.auth_key,
+                secret_key=self._credentials.secret_key,
+                session_key=self._session_key,
+            )
+        except RemootioCryptoError as err:
+            _LOGGER.debug("Failed to decrypt frame: %s", err)
+            if not self._authenticated:
+                self._fail_authentication(RemootioAuthenticationError("Invalid API keys"))
+            return
+
+        if "challenge" in payload:
+            await self._handle_challenge(payload)
+            return
+        if "response" in payload:
+            self._handle_response(payload)
+            return
+        if "event" in payload:
+            self._handle_event(payload)
+
+    def _handle_error_frame(self, error_message: str) -> None:
+        _LOGGER.debug("Device error: %s", error_message)
+        self._set_disconnect_reason(f"device error: {error_message}")
+        if error_message in {
+            "authentication error",
+            "authentication timeout",
+            "already authenticated",
+        }:
+            self._fail_authentication(RemootioAuthenticationError(error_message))
+
+    async def _handle_challenge(self, payload: dict[str, Any]) -> None:
+        try:
+            challenge = Challenge.from_payload(payload)
+        except ValueError as err:
+            self._fail_authentication(RemootioAuthenticationError(str(err)))
+            return
+        self._session_key = challenge.session_key
+        self._last_action_id = challenge.initial_action_id
+        try:
+            await self._send_action(ActionType.QUERY, wait=False)
+        except RemootioError as err:
+            self._fail_authentication(err)
+
+    def _handle_response(self, payload: dict[str, Any]) -> None:
+        try:
+            response = ActionResponse.from_payload(payload)
+        except ValueError:
+            _LOGGER.debug("Ignoring malformed action response")
+            return
+        self._note_response_id(response.id)
+        self._state = response.state
+        if (
+            not self._authenticated
+            and response.type is ActionType.QUERY
+            and self._session_key is not None
+        ):
+            self._authenticated = True
+            self._authenticated_event.set()
+        pending = self._pending.pop(response.id, None)
+        if pending is not None and not pending.done():
+            pending.set_result(response)
+
+    def _handle_event(self, payload: dict[str, Any]) -> None:
+        try:
+            event = RemootioEvent.from_payload(payload)
+        except ValueError:
+            _LOGGER.debug("Ignoring malformed event")
+            return
+        if event.state is not DoorState.UNKNOWN:
+            self._state = event.state
+        self._notify_event(event)
+
+    def _fail_authentication(self, error: BaseException) -> None:
+        self._auth_error = error
+        self._authenticated_event.set()
+
+    def _note_response_id(self, response_id: int) -> None:
+        if self._last_action_id is None:
+            self._last_action_id = response_id
+            return
+        if response_id > self._last_action_id or (
+            response_id == 0 and self._last_action_id == ACTION_ID_MASK - 1
+        ):
+            self._last_action_id = response_id
+
+    def _allocate_action_id(self) -> int:
+        if self._last_action_id is None:
+            raise RemootioAuthenticationError("Session is not authenticated")
+        self._last_action_id = (self._last_action_id + 1) % ACTION_ID_MASK
+        return self._last_action_id
+
+    async def _request_action(
+        self,
+        action_type: ActionType,
+        duration_minutes: int | None = None,
+    ) -> ActionResponse:
+        if not self.authenticated:
+            raise RemootioAuthenticationError("Session is not authenticated")
+        if duration_minutes is not None:
+            if duration_minutes < 1:
+                raise ValueError("duration_minutes must be >= 1")
+            version = self.api_version or 0
+            if version < MIN_API_VERSION_DURATION:
+                raise ValueError(
+                    "duration_minutes requires Websocket API v3 or later "
+                    f"(device reports v{version or 'unknown'})"
+                )
+        response = await self._send_action(action_type, duration_minutes=duration_minutes)
+        if not response.success:
+            raise RemootioActionError(response)
+        return response
+
+    async def _send_action(
+        self,
+        action_type: ActionType,
+        duration_minutes: int | None = None,
+        *,
+        wait: bool = True,
+    ) -> ActionResponse:
+        async with self._action_lock:
+            action_id = self._allocate_action_id()
+            action: dict[str, Any] = {"type": action_type.value, "id": action_id}
+            if duration_minutes is not None:
+                action["duration"] = duration_minutes
+            loop = asyncio.get_running_loop()
+            future: asyncio.Future[ActionResponse] = loop.create_future()
+            self._pending[action_id] = future
+            await self._send_encrypted({"action": action})
+
+        if not wait:
+            return ActionResponse(
+                type=action_type,
+                id=action_id,
+                success=True,
+                state=self._state,
+                t100ms=0,
+                relay_triggered=False,
+                error_code="",
+            )
+
+        try:
+            return await asyncio.wait_for(future, timeout=self._action_timeout)
+        except TimeoutError as err:
+            self._pending.pop(action_id, None)
+            if not future.done():
+                future.cancel()
+            raise RemootioTimeoutError(
+                f"Timed out waiting for {action_type.value} response"
+            ) from err
+
+    async def _send_encrypted(self, payload: dict[str, Any]) -> None:
+        if self._session_key is None:
+            raise RemootioAuthenticationError("Session is not authenticated")
+        frame = encrypt_payload(
+            payload,
+            auth_key=self._credentials.auth_key,
+            session_key=self._session_key,
+        )
+        await self._send_raw(frame)
+
+    async def _send_basic(self, frame: dict[str, Any]) -> None:
+        await self._send_raw(frame)
+
+    async def _send_raw(self, frame: dict[str, Any]) -> None:
+        if self._ws is None or self._ws.closed:
+            raise RemootioConnectionError("Not connected to Remootio")
+        await self._ws.send_str(compact_json(frame))
+
+    async def _ping_loop(self) -> None:
+        try:
+            while self.connected and not self._closed_by_user:
+                await asyncio.sleep(self._ping_interval)
+                if not self.connected or self._closed_by_user:
+                    return
+                self._arm_ping_watchdog()
+                with suppress(RemootioConnectionError):
+                    await self._send_basic({"type": "PING"})
+                    _LOGGER.debug("Sent PING to Remootio (%s:%s)", self._host, self._port)
+        except asyncio.CancelledError:
+            raise
+
+    def _arm_ping_watchdog(self) -> None:
+        self._clear_ping_watchdog()
+        self._ping_watchdog = asyncio.create_task(
+            self._ping_watchdog_timeout(),
+            name="pyremootio-ping-watchdog",
+        )
+
+    def _clear_ping_watchdog(self) -> None:
+        if self._ping_watchdog is not None:
+            self._ping_watchdog.cancel()
+            self._ping_watchdog = None
+
+    async def _ping_watchdog_timeout(self) -> None:
+        try:
+            await asyncio.sleep(self._ping_timeout)
+        except asyncio.CancelledError:
+            return
+        self._set_disconnect_reason(
+            f"no response to PING within {int(self._ping_timeout * 1000)} ms"
+        )
+        if self._ws is not None and not self._ws.closed:
+            await self._ws.close()
+
+    def _set_disconnect_reason(self, reason: str) -> None:
+        if self._disconnect_reason is None:
+            self._disconnect_reason = reason
+
+    def _fail_pending(self, error: BaseException) -> None:
+        message = str(error)
+        for future in self._pending.values():
+            if not future.done():
+                future.set_exception(RemootioConnectionError(message))
+        self._pending.clear()
+
+    def _notify_event(self, event: RemootioEvent) -> None:
+        for callback in list(self._listeners):
+            self._schedule_callback(callback, event)
+
+    def _notify_connection(self, available: bool) -> None:
+        for callback in list(self._connection_listeners):
+            self._schedule_callback(callback, available)
+
+    def _schedule_callback(
+        self,
+        callback: Callable[..., Awaitable[None] | None],
+        *args: Any,
+    ) -> None:
+        task = asyncio.create_task(self._run_callback(callback, *args))
+        self._callback_tasks.add(task)
+        task.add_done_callback(self._callback_tasks.discard)
+
+    async def _run_callback(
+        self,
+        callback: Callable[..., Awaitable[None] | None],
+        *args: Any,
+    ) -> None:
+        try:
+            result = callback(*args)
+            if isawaitable(result):
+                await result
+        except Exception:
+            _LOGGER.exception("Remootio listener raised")

pyremootio/const.py

@@ -0,0 +1,15 @@
+"""Protocol constants for the Remootio Websocket API."""
+
+DEFAULT_PORT = 8080
+DEFAULT_PING_INTERVAL = 60.0
+DEFAULT_AUTH_TIMEOUT = 15.0
+DEFAULT_ACTION_TIMEOUT = 10.0
+DEFAULT_HELLO_TIMEOUT = 5.0
+INITIAL_RECONNECT_DELAY = 1.0
+MAX_RECONNECT_DELAY = 60.0
+
+# Action IDs are 31-bit counters. Next id = (lastActionId + 1) % ACTION_ID_MASK.
+ACTION_ID_MASK = 0x7FFFFFFF
+
+HEX_KEY_LENGTH = 64
+MIN_API_VERSION_DURATION = 3

pyremootio/crypto.py

@@ -0,0 +1,169 @@
+"""AES-256-CBC + HMAC-SHA256 helpers for Remootio ENCRYPTED frames."""
+
+from __future__ import annotations
+
+import base64
+import hmac
+import json
+from collections.abc import Mapping
+from hashlib import sha256
+from os import urandom
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.padding import PKCS7
+
+from pyremootio.exceptions import RemootioCryptoError
+
+_AES_BLOCK_BITS = 128
+_AES_KEY_LENGTH = 32
+_IV_LENGTH = 16
+_JSON_SEPARATORS = (",", ":")
+
+
+def compact_json(value: Mapping[str, Any] | list[Any] | str | int | bool | None) -> str:
+    """Serialize JSON without whitespace, matching the device MAC input."""
+    return json.dumps(value, separators=_JSON_SEPARATORS)
+
+
+def _b64decode(value: str) -> bytes:
+    try:
+        return base64.b64decode(value, validate=True)
+    except (ValueError, UnicodeError) as err:
+        raise RemootioCryptoError("Invalid base64") from err
+
+
+def _require_aes_key(key: bytes, *, name: str) -> bytes:
+    if len(key) != _AES_KEY_LENGTH:
+        raise RemootioCryptoError(f"{name} must be {_AES_KEY_LENGTH} bytes")
+    return key
+
+
+def _encryption_key(*, secret_key: str | None, session_key: str | None) -> bytes:
+    if session_key is not None:
+        try:
+            key = _b64decode(session_key)
+        except RemootioCryptoError as err:
+            raise RemootioCryptoError("session_key is not valid base64") from err
+        return _require_aes_key(key, name="session_key")
+    if secret_key is None:
+        raise RemootioCryptoError("An encryption key is required")
+    try:
+        key = bytes.fromhex(secret_key)
+    except ValueError as err:
+        raise RemootioCryptoError("secret_key is not valid hex") from err
+    return _require_aes_key(key, name="secret_key")
+
+
+def _auth_key_bytes(auth_key: str) -> bytes:
+    try:
+        return bytes.fromhex(auth_key)
+    except ValueError as err:
+        raise RemootioCryptoError("auth_key is not valid hex") from err
+
+
+def _mac_digest(data: Mapping[str, str], auth_key: str) -> bytes:
+    mac_input = compact_json({"iv": data["iv"], "payload": data["payload"]})
+    return hmac.new(_auth_key_bytes(auth_key), mac_input.encode("latin-1"), sha256).digest()
+
+
+def _mac_for_data(data: Mapping[str, str], auth_key: str) -> str:
+    return base64.b64encode(_mac_digest(data, auth_key)).decode("ascii")
+
+
+def _verify_mac(data: Mapping[str, str], auth_key: str, mac: str) -> None:
+    """Compare HMAC digests in constant time, even if ``mac`` is malformed."""
+    expected = _mac_digest(data, auth_key)
+    received: bytes | None
+    try:
+        received = base64.b64decode(mac, validate=True)
+    except (ValueError, UnicodeError):
+        received = None
+    if received is None or len(received) != len(expected):
+        candidate = bytes(len(expected))
+        valid = False
+    else:
+        candidate = received
+        valid = True
+    if not hmac.compare_digest(expected, candidate) or not valid:
+        raise RemootioCryptoError("ENCRYPTED frame MAC does not match")
+
+
+def decrypt_frame(
+    frame: Mapping[str, Any],
+    *,
+    auth_key: str,
+    secret_key: str | None = None,
+    session_key: str | None = None,
+) -> dict[str, Any]:
+    """Decrypt an ENCRYPTED frame and verify its HMAC.
+
+    Use ``secret_key`` before the session is authenticated (AUTH challenge).
+    Use ``session_key`` for every later ENCRYPTED frame.
+    """
+    if frame.get("type") != "ENCRYPTED":
+        raise RemootioCryptoError("Frame is not an ENCRYPTED frame")
+    data = frame.get("data")
+    mac = frame.get("mac")
+    if not isinstance(data, Mapping) or not isinstance(mac, str):
+        raise RemootioCryptoError("ENCRYPTED frame is missing data or mac")
+    iv_b64 = data.get("iv")
+    payload_b64 = data.get("payload")
+    if not isinstance(iv_b64, str) or not isinstance(payload_b64, str):
+        raise RemootioCryptoError("ENCRYPTED frame data is invalid")
+
+    _verify_mac({"iv": iv_b64, "payload": payload_b64}, auth_key, mac)
+
+    key = _encryption_key(secret_key=secret_key, session_key=session_key)
+    try:
+        iv = _b64decode(iv_b64)
+        if len(iv) != _IV_LENGTH:
+            raise RemootioCryptoError("IV must be 16 bytes")
+        ciphertext = _b64decode(payload_b64)
+        decryptor = Cipher(algorithms.AES(key), modes.CBC(iv)).decryptor()
+        padded = decryptor.update(ciphertext) + decryptor.finalize()
+        unpadder = PKCS7(_AES_BLOCK_BITS).unpadder()
+        plaintext = unpadder.update(padded) + unpadder.finalize()
+        decoded = plaintext.decode("latin-1")
+        parsed = json.loads(decoded)
+    except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as err:
+        raise RemootioCryptoError("Failed to decrypt ENCRYPTED frame") from err
+    if not isinstance(parsed, dict):
+        raise RemootioCryptoError("Decrypted payload is not a JSON object")
+    return parsed
+
+
+def encrypt_payload(
+    payload: Mapping[str, Any],
+    *,
+    auth_key: str,
+    session_key: str | None = None,
+    secret_key: str | None = None,
+    iv: bytes | None = None,
+) -> dict[str, Any]:
+    """Wrap an unencrypted payload in an ENCRYPTED frame.
+
+    The device encrypts the AUTH challenge with ``secret_key``. Every later
+    frame uses ``session_key``.
+    """
+    if iv is None:
+        iv = urandom(_IV_LENGTH)
+    elif len(iv) != _IV_LENGTH:
+        raise RemootioCryptoError("IV must be 16 bytes")
+
+    key = _encryption_key(secret_key=secret_key, session_key=session_key)
+    plaintext = compact_json(payload).encode("latin-1")
+    padder = PKCS7(_AES_BLOCK_BITS).padder()
+    padded = padder.update(plaintext) + padder.finalize()
+    encryptor = Cipher(algorithms.AES(key), modes.CBC(iv)).encryptor()
+    ciphertext = encryptor.update(padded) + encryptor.finalize()
+
+    data = {
+        "iv": base64.b64encode(iv).decode("ascii"),
+        "payload": base64.b64encode(ciphertext).decode("ascii"),
+    }
+    return {
+        "type": "ENCRYPTED",
+        "data": data,
+        "mac": _mac_for_data(data, auth_key),
+    }

pyremootio/exceptions.py

@@ -0,0 +1,37 @@
+"""Exceptions raised by the Remootio client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyremootio.models import ActionResponse
+
+
+class RemootioError(Exception):
+    """Base error for the Remootio client."""
+
+
+class RemootioConnectionError(RemootioError):
+    """The websocket connection could not be established or was lost."""
+
+
+class RemootioAuthenticationError(RemootioError):
+    """The AUTH challenge/response flow failed."""
+
+
+class RemootioCryptoError(RemootioError):
+    """Encryption, decryption, or MAC verification failed."""
+
+
+class RemootioTimeoutError(RemootioError):
+    """A request did not complete within the expected time."""
+
+
+class RemootioActionError(RemootioError):
+    """The device rejected an action or reported success=false."""
+
+    def __init__(self, response: ActionResponse) -> None:
+        self.response = response
+        message = response.error_code or f"{response.type} failed"
+        super().__init__(message)

pyremootio/models.py

@@ -0,0 +1,244 @@
+"""Typed models for Remootio Websocket API frames, actions, and events."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from pyremootio.const import HEX_KEY_LENGTH
+
+_HEX_KEY_RE = re.compile(rf"^[0-9A-Fa-f]{{{HEX_KEY_LENGTH}}}$")
+
+
+class DoorState(StrEnum):
+    """Gate / garage door sensor state reported by the device."""
+
+    OPEN = "open"
+    CLOSED = "closed"
+    NO_SENSOR = "no sensor"
+    UNKNOWN = "unknown"
+
+
+class ActionType(StrEnum):
+    """Encrypted action types the client can send."""
+
+    QUERY = "QUERY"
+    TRIGGER = "TRIGGER"
+    TRIGGER_SECONDARY = "TRIGGER_SECONDARY"
+    OPEN = "OPEN"
+    CLOSE = "CLOSE"
+    RESTART = "RESTART"
+
+
+class EventType(StrEnum):
+    """Device event types (logging mode determines which are emitted)."""
+
+    STATE_CHANGE = "StateChange"
+    RELAY_TRIGGER = "RelayTrigger"
+    SECONDARY_RELAY_TRIGGER = "SecondaryRelayTrigger"
+    OUTPUT_HELD_ACTIVE = "OutputHeldActive"
+    SECONDARY_OUTPUT_HELD_ACTIVE = "SecondaryOutputHeldActive"
+    CONNECTED = "Connected"
+    LEFT_OPEN = "LeftOpen"
+    KEY_MANAGEMENT = "KeyManagement"
+    RESTART = "Restart"
+    MANUAL_BUTTON_PUSHED = "ManualButtonPushed"
+    MANUAL_BUTTON_ENABLED = "ManualButtonEnabled"
+    MANUAL_BUTTON_DISABLED = "ManualButtonDisabled"
+    DOORBELL_PUSHED = "DoorbellPushed"
+    DOORBELL_ENABLED = "DoorbellEnabled"
+    DOORBELL_DISABLED = "DoorbellDisabled"
+    SENSOR_ENABLED = "SensorEnabled"
+    SENSOR_FLIPPED = "SensorFlipped"
+    SENSOR_DISABLED = "SensorDisabled"
+    OUTPUT1_ACTIVATED = "Output1Activated"
+    OUTPUT1_DEACTIVATED = "Output1Deactivated"
+    OUTPUT2_ACTIVATED = "Output2Activated"
+    OUTPUT2_DEACTIVATED = "Output2Deactivated"
+
+
+class KeyType(StrEnum):
+    """Key class reported in event data."""
+
+    MASTER_KEY = "master key"
+    UNIQUE_KEY = "unique key"
+    GUEST_KEY = "guest key"
+    API_KEY = "api key"
+    SMART_HOME = "smart home"
+    AUTOMATION = "automation"
+
+
+class ConnectionVia(StrEnum):
+    """How a key reached the device for an event."""
+
+    BLUETOOTH = "bluetooth"
+    WIFI = "wifi"
+    INTERNET = "internet"
+    AUTOOPEN = "autoopen"
+    UNKNOWN = "unknown"
+    NONE = "none"
+
+
+class DeviceErrorMessage(StrEnum):
+    """ERROR frame errorMessage values sent by the device."""
+
+    JSON_ERROR = "json error"
+    INPUT_ERROR = "input error"
+    INTERNAL_ERROR = "internal error"
+    CONNECTION_TIMEOUT = "connection timeout"
+    AUTHENTICATION_TIMEOUT = "authentication timeout"
+    ALREADY_AUTHENTICATED = "already authenticated"
+    AUTHENTICATION_ERROR = "authentication error"
+
+
+class ActionErrorCode(StrEnum):
+    """errorCode values in action responses."""
+
+    NONE = ""
+    RELAY_BUSY = "ERR_RELAY_BUSY"
+    NO_SENSOR = "ERR_NO_SENSOR"
+    INVALID_REQUEST = "ERR_INVALID_REQUEST"
+
+
+def _parse_door_state(value: object) -> DoorState:
+    if isinstance(value, DoorState):
+        return value
+    if isinstance(value, str):
+        try:
+            return DoorState(value)
+        except ValueError:
+            return DoorState.UNKNOWN
+    return DoorState.UNKNOWN
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+    """API Secret Key and API Auth Key from the Remootio app."""
+
+    secret_key: str
+    auth_key: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "secret_key", self.secret_key.strip())
+        object.__setattr__(self, "auth_key", self.auth_key.strip())
+        if not _HEX_KEY_RE.fullmatch(self.secret_key):
+            raise ValueError("secret_key must be a 64-character hex string")
+        if not _HEX_KEY_RE.fullmatch(self.auth_key):
+            raise ValueError("auth_key must be a 64-character hex string")
+
+    def __repr__(self) -> str:
+        return "Credentials(secret_key='***', auth_key='***')"
+
+
+@dataclass(frozen=True, slots=True)
+class ServerHello:
+    """Identity returned by a HELLO / SERVER_HELLO exchange."""
+
+    api_version: int
+    message: str
+    serial_number: str | None = None
+    remootio_version: str | None = None
+
+    @classmethod
+    def from_frame(cls, frame: Mapping[str, Any]) -> ServerHello:
+        api_version = frame.get("apiVersion", 1)
+        try:
+            parsed_version = int(api_version)
+        except (TypeError, ValueError):
+            parsed_version = 1
+        serial = frame.get("serialNumber")
+        version = frame.get("remootioVersion")
+        return cls(
+            api_version=parsed_version,
+            message=str(frame.get("message", "")),
+            serial_number=str(serial) if serial else None,
+            remootio_version=str(version) if version else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Challenge:
+    """AUTH challenge payload: session key plus the starting action counter."""
+
+    session_key: str
+    initial_action_id: int
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> Challenge:
+        challenge = payload.get("challenge")
+        if not isinstance(challenge, Mapping):
+            raise ValueError("AUTH challenge payload is missing challenge")
+        session_key = challenge.get("sessionKey")
+        initial_action_id = challenge.get("initialActionId")
+        if not isinstance(session_key, str) or not isinstance(initial_action_id, int):
+            raise ValueError("AUTH challenge payload is invalid")
+        return cls(session_key=session_key, initial_action_id=initial_action_id)
+
+
+@dataclass(frozen=True, slots=True)
+class ActionResponse:
+    """Decrypted response to an encrypted action."""
+
+    type: ActionType
+    id: int
+    success: bool
+    state: DoorState
+    t100ms: int
+    relay_triggered: bool
+    error_code: str
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> ActionResponse:
+        response = payload.get("response")
+        if not isinstance(response, Mapping):
+            raise ValueError("Action response payload is missing response")
+        raw_type = str(response.get("type", ""))
+        try:
+            action_type = ActionType(raw_type)
+        except ValueError as err:
+            raise ValueError(f"Unknown action response type: {raw_type}") from err
+        return cls(
+            type=action_type,
+            id=int(response.get("id", 0)),
+            success=bool(response.get("success", False)),
+            state=_parse_door_state(response.get("state")),
+            t100ms=int(response.get("t100ms", 0)),
+            relay_triggered=bool(response.get("relayTriggered", False)),
+            error_code=str(response.get("errorCode", "")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RemootioEvent:
+    """Decrypted event pushed by the device."""
+
+    type: str
+    state: DoorState
+    cnt: int
+    t100ms: int
+    data: dict[str, Any] | None = None
+
+    @property
+    def event_type(self) -> EventType | None:
+        """Known EventType, or None if the device sent an unrecognized type."""
+        try:
+            return EventType(self.type)
+        except ValueError:
+            return None
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> RemootioEvent:
+        event = payload.get("event")
+        if not isinstance(event, Mapping):
+            raise ValueError("Event payload is missing event")
+        data = event.get("data")
+        return cls(
+            type=str(event.get("type", "")),
+            state=_parse_door_state(event.get("state")),
+            cnt=int(event.get("cnt", 0)),
+            t100ms=int(event.get("t100ms", 0)),
+            data=dict(data) if isinstance(data, Mapping) else None,
+        )

pyremootio-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: pyremootio
+Version: 0.1.0
+Summary: Async Python client for the Remootio Websocket API
+Project-URL: Homepage, https://github.com/remootio/pyremootio
+Project-URL: Documentation, https://github.com/remootio/remootio-api-documentation
+Project-URL: Source, https://github.com/remootio/pyremootio
+Project-URL: Issues, https://github.com/remootio/pyremootio/issues
+Author-email: Remootio <hello@remootio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,garage,gate,remootio,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyremootio
+
+Async Python client for the [Remootio](https://www.remootio.com) local Websocket API.
+
+Enable the Websocket API in the Remootio app and copy the API Secret Key, API Auth Key, and device IP.
+
+Protocol details: [Remootio Websocket API documentation](https://github.com/remootio/remootio-api-documentation).
+
+## Install
+
+Python 3.12 or newer:
+
+```bash
+pip install pyremootio
+```
+
+From a clone of this repo (includes tests and examples):
+
+```bash
+python3.12 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+Run examples with `.venv/bin/python`.
+
+## Usage
+
+```python
+import asyncio
+import aiohttp
+from pyremootio import RemootioClient
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        client = RemootioClient(
+            "<ip_address>",  # IP address of your Remootio device
+            "<secret_key>",  # API Secret Key from the Remootio app
+            "<auth_key>",  # API Auth Key from the Remootio app
+            session,
+        )
+        await client.connect()
+        try:
+            response = await client.trigger()
+            print("TRIGGER success=%s state=%s" % (response.success, response.state))
+        finally:
+            await client.disconnect()
+
+asyncio.run(main())
+```
+
+`connect()` runs HELLO, AUTH, and the first QUERY action to authenticate the client. After that, `listen()` receives device events.
+
+Logging uses the standard `pyremootio` logger:
+
+| Level | What you see |
+| --- | --- |
+| `DEBUG` | PING / PONG keepalive |
+| `INFO` | connect, authenticate, disconnect (with reason) |
+| `WARNING` | connection lost, reconnect failed |
+| `ERROR` | unexpected receive-loop or listener failures |
+
+```python
+import logging
+logging.getLogger("pyremootio").setLevel(logging.DEBUG)
+```
+
+### Events
+
+```python
+async def on_event(event):
+    print(event.type, event.state)
+
+unsubscribe = client.listen(on_event)
+```
+
+`StateChange` is sent when a sensor is installed. Enable API logging in the app for the full event set.
+
+### Actions
+
+| Method | Device action |
+| --- | --- |
+| `query()` | Current door state |
+| `open(duration_minutes=None)` | Open if closed (sensor required) |
+| `close(duration_minutes=None)` | Close if open (sensor required) |
+| `trigger(duration_minutes=None)` | Pulse the control output |
+| `trigger_secondary(duration_minutes=None)` | Pulse the free relay output |
+| `restart()` | Reboot the device (connection drops) |
+
+`duration_minutes` holds the output active. It is rejected unless `api_version` is 3 or later. Failed actions raise `RemootioActionError`.
+
+## Examples
+
+- [`examples/trigger.py`](examples/trigger.py) — connect, trigger, wait for `StateChange`
+- [`examples/log_events.py`](examples/log_events.py) — log device events to stdout
+
+```bash
+.venv/bin/python examples/trigger.py --host <ip_address> --secret-key <secret_key> --auth-key <auth_key>
+```
+
+## Tests
+
+```bash
+pytest
+```

pyremootio-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyremootio/__init__.py,sha256=Vlq22M3JfKLspxtF4q1T3ZjNV1aEzMdCfv8AoKuYlTw,976
+pyremootio/client.py,sha256=_KBxE1RV7ziQ1AHgZk2YUkjPq97BlfsMF6oYa_5BhlI,25158
+pyremootio/const.py,sha256=WqDZZoXYtjyGHSwK5TZUaFTd5HJ4aqNzWWR_OEjUJWM,410
+pyremootio/crypto.py,sha256=soQPeOkqHBlzfBXnUzSrr9cfscWjJt_OUA2m7tE5kM4,6040
+pyremootio/exceptions.py,sha256=8TvD4VsdkQE-sW2O0Y6gji8vwM9WhXl0WMTz7krkuho,1008
+pyremootio/models.py,sha256=uauElgvm0Y6sZVPqS0szKS9HVK5gwA35wZQjHIjoDYk,7604
+pyremootio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyremootio-0.1.0.dist-info/METADATA,sha256=IHw0H5i_dumEfltoFTKjBUIUMLf0h6JHXe-L9K7v1aU,4093
+pyremootio-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyremootio-0.1.0.dist-info/licenses/LICENSE,sha256=XrOUPtCCGPf3nNI_ZEzQ9XxhrykpzQkugQq7Ll-jMEg,1075
+pyremootio-0.1.0.dist-info/RECORD,,

pyremootio-0.1.0.dist-info/WHEEL

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

pyremootio-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Remootio
+
+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 WITHOUT LIMITATION 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.