plexus-python 0.2.0__tar.gz → 0.3.0__tar.gz

{plexus_python-0.2.0 → plexus_python-0.3.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.3.0] - WebSocket transport
+
+Adds a wire-compatible WebSocket transport matching the `plexus-c` SDK. WS is now the default; failed sends transparently fall back to `POST /ingest`.
+
+### Added
+
+- `plexus.WebSocketTransport` — connects to `/ws/device` on the gateway. Exchanges the same `device_auth` / `authenticated` / `telemetry` / `heartbeat` / `typed_command` / `command_result` frames as `plexus-c`.
+- `Plexus(transport="ws" | "http")` — defaults to `"ws"`.
+- `Plexus.on_command(name, handler, description=..., params=...)` — register command handlers; automatic `ack`, handler return becomes `result`, exceptions become `error`.
+- `Plexus.close()` — stops the WebSocket thread.
+- Runtime dep: `websocket-client>=1.7`.
+- Tests: `tests/test_ws.py` (auth handshake, telemetry, command roundtrip, error paths).
+
 ## [0.2.0] - Thin SDK rewrite
 
 Breaking. `plexus-python` is now just the thin client — no agent, adapters, sensors, CLI, or TUI. The package is 886 lines with one runtime dependency (`requests`). Protocol integrations (MAVLink, CAN, MQTT, Modbus, OPC-UA, BLE, I2C sensors) now live as standalone recipes in `examples/`, using the upstream library directly (`pymavlink`, `python-can`, `paho-mqtt`, etc.) plus `px.send()`.

