pyremootio 0.1.0__tar.gz

pyremootio-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

pyremootio-0.1.0/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.

pyremootio-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,104 @@
+# 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/examples/log_events.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Connect and print every event the device sends (enable API with logging).
+
+Example (from this folder, after installing into .venv):
+
+    <ip_address> is the IP address of the Remootio device.
+    <secret_key> is the secret key of the Remootio device, you can find it in the Remootio app.
+    <auth_key> is the auth key of the Remootio device, you can find it in the Remootio app.
+
+    .venv/bin/python examples/log_events.py --host <ip_address> --secret-key <secret_key> --auth-key <auth_key>
+
+    for example:
+    .venv/bin/python examples/log_events.py --host 10.23.1.106 --secret-key D0A7E9B4E31AB7BCF2219C9A587ACA7DDB572EAB08459D0ACC52F7C83121B19C --auth-key 3C3B25A1227B9FA87E4A4E259B661F98E522531D2250BAE0C3F1FE3B02762183
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+
+import aiohttp
+
+from pyremootio import RemootioClient, RemootioEvent
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", required=True)
+    parser.add_argument("--secret-key", required=True)
+    parser.add_argument("--auth-key", required=True)
+    parser.add_argument("--port", type=int, default=8080)
+    parser.add_argument(
+        "--log-level",
+        default="DEBUG",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="pyremootio log level (default: DEBUG, includes PING/PONG)",
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(message)s",
+    )
+    logging.getLogger("pyremootio").setLevel(getattr(logging, args.log_level))
+
+    async def on_event(event: RemootioEvent) -> None:
+        logging.info("%s state=%s cnt=%s data=%s", event.type, event.state, event.cnt, event.data)
+
+    async with aiohttp.ClientSession() as session:
+        client = RemootioClient(
+            args.host,
+            args.secret_key,
+            args.auth_key,
+            session,
+            port=args.port,
+        )
+        client.listen(on_event)
+        await client.connect(reconnect=True)
+        logging.info(
+            "Listening (serial=%s, api=%s, state=%s)",
+            client.serial_number,
+            client.api_version,
+            client.state,
+        )
+        try:
+            await asyncio.Event().wait()
+        finally:
+            await client.disconnect()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyremootio-0.1.0/examples/trigger.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Connect, trigger the control output, and disconnect after a StateChange.
+
+Example (from this folder, after installing into .venv):
+
+    <ip_address> is the IP address of the Remootio device.
+    <secret_key> is the secret key of the Remootio device, you can find it in the Remootio app.
+    <auth_key> is the auth key of the Remootio device, you can find it in the Remootio app.
+
+    .venv/bin/python examples/trigger.py --host <ip_address> --secret-key <secret_key> --auth-key <auth_key>
+
+for example:
+    .venv/bin/python examples/trigger.py --host 10.23.1.106 --secret-key D0A7E9B4E31AB7BCF2219C9A587ACA7DDB572EAB08459D0ACC52F7C83121B19C --auth-key 3C3B25A1227B9FA87E4A4E259B661F98E522531D2250BAE0C3F1FE3B02762183
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+
+import aiohttp
+
+from pyremootio import DoorState, EventType, RemootioClient, RemootioEvent
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", required=True)
+    parser.add_argument("--secret-key", required=True)
+    parser.add_argument("--auth-key", required=True)
+    parser.add_argument("--port", type=int, default=8080)
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO)
+    done = asyncio.Event()
+
+    async def on_event(event: RemootioEvent) -> None:
+        if event.event_type is EventType.STATE_CHANGE:
+            logging.info("Door state changed to %s", event.state)
+            done.set()
+
+    async with aiohttp.ClientSession() as session:
+        client = RemootioClient(
+            args.host,
+            args.secret_key,
+            args.auth_key,
+            session,
+            port=args.port,
+        )
+        client.listen(on_event)
+        await client.connect()
+        try:
+            logging.info(
+                "Authenticated (serial=%s, api=%s, state=%s)",
+                client.serial_number,
+                client.api_version,
+                client.state,
+            )
+            response = await client.trigger()
+            logging.info("TRIGGER success=%s state=%s", response.success, response.state)
+            if response.state is DoorState.NO_SENSOR:
+                logging.info("No sensor installed; disconnecting without waiting")
+                return
+            await asyncio.wait_for(done.wait(), timeout=30)
+        finally:
+            await client.disconnect()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyremootio-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyremootio"
+dynamic = ["version"]
+description = "Async Python client for the Remootio Websocket API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    { name = "Remootio", email = "hello@remootio.com" },
+]
+keywords = ["remootio", "asyncio", "garage", "gate", "websocket"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+    "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/remootio/pyremootio"
+Documentation = "https://github.com/remootio/remootio-api-documentation"
+Source = "https://github.com/remootio/pyremootio"
+Issues = "https://github.com/remootio/pyremootio/issues"
+
+[tool.hatch.version]
+path = "src/pyremootio/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/examples",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "PERF",
+    "PLC",
+    "PLE",
+    "PLW",
+    "RUF",
+    "SIM",
+    "UP",
+    "W",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pyremootio"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/*.py" = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+mypy_path = "src"
+packages = ["pyremootio"]

pyremootio-0.1.0/src/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"