{plexus_python-0.2.0 → plexus_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.2.0
+Version: 0.3.0
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -24,10 +24,12 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.8
 Requires-Dist: requests>=2.28.0
+Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: websockets>=12; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # plexus-python
@@ -119,13 +121,47 @@ px.buffer_size()
 px.flush_buffer()
 ```
 
+## Transport
+
+By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:
+
+- lower-latency streaming of telemetry,
+- live command delivery from the UI / API to the device.
+
+If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
+
+```python
+# default — ws with http fallback
+px = Plexus()
+
+# force http (legacy)
+px = Plexus(transport="http")
+```
+
+### Handling commands
+
+Register a handler before the first `send()` so the command is advertised in the auth frame:
+
+```python
+def reboot(name, params):
+    delay = params.get("delay_s", 0)
+    # ... reboot logic ...
+    return {"ok": True, "delay": delay}
+
+px = Plexus()
+px.on_command("reboot", reboot, description="reboot the device")
+px.send("temperature", 72.5)   # opens the socket, waits for auth
+```
+
+The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL (unused in SDK, for compatibility) | `wss://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
 
 ## Architecture
 

{plexus_python-0.2.0 → plexus_python-0.3.0}/README.md

@@ -87,13 +87,47 @@ px.buffer_size()
 px.flush_buffer()
 ```
 
+## Transport
+
+By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:
+
+- lower-latency streaming of telemetry,
+- live command delivery from the UI / API to the device.
+
+If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
+
+```python
+# default — ws with http fallback
+px = Plexus()
+
+# force http (legacy)
+px = Plexus(transport="http")
+```
+
+### Handling commands
+
+Register a handler before the first `send()` so the command is advertised in the auth frame:
+
+```python
+def reboot(name, params):
+    delay = params.get("delay_s", 0)
+    # ... reboot logic ...
+    return {"ok": True, "delay": delay}
+
+px = Plexus()
+px.on_command("reboot", reboot, description="reboot the device")
+px.send("temperature", 72.5)   # opens the socket, waits for auth
+```
+
+The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL (unused in SDK, for compatibility) | `wss://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
 
 ## Architecture
 

{plexus_python-0.2.0 → plexus_python-0.3.0}/plexus/__init__.py

@@ -8,6 +8,7 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 """
 
 from plexus.client import Plexus
+from plexus.ws import WebSocketTransport
 
-__version__ = "0.2.0"
-__all__ = ["Plexus"]
+__version__ = "0.3.0"
+__all__ = ["Plexus", "WebSocketTransport"]

{plexus_python-0.2.0 → plexus_python-0.3.0}/plexus/client.py

@@ -48,6 +48,7 @@ from plexus.config import (
     get_api_key,
     get_endpoint,
     get_gateway_url,
+    get_gateway_ws_url,
     get_source_id,
 )
 logger = logging.getLogger(__name__)
@@ -95,6 +96,8 @@ class Plexus:
         max_buffer_size: int = 10000,
         persistent_buffer: bool = False,
         buffer_path: Optional[str] = None,
+        transport: str = "ws",
+        ws_url: Optional[str] = None,
     ):
         self.api_key = api_key or get_api_key()
         if not self.api_key:
@@ -114,6 +117,12 @@ class Plexus:
         self._session: Optional[requests.Session] = None
         self._store_frames: bool = False
 
+        if transport not in ("ws", "http"):
+            raise ValueError(f"transport must be 'ws' or 'http', got {transport!r}")
+        self.transport = transport
+        self._ws_url = (ws_url or get_gateway_ws_url())
+        self._ws = None  # lazily constructed in _ensure_ws()
+
         # Pluggable buffer backend for failed sends
         if persistent_buffer:
             self._buffer: BufferBackend = SqliteBuffer(
@@ -254,12 +263,54 @@ class Plexus:
         data_points = [self._make_point(m, v, ts, tags) for m, v in points]
         return self._send_points(data_points)
 
+    def _ensure_ws(self):
+        """Lazily construct and start the WebSocket transport."""
+        if self._ws is not None:
+            return self._ws
+        from plexus.ws import WebSocketTransport
+        from plexus import __version__
+        self._ws = WebSocketTransport(
+            api_key=self.api_key,
+            source_id=self.source_id,
+            ws_url=self._ws_url,
+            agent_version=__version__,
+        )
+        self._ws.start()
+        return self._ws
+
+    def on_command(
+        self,
+        name: str,
+        handler,
+        *,
+        description: Optional[str] = None,
+        params: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Register a command handler (WebSocket transport only).
+
+        The handler is called as `handler(command_name, params_dict)` and may
+        return a dict (→ `result`) or raise (→ `error`). An `ack` is sent
+        automatically before the handler runs.
+
+        Must be called before the first send() so the command is advertised
+        in the auth frame.
+        """
+        if self.transport != "ws":
+            raise PlexusError("on_command requires transport='ws'")
+        ws = self._ensure_ws()
+        ws.register_command(name, handler, description=description, params=params)
+
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
-        """Send data points to the API with retry and buffering.
+        """Send data points to the gateway with retry and buffering.
+
+        Path:
+        - transport='ws': try the WebSocket first; if not yet authenticated or
+          the socket fails, fall through to the HTTP path so points still land.
+        - transport='http': always POST /ingest with retries.
 
-        Retry behavior:
-        - Retries on: Timeout, ConnectionError, HTTP 429 (rate limit), HTTP 5xx
-        - No retry on: HTTP 401/403 (auth errors), HTTP 400/422 (bad request)
+        Retry behavior (HTTP path):
+        - Retries on: Timeout, ConnectionError, HTTP 429, HTTP 5xx
+        - No retry on: HTTP 401/403 (auth), HTTP 400/422 (bad request)
         - After max retries: buffers points locally for next send attempt
         """
         if not self.api_key:
@@ -270,6 +321,18 @@ class Plexus:
         # Include any previously buffered points
         all_points = self._get_buffered_points() + points
 
+        # Preferred path: WebSocket.
+        if self.transport == "ws":
+            ws = self._ensure_ws()
+            # Brief wait on first call so startup races don't dump every point
+            # into the HTTP fallback path.
+            if not ws.is_authenticated:
+                ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+            if ws.send_points(all_points):
+                self._clear_buffer()
+                return True
+            # Socket unavailable → fall through to HTTP.
+
         url = f"{self.gateway_url}/ingest"
         last_error: Optional[Exception] = None
 
@@ -451,6 +514,9 @@ class Plexus:
 
     def close(self):
         """Close the client and release resources."""
+        if self._ws is not None:
+            self._ws.stop()
+            self._ws = None
         if self._session:
             self._session.close()
             self._session = None

plexus_python-0.3.0/plexus/ws.py

@@ -0,0 +1,344 @@
+"""
+WebSocket transport for the Plexus Python SDK.
+
+Wire-compatible with the C SDK (`plexus_ws.c`). Targets the gateway's
+`/ws/device` endpoint and exchanges the same JSON frames:
+
+    client → {"type": "device_auth", "api_key": ..., "source_id": ...,
+              "platform": "python-sdk", "agent_version": ..., "commands": [...]}
+    server → {"type": "authenticated", "source_id": ...}
+    client → {"type": "telemetry", "points": [...]}
+    client → {"type": "heartbeat", "source_id": ..., "agent_version": ...}   # every 30s
+    server → {"type": "typed_command", "id": ..., "command": ..., "params": {...}}
+    client → {"type": "command_result", "id": ..., "command": ..., "event": "ack"}
+    client → {"type": "command_result", "id": ..., "command": ...,
+              "event": "result" | "error", "result": {...} | "error": "..."}
+
+Runs the read loop on a background daemon thread so callers can stay sync.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+try:
+    import websocket  # websocket-client
+except ImportError as e:  # pragma: no cover - import-time failure is obvious
+    raise ImportError(
+        "WebSocket transport requires 'websocket-client'. "
+        "Install with: pip install websocket-client"
+    ) from e
+
+logger = logging.getLogger(__name__)
+
+AUTH_TIMEOUT_S = 10.0
+HEARTBEAT_INTERVAL_S = 30.0
+BACKOFF_BASE_S = 1.0
+BACKOFF_MAX_S = 60.0
+
+CommandHandler = Callable[[str, Dict[str, Any]], Optional[Dict[str, Any]]]
+
+
+@dataclass
+class _RegisteredCommand:
+    name: str
+    handler: CommandHandler
+    description: Optional[str] = None
+    params: List[Dict[str, Any]] = field(default_factory=list)
+
+    def to_manifest(self) -> Dict[str, Any]:
+        m: Dict[str, Any] = {"name": self.name}
+        if self.description:
+            m["description"] = self.description
+        if self.params:
+            m["params"] = self.params
+        return m
+
+
+class WebSocketTransport:
+    """Background WebSocket connection to the Plexus gateway.
+
+    Lifecycle:
+        t = WebSocketTransport(api_key, source_id, ws_url)
+        t.start()
+        t.wait_authenticated(timeout=5)
+        t.send_points([...])
+        t.stop()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        source_id: str,
+        ws_url: str,
+        *,
+        agent_version: str = "0.0.0",
+        platform: str = "python-sdk",
+        auto_reconnect: bool = True,
+    ):
+        if not api_key:
+            raise ValueError("api_key required")
+        if not source_id:
+            raise ValueError("source_id required")
+
+        self.api_key = api_key
+        self.source_id = source_id
+        self.ws_url = _ensure_device_path(ws_url)
+        self.agent_version = agent_version
+        self.platform = platform
+        self.auto_reconnect = auto_reconnect
+
+        self._commands: Dict[str, _RegisteredCommand] = {}
+        self._ws: Optional[websocket.WebSocket] = None
+        self._ws_lock = threading.Lock()
+        self._authenticated = threading.Event()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._backoff_attempt = 0
+
+    # ------------------------------------------------------------------ public
+
+    def register_command(
+        self,
+        name: str,
+        handler: CommandHandler,
+        *,
+        description: Optional[str] = None,
+        params: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Register a command handler. Must be called before start() to be
+        advertised in the auth frame."""
+        self._commands[name] = _RegisteredCommand(
+            name=name, handler=handler, description=description, params=params or []
+        )
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run, name="plexus-ws", daemon=True
+        )
+        self._thread.start()
+
+    def stop(self, timeout: float = 2.0) -> None:
+        self._stop.set()
+        with self._ws_lock:
+            ws = self._ws
+        if ws is not None:
+            try:
+                ws.close()
+            except Exception:  # pragma: no cover
+                pass
+        if self._thread:
+            self._thread.join(timeout=timeout)
+
+    def wait_authenticated(self, timeout: float = AUTH_TIMEOUT_S) -> bool:
+        return self._authenticated.wait(timeout=timeout)
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated.is_set()
+
+    def send_points(self, points: List[Dict[str, Any]]) -> bool:
+        """Send a telemetry frame. Returns False if the socket is not
+        authenticated — caller is expected to fall back to HTTP."""
+        if not points:
+            return True
+        if not self._authenticated.is_set():
+            return False
+        frame = {"type": "telemetry", "points": points}
+        return self._send_frame(frame)
+
+    # ------------------------------------------------------------------ thread
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                self._connect_and_serve()
+            except Exception as e:
+                logger.warning("plexus ws loop error: %s", e)
+            finally:
+                self._authenticated.clear()
+                with self._ws_lock:
+                    self._ws = None
+
+            if not self.auto_reconnect or self._stop.is_set():
+                break
+
+            delay = _backoff_delay(self._backoff_attempt)
+            self._backoff_attempt = min(self._backoff_attempt + 1, 10)
+            logger.info("plexus ws reconnect in %.1fs", delay)
+            if self._stop.wait(timeout=delay):
+                break
+
+    def _connect_and_serve(self) -> None:
+        ws = websocket.create_connection(self.ws_url, timeout=AUTH_TIMEOUT_S)
+        with self._ws_lock:
+            self._ws = ws
+
+        # 1. Send device_auth
+        auth = {
+            "type": "device_auth",
+            "api_key": self.api_key,
+            "source_id": self.source_id,
+            "platform": self.platform,
+            "agent_version": self.agent_version,
+        }
+        if self._commands:
+            auth["commands"] = [c.to_manifest() for c in self._commands.values()]
+        ws.send(json.dumps(auth))
+
+        # 2. Wait for authenticated
+        ws.settimeout(AUTH_TIMEOUT_S)
+        try:
+            raw = ws.recv()
+        except websocket.WebSocketTimeoutException as e:
+            raise TimeoutError("auth timeout") from e
+
+        msg = _safe_json(raw)
+        if msg.get("type") != "authenticated":
+            raise RuntimeError(f"auth failed: {msg}")
+
+        self._authenticated.set()
+        self._backoff_attempt = 0
+        logger.info("plexus ws authenticated as %s", self.source_id)
+
+        # 3. Read loop with heartbeat pump
+        ws.settimeout(1.0)
+        last_heartbeat = time.monotonic()
+        while not self._stop.is_set():
+            now = time.monotonic()
+            if now - last_heartbeat >= HEARTBEAT_INTERVAL_S:
+                self._send_frame({
+                    "type": "heartbeat",
+                    "source_id": self.source_id,
+                    "agent_version": self.agent_version,
+                })
+                last_heartbeat = now
+
+            try:
+                raw = ws.recv()
+            except websocket.WebSocketTimeoutException:
+                continue
+            except (websocket.WebSocketConnectionClosedException, OSError):
+                logger.info("plexus ws closed")
+                return
+
+            if not raw:
+                continue
+            self._dispatch(_safe_json(raw))
+
+    def _dispatch(self, msg: Dict[str, Any]) -> None:
+        mtype = msg.get("type")
+        if mtype == "typed_command":
+            self._handle_command(msg)
+        elif mtype == "error":
+            logger.warning("plexus ws server error: %s", msg.get("detail") or msg)
+        # ignore unknown types — forward-compat
+
+    def _handle_command(self, msg: Dict[str, Any]) -> None:
+        cmd_id = msg.get("id") or ""
+        command = msg.get("command") or ""
+        params = msg.get("params") or {}
+
+        # Ack immediately (matches C SDK: plexus_ws.c:275-280)
+        self._send_frame({
+            "type": "command_result",
+            "id": cmd_id,
+            "command": command,
+            "event": "ack",
+        })
+
+        reg = self._commands.get(command)
+        if reg is None:
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": f"unknown command: {command}",
+            })
+            return
+
+        # Run the handler off the read-loop thread so a slow handler doesn't
+        # block heartbeats or other inbound frames.
+        threading.Thread(
+            target=self._run_handler,
+            args=(reg, cmd_id, command, params),
+            daemon=True,
+        ).start()
+
+    def _run_handler(
+        self,
+        reg: _RegisteredCommand,
+        cmd_id: str,
+        command: str,
+        params: Dict[str, Any],
+    ) -> None:
+        try:
+            result = reg.handler(command, params)
+        except Exception as e:
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": str(e),
+            })
+            return
+        self._send_frame({
+            "type": "command_result",
+            "id": cmd_id,
+            "command": command,
+            "event": "result",
+            "result": result if result is not None else {},
+        })
+
+    def _send_frame(self, frame: Dict[str, Any]) -> bool:
+        with self._ws_lock:
+            ws = self._ws
+        if ws is None:
+            return False
+        try:
+            ws.send(json.dumps(frame))
+            return True
+        except Exception as e:
+            logger.debug("plexus ws send failed: %s", e)
+            return False
+
+
+# --------------------------------------------------------------------- helpers
+
+
+def _ensure_device_path(url: str) -> str:
+    url = url.rstrip("/")
+    if url.endswith("/ws/device"):
+        return url
+    return url + "/ws/device"
+
+
+def _safe_json(raw: Any) -> Dict[str, Any]:
+    if isinstance(raw, (bytes, bytearray)):
+        raw = raw.decode("utf-8", errors="replace")
+    if not isinstance(raw, str):
+        return {}
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return obj if isinstance(obj, dict) else {}
+
+
+def _backoff_delay(attempt: int) -> float:
+    """Exponential backoff with ±25% jitter, capped at BACKOFF_MAX_S.
+    Matches plexus_ws.c:44-52."""
+    base = min(BACKOFF_BASE_S * (2 ** attempt), BACKOFF_MAX_S)
+    jitter = base * 0.25 * (2 * random.random() - 1)
+    return max(0.1, base + jitter)

{plexus_python-0.2.0 → plexus_python-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"
@@ -29,10 +29,11 @@ classifiers = [
 ]
 dependencies = [
     "requests>=2.28.0",
+    "websocket-client>=1.7",
 ]
 
 [project.optional-dependencies]
-dev = ["pytest", "pytest-cov", "ruff"]
+dev = ["pytest", "pytest-cov", "ruff", "websockets>=12"]
 
 [project.urls]
 Homepage = "https://plexus.dev"

plexus_python-0.3.0/tests/test_ws.py

@@ -0,0 +1,255 @@
+"""Wire-compatibility tests for plexus.ws.WebSocketTransport.
+
+Spins up a tiny `websockets`-based server on localhost that impersonates the
+gateway's /ws/device endpoint and asserts the frames the SDK exchanges match
+the C SDK / gateway contract:
+
+    device_auth → authenticated → telemetry → heartbeat → typed_command roundtrip
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import time
+from typing import Any, Dict, List
+
+import pytest
+
+websockets = pytest.importorskip("websockets")
+from websockets.server import serve  # noqa: E402
+
+from plexus.ws import WebSocketTransport  # noqa: E402
+
+
+class _StubGateway:
+    """Minimal gateway stub. Records every frame the client sends."""
+
+    def __init__(self):
+        self.received: List[Dict[str, Any]] = []
+        self.auth_frame: Dict[str, Any] = {}
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._server = None
+        self._thread: threading.Thread | None = None
+        self.port = 0
+        self._ws = None
+        self._ready = threading.Event()
+
+    def start(self) -> None:
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        assert self._ready.wait(timeout=3), "stub server did not start"
+
+    def stop(self) -> None:
+        if self._loop and self._server:
+            self._loop.call_soon_threadsafe(self._server.close)
+        if self._thread:
+            self._thread.join(timeout=2)
+
+    async def _handler(self, ws, path="/ws/device"):
+        self._ws = ws
+        # First frame must be device_auth.
+        raw = await ws.recv()
+        msg = json.loads(raw)
+        self.auth_frame = msg
+        await ws.send(json.dumps({
+            "type": "authenticated",
+            "source_id": msg.get("source_id"),
+        }))
+        try:
+            async for raw in ws:
+                self.received.append(json.loads(raw))
+        except websockets.ConnectionClosed:
+            return
+
+    async def send_command(self, cmd_id: str, name: str, params: Dict[str, Any]):
+        assert self._ws is not None
+        await self._ws.send(json.dumps({
+            "type": "typed_command",
+            "id": cmd_id,
+            "command": name,
+            "params": params,
+        }))
+
+    def send_command_sync(self, cmd_id: str, name: str, params: Dict[str, Any]):
+        assert self._loop is not None
+        fut = asyncio.run_coroutine_threadsafe(
+            self.send_command(cmd_id, name, params), self._loop
+        )
+        fut.result(timeout=2)
+
+    def _run(self) -> None:
+        async def main():
+            self._server = await serve(self._handler, "127.0.0.1", 0)
+            self.port = self._server.sockets[0].getsockname()[1]
+            self._ready.set()
+            await self._server.wait_closed()
+
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+        try:
+            self._loop.run_until_complete(main())
+        finally:
+            self._loop.close()
+
+
+@pytest.fixture
+def gateway():
+    g = _StubGateway()
+    g.start()
+    yield g
+    g.stop()
+
+
+def _url(port: int) -> str:
+    return f"ws://127.0.0.1:{port}"
+
+
+def _wait_until(pred, timeout=3.0):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if pred():
+            return True
+        time.sleep(0.02)
+    return False
+
+
+def test_auth_handshake_and_telemetry(gateway):
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+        agent_version="9.9.9",
+    )
+    t.start()
+    try:
+        assert t.wait_authenticated(timeout=3)
+
+        # Auth frame shape
+        assert gateway.auth_frame["type"] == "device_auth"
+        assert gateway.auth_frame["api_key"] == "plx_test_abc"
+        assert gateway.auth_frame["source_id"] == "drone-001"
+        assert gateway.auth_frame["platform"] == "python-sdk"
+        assert gateway.auth_frame["agent_version"] == "9.9.9"
+        # commands is omitted when none registered
+        assert "commands" not in gateway.auth_frame
+
+        # Telemetry frame shape
+        assert t.send_points([
+            {"metric": "battery_voltage", "value": 12.4, "timestamp": 1700000000000}
+        ])
+        assert _wait_until(
+            lambda: any(m.get("type") == "telemetry" for m in gateway.received)
+        )
+        tele = next(m for m in gateway.received if m["type"] == "telemetry")
+        assert tele["points"][0]["metric"] == "battery_voltage"
+        assert tele["points"][0]["value"] == 12.4
+    finally:
+        t.stop()
+
+
+def test_command_roundtrip(gateway):
+    got: Dict[str, Any] = {}
+
+    def reboot(name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        got["name"] = name
+        got["params"] = params
+        return {"ok": True, "delay": params.get("delay_s")}
+
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+    )
+    t.register_command("reboot", reboot, description="reboot device")
+    t.start()
+    try:
+        assert t.wait_authenticated(timeout=3)
+        # Advertised in auth frame
+        assert gateway.auth_frame["commands"] == [
+            {"name": "reboot", "description": "reboot device"}
+        ]
+
+        gateway.send_command_sync("cmd-42", "reboot", {"delay_s": 10})
+
+        # Expect ack then result
+        assert _wait_until(
+            lambda: sum(
+                1 for m in gateway.received
+                if m.get("type") == "command_result" and m.get("id") == "cmd-42"
+            ) >= 2
+        )
+        results = [
+            m for m in gateway.received
+            if m.get("type") == "command_result" and m.get("id") == "cmd-42"
+        ]
+        assert results[0]["event"] == "ack"
+        assert results[0]["command"] == "reboot"
+        assert results[1]["event"] == "result"
+        assert results[1]["result"] == {"ok": True, "delay": 10}
+
+        assert got == {"name": "reboot", "params": {"delay_s": 10}}
+    finally:
+        t.stop()
+
+
+def test_unknown_command_returns_error(gateway):
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+    )
+    t.start()
+    try:
+        assert t.wait_authenticated(timeout=3)
+        gateway.send_command_sync("cmd-1", "nope", {})
+        assert _wait_until(lambda: any(
+            m.get("type") == "command_result" and m.get("event") == "error"
+            for m in gateway.received
+        ))
+        err = next(
+            m for m in gateway.received
+            if m.get("type") == "command_result" and m.get("event") == "error"
+        )
+        assert "unknown command" in err["error"]
+    finally:
+        t.stop()
+
+
+def test_handler_exception_returns_error(gateway):
+    def bad(name, params):
+        raise RuntimeError("boom")
+
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+    )
+    t.register_command("bad", bad)
+    t.start()
+    try:
+        assert t.wait_authenticated(timeout=3)
+        gateway.send_command_sync("cmd-9", "bad", {})
+        assert _wait_until(lambda: any(
+            m.get("type") == "command_result"
+            and m.get("event") == "error"
+            and m.get("id") == "cmd-9"
+            for m in gateway.received
+        ))
+        err = next(
+            m for m in gateway.received
+            if m.get("type") == "command_result"
+            and m.get("event") == "error"
+            and m.get("id") == "cmd-9"
+        )
+        assert err["error"] == "boom"
+    finally:
+        t.stop()
+
+
+def test_ensure_device_path():
+    from plexus.ws import _ensure_device_path
+    assert _ensure_device_path("wss://foo") == "wss://foo/ws/device"
+    assert _ensure_device_path("wss://foo/") == "wss://foo/ws/device"
+    assert _ensure_device_path("wss://foo/ws/device") == "wss://foo/ws/device"