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

{plexus_python-0.3.0 → plexus_python-0.4.1}/AGENTS.md

@@ -4,11 +4,11 @@ Machine-readable interface for AI assistants and automation scripts.
 
 ## Environment Variables
 
-| Variable                | Description                                  | Default                          |
-| ----------------------- | -------------------------------------------- | -------------------------------- |
-| `PLEXUS_API_KEY`        | API key for authentication (required)        | none                             |
-| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL                      | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                        | `wss://plexus-gateway.fly.dev`   |
+| Variable                | Description                           | Default                          |
+| ----------------------- | ------------------------------------- | -------------------------------- |
+| `PLEXUS_API_KEY`        | API key for authentication (required) | none                             |
+| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://plexus-gateway.fly.dev`   |
 
 ## CLI Commands
 
@@ -48,21 +48,6 @@ px.send_batch([
 px = Plexus(api_key="plx_xxxxx", persistent_buffer=True)
 ```
 
-## Project Structure
-
-```
-plexus/
-├── cli.py          # CLI entry point (click commands)
-├── tui.py          # Live terminal dashboard (Rich)
-├── client.py       # Plexus HTTP client (thin SDK)
-├── connector.py    # WebSocket daemon
-├── config.py       # Config file + env var management
-├── detect.py       # Hardware auto-detection
-├── deps.py         # Dependency helpers
-├── sensors/        # I2C sensor drivers + SensorHub
-└── adapters/       # Protocol adapters: CAN, MAVLink, MQTT, Modbus, OPC-UA, BLE, Serial
-```
-
 ## Key Conventions
 
 - Config lives in `~/.plexus/config.json`

{plexus_python-0.3.0 → plexus_python-0.4.1}/API.md

@@ -152,34 +152,36 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 
 ### Device Authentication
 
-Devices authenticate using an API key:
+Devices authenticate using an API key. The `source_id` in the request is the device's *desired* name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
 
 ```json
 // Device → Server
 {
   "type": "device_auth",
   "api_key": "plx_xxxxx",
-  "source_id": "my-device-001",
-  "platform": "Linux",
-  "sensors": [
-    {
-      "name": "MPU6050",
-      "description": "6-axis IMU",
-      "metrics": ["accel_x", "accel_y", "accel_z", "gyro_x", "gyro_y", "gyro_z"],
-      "sample_rate": 100,
-      "prefix": "",
-      "available": true
-    }
-  ]
+  "source_id": "drone-01",
+  "install_id": "c9f2e0b46f4a4f6a8c3e1d5b0a2e7f91",
+  "platform": "python-sdk",
+  "agent_version": "0.3.1"
 }
 
 // Server → Device
 {
   "type": "authenticated",
-  "source_id": "my-device-001"
+  "source_id": "drone-01"
+}
+
+// Server → Device (collision case)
+{
+  "type": "authenticated",
+  "source_id": "drone-01_2"
 }
 ```
 
+The SDK **adopts** whatever `source_id` the server returns and uses it for all subsequent frames, heartbeats, and reconnects. It also persists the assigned name locally so reconnects go straight to the claimed slot.
+
+`install_id` is a stable per-installation UUID, generated on the device's first run and saved to `~/.plexus/config.json`. It lets the server distinguish a rebooting device from a new device trying to claim an existing name. Legacy SDKs that omit `install_id` continue to work as before (the server passes the declared `source_id` through unchanged).
+
 ### Message Types (Dashboard → Device)
 
 | Type            | Description                          |

plexus_python-0.4.1/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## [0.4.1] - 2026-04-27 - CI fixes for 0.4.0
+
+### Fixed
+
+- `plexus/cli.py` — drop a stray `f` prefix on a non-interpolated string
+  that ruff (`F541`) caught in CI.
+- `tests/test_retry.py::test_concurrent_sends` — move `patch.object` out
+  of the per-thread closure. `mock.patch.object` mutates instance
+  attributes and is not thread-safe; under 20 concurrent threads the
+  state would leak and surface as a spurious `AttributeError` on Python
+  3.8.
+
+## [0.4.0] - 2026-04-27 - Stable device identity + CLI
+
+The gateway is now authoritative for a device's `source_id`. The SDK sends a
+locally-generated `install_id` in the auth frame; the gateway atomically
+claims `(org, source_id)` and, if the desired name is already owned by a
+different install, returns an auto-suffixed name (`drone-01` → `drone-01_2`
+→ `drone-01_3`…) in the `authenticated` frame. The SDK adopts and persists
+the assigned name so subsequent reconnects are stable.
+
+This fixes the silent stream-merging that happened when cloned SD-card
+images shared a hostname or when two operators picked the same name.
+
+### Added
+
+- `plexus init` (alias `plexus login`) — fly.io / vercel-style browser auth
+  flow. Spins up a localhost listener, opens `${PLEXUS_ENDPOINT}/auth/cli`
+  with a state-protected callback, and persists the issued key to
+  `~/.plexus/config.json`. Console script registered in `pyproject.toml`
+  (`plexus = "plexus.cli:main"`); stdlib-only, no new runtime deps.
+- `plexus.config.get_install_id()` — lazy per-installation UUID, persisted
+  to `~/.plexus/config.json`. **Not** written by `setup.sh`: it's minted by
+  the SDK on first run so pre-baked images get distinct IDs per boot.
+- `PLEXUS_INSTALL_ID` env var — override for `get_install_id()` so
+  ephemeral containers (Fly machines, k8s pods, CI runners) can pin a
+  stable identity across restarts when the config filesystem is ephemeral.
+  Without this, every redeploy gets a fresh UUID and the gateway
+  auto-suffixes the source_id.
+- `plexus.config.set_source_id()` — persist the gateway-assigned name after
+  auto-suffix resolution.
+- `WebSocketTransport(install_id=..., on_source_id_assigned=...)` — the
+  transport sends `install_id` in the `device_auth` frame and invokes the
+  callback whenever the gateway returns a different `source_id` than
+  requested.
+
+### Changed
+
+- `WebSocketTransport` now reads the `source_id` back from the
+  `authenticated` frame and updates `self.source_id` in place if the gateway
+  auto-suffixed. The rename is logged at INFO level on first occurrence.
+- `Plexus` wires `install_id` into the transport and persists the assigned
+  `source_id` to config on rename.
+- `scripts/setup.sh` — `--name` is **required**. The hostname fallback is
+  removed (it was the main source of cloned-image collisions). In a TTY the
+  script prompts interactively; in non-TTY it exits with an error. Names are
+  validated against `^[a-z0-9][a-z0-9_-]{1,62}$`. Stale `plexus start` /
+  `plexus reset` hints were dropped.
+
+### Wire-protocol (compatible)
+
+- `device_auth` frame gains an optional `install_id` field. The gateway
+  treats a missing `install_id` as legacy pass-through, so older SDKs and
+  the C SDK continue to work unchanged.
+
+## [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()`.
+
+### Added
+
+- 5 runnable example scripts: `basic.py`, `mavlink.py`, `can.py`, `mqtt.py`, `i2c_bme280.py`
+
+### Removed
+
+- `plexus/adapters/` (MAVLink, CAN, MQTT, Modbus, OPC-UA, BLE, Serial — use the upstream lib directly)
+- `plexus/sensors/` (I2C drivers + auto-detect — use Adafruit CircuitPython or smbus2 directly)
+- `plexus/cameras/` (frame upload — out of scope)
+- `plexus/cli.py`, `plexus/connector.py`, `plexus/streaming.py`, `plexus/detect.py`, `plexus/tui.py`, `plexus/deps.py`
+- `plexus` console script, `python -m plexus`
+- Extras: `[sensors]`, `[system]`, `[tui]`, `[mqtt]`, `[can]`, `[mavlink]`, `[modbus]`, `[opcua]`, `[ble]`, `[serial]`, `[ros]`, `[camera]`, `[picamera]`, `[all]`
+- Runtime deps: `click`, `websockets`
+
+### Changed
+
+- Default ingest endpoint points directly at the Plexus gateway (`https://plexus-gateway.fly.dev/ingest`), not the Next.js app proxy
+- Client raises `ValueError` clearly when no API key is available, instead of invoking a login flow
+
+## [0.1.0] - Initial release
+
+- `Plexus` thin client for HTTP ingest
+- `plexus start` daemon with WebSocket streaming
+- Protocol adapters: MAVLink, CAN, MQTT, Modbus, OPC-UA, Serial, BLE
+- I2C sensor auto-detection and drivers
+- Store-and-forward buffering (SQLite)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.3.0
+Version: 0.4.1
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -54,6 +54,21 @@ px.send("temperature", 72.5)
 
 Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
 
+## Device identity
+
+Every device needs a unique `source_id`. The recommended way to set one on a real host is the bootstrap script, which requires a device name up front:
+
+```bash
+curl -sL https://app.plexus.company/setup | bash -s -- \
+  --key plx_xxx --name drone-01
+```
+
+The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
+
+**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+
+In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
+
 ## Usage
 
 ```python

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

@@ -20,6 +20,21 @@ px.send("temperature", 72.5)
 
 Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
 
+## Device identity
+
+Every device needs a unique `source_id`. The recommended way to set one on a real host is the bootstrap script, which requires a device name up front:
+
+```bash
+curl -sL https://app.plexus.company/setup | bash -s -- \
+  --key plx_xxx --name drone-01
+```
+
+The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
+
+**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+
+In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
+
 ## Usage
 
 ```python

{plexus_python-0.3.0 → plexus_python-0.4.1}/SECURITY.md

@@ -22,7 +22,7 @@ Instead, email **support@plexus.company** with:
 ## Supported Versions
 
 | Version | Supported |
-|---------|-----------|
+| ------- | --------- |
 | 0.9.x   | Yes       |
 | < 0.9   | No        |
 

{plexus_python-0.3.0 → plexus_python-0.4.1}/examples/basic.py

@@ -11,7 +11,7 @@ import time
 
 from plexus import Plexus
 
-px = Plexus(source_id="demo-device")
+px = Plexus(api_key="plx_123...", source_id="demo-device")
 
 while True:
     px.send("temperature", 20 + random.random() * 5)

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

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

plexus_python-0.4.1/plexus/cli.py

@@ -0,0 +1,275 @@
+"""
+Plexus CLI — `plexus init` style auth, plus a few sibling commands.
+
+Designed to feel like fly.io / vercel CLIs:
+    $ pip install plexus
+    $ plexus init
+    Opening browser to https://app.plexus.company/auth/cli...
+    ✓ Saved API key as cli-<host>. You're set up.
+
+Implementation:
+- Spin up a local HTTP listener on a random free port.
+- Open the browser to /auth/cli with the callback URL embedded.
+- Block until the browser POSTs (well — redirects with key) to /callback.
+- Verify the `state` parameter matches what we generated.
+- Persist the key via plexus.config.save_config; the SDK already reads
+  `~/.plexus/config.json` for `PLEXUS_API_KEY`.
+
+Stdlib only — keep dependency footprint minimal.
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.server
+import secrets
+import socket
+import socketserver
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from typing import Optional
+
+from . import config
+
+
+DEFAULT_TIMEOUT_SECONDS = 300
+SUCCESS_HTML = """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Plexus CLI</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        display: flex; align-items: center; justify-content: center;
+        min-height: 100vh; margin: 0; background: Canvas; color: CanvasText;
+      }
+      .card {
+        max-width: 360px; padding: 32px; border: 1px solid #8884;
+        border-radius: 12px; text-align: center;
+      }
+      h1 { margin: 0 0 8px; font-size: 18px; }
+      p { margin: 0; color: #888; font-size: 14px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>You're all set</h1>
+      <p>Return to your terminal &mdash; the CLI has your key.</p>
+    </div>
+  </body>
+</html>""".encode("utf-8")
+
+ERROR_HTML = """<!doctype html>
+<html><head><meta charset="utf-8" /><title>Plexus CLI</title></head>
+<body><pre style="font-family:ui-monospace,monospace;padding:24px">
+Plexus CLI authorization failed. Return to your terminal for details.
+</pre></body></html>""".encode("utf-8")
+
+
+class _CallbackResult:
+    key: Optional[str] = None
+    state: Optional[str] = None
+    error: Optional[str] = None
+
+
+def _pick_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _make_handler(result: _CallbackResult, expected_state: str, done: threading.Event):
+    class Handler(http.server.BaseHTTPRequestHandler):
+        # Silence the default request log — we don't want CLI noise.
+        def log_message(self, *_args, **_kwargs):  # type: ignore[override]
+            return
+
+        def do_GET(self):  # type: ignore[override]
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != "/callback":
+                self.send_response(404)
+                self.end_headers()
+                return
+
+            params = urllib.parse.parse_qs(parsed.query)
+            got_state = (params.get("state") or [""])[0]
+            got_key = (params.get("key") or [""])[0]
+
+            if got_state != expected_state:
+                result.error = "state mismatch"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(ERROR_HTML)
+                done.set()
+                return
+
+            if not got_key:
+                result.error = "no key in callback"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(ERROR_HTML)
+                done.set()
+                return
+
+            result.key = got_key
+            result.state = got_state
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(SUCCESS_HTML)
+            done.set()
+
+    return Handler
+
+
+def _hostname_label() -> str:
+    try:
+        host = socket.gethostname() or "device"
+    except Exception:
+        host = "device"
+    # Strip the trailing .local etc. and clean it for display.
+    safe = host.split(".")[0].lower().replace(" ", "-")
+    return f"cli-{safe}" if safe else "cli"
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Open the browser, capture an API key, save it locally."""
+    existing = config.get_api_key()
+    if existing and not args.force:
+        print(
+            "An API key is already configured. "
+            "Re-run with --force to replace it.",
+            file=sys.stderr,
+        )
+        return 1
+
+    endpoint = config.get_endpoint().rstrip("/")
+    state = secrets.token_urlsafe(24)
+    name = args.name or _hostname_label()
+    port = _pick_free_port()
+    callback = f"http://127.0.0.1:{port}/callback"
+
+    auth_url = (
+        f"{endpoint}/auth/cli"
+        f"?state={urllib.parse.quote(state)}"
+        f"&callback={urllib.parse.quote(callback)}"
+        f"&name={urllib.parse.quote(name)}"
+    )
+
+    result = _CallbackResult()
+    done = threading.Event()
+    handler = _make_handler(result, state, done)
+
+    server = socketserver.TCPServer(("127.0.0.1", port), handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    try:
+        print(f"Opening {auth_url}")
+        try:
+            webbrowser.open(auth_url, new=1, autoraise=True)
+        except Exception:
+            pass  # User can copy the URL manually.
+
+        print("Waiting for browser confirmation...", flush=True)
+        finished = done.wait(timeout=args.timeout)
+        if not finished:
+            print(
+                f"Timed out after {args.timeout}s. Re-run `plexus init`.",
+                file=sys.stderr,
+            )
+            return 2
+    finally:
+        server.shutdown()
+        server.server_close()
+
+    if result.error or not result.key:
+        print(
+            f"Authorization failed: {result.error or 'no key returned'}",
+            file=sys.stderr,
+        )
+        return 3
+
+    cfg = config.load_config()
+    cfg["api_key"] = result.key
+    config.save_config(cfg)
+    print(f"✓ Saved API key as {name}.")
+    print("  ~/.plexus/config.json")
+    return 0
+
+
+def cmd_logout(_args: argparse.Namespace) -> int:
+    """Forget the locally stored API key."""
+    cfg = config.load_config()
+    if not cfg.get("api_key"):
+        print("Nothing to do — no key on file.")
+        return 0
+    cfg["api_key"] = None
+    config.save_config(cfg)
+    print("✓ Cleared local API key.")
+    return 0
+
+
+def cmd_whoami(_args: argparse.Namespace) -> int:
+    """Print the prefix of the locally stored key + the configured endpoint."""
+    key = config.get_api_key()
+    endpoint = config.get_endpoint()
+    if not key:
+        print("Not signed in. Run `plexus init` to authorize this machine.")
+        return 1
+    masked = f"{key[:8]}…{key[-4:]}" if len(key) > 12 else key
+    print(f"key:      {masked}")
+    print(f"endpoint: {endpoint}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="plexus",
+        description="Plexus CLI — auth, send, query telemetry from your terminal.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser(
+        "init",
+        help="Authorize this machine and save an API key locally.",
+        aliases=["login"],
+    )
+    init.add_argument("--name", help="Label for the issued key (default: cli-<hostname>).")
+    init.add_argument(
+        "--timeout",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="Seconds to wait for the browser callback.",
+    )
+    init.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing local key.",
+    )
+    init.set_defaults(func=cmd_init)
+
+    logout = sub.add_parser("logout", help="Forget the local API key.")
+    logout.set_defaults(func=cmd_logout)
+
+    whoami = sub.add_parser("whoami", help="Show the local credential summary.")
+    whoami.set_defaults(func=cmd_whoami)
+
+    return parser
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -49,7 +49,9 @@ from plexus.config import (
     get_endpoint,
     get_gateway_url,
     get_gateway_ws_url,
+    get_install_id,
     get_source_id,
+    set_source_id,
 )
 logger = logging.getLogger(__name__)
 
@@ -259,7 +261,7 @@ class Plexus:
                 ("position", {"x": 1.0, "y": 2.0}),
             ])
         """
-        ts = timestamp or time.time()
+        ts = timestamp if timestamp is not None else time.time()
         data_points = [self._make_point(m, v, ts, tags) for m, v in points]
         return self._send_points(data_points)
 
@@ -273,11 +275,23 @@ class Plexus:
             api_key=self.api_key,
             source_id=self.source_id,
             ws_url=self._ws_url,
+            install_id=get_install_id(),
             agent_version=__version__,
+            on_source_id_assigned=self._on_source_id_assigned,
         )
         self._ws.start()
         return self._ws
 
+    def _on_source_id_assigned(self, assigned: str) -> None:
+        """Callback from WebSocketTransport when the gateway returns an
+        auto-suffixed source_id. Persists it so subsequent runs (and the HTTP
+        fallback path in this process) use the assigned name directly."""
+        self.source_id = assigned
+        try:
+            set_source_id(assigned)
+        except Exception as e:  # pragma: no cover - persistence failure is non-fatal
+            logger.debug("failed to persist assigned source_id: %s", e)
+
     def on_command(
         self,
         name: str,

{plexus_python-0.3.0 → plexus_python-0.4.1}/plexus/config.py

@@ -145,6 +145,54 @@ def get_source_id() -> Optional[str]:
     return source_id
 
 
+def get_install_id() -> str:
+    """Get the device install ID, generating one if not set.
+
+    The install_id is a stable per-installation UUID. It is generated lazily
+    on first run (NOT at image-build time) so that cloned SD-card images
+    naturally get distinct install_ids on their first boot. The gateway uses
+    it to tell "same device reconnecting" from "different device claiming the
+    same name" when resolving source_id collisions.
+
+    Resolution order:
+      1. ``PLEXUS_INSTALL_ID`` env var — lets ephemeral containers (Fly
+         machines, CI runners, Kubernetes pods) pin a stable identity
+         across restarts when the config filesystem is ephemeral. Without
+         this, every redeploy generates a new install_id and the gateway
+         auto-suffixes the source_id to avoid a collision with the prior
+         install ("gw-001" → "gw-001_2" → "gw-001_3"…).
+      2. ``install_id`` in the on-disk config.
+      3. Newly-generated UUID, persisted to config.
+    """
+    env_id = os.environ.get("PLEXUS_INSTALL_ID", "").strip()
+    if env_id:
+        return env_id
+
+    config = load_config()
+    install_id = config.get("install_id")
+
+    if not install_id:
+        import uuid
+        install_id = uuid.uuid4().hex
+        config["install_id"] = install_id
+        save_config(config)
+
+    return install_id
+
+
+def set_source_id(source_id: str) -> None:
+    """Persist an updated source_id to the config file.
+
+    Called by the SDK when the gateway returns an auto-suffixed name so the
+    assigned name is stable across reconnects.
+    """
+    config = load_config()
+    if config.get("source_id") == source_id:
+        return
+    config["source_id"] = source_id
+    save_config(config)
+
+
 def get_persistent_buffer() -> bool:
     """Get persistent buffer setting. Default True (store-and-forward enabled)."""
     config = load_config()

{plexus_python-0.3.0 → plexus_python-0.4.1}/plexus/ws.py

@@ -5,8 +5,14 @@ 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": [...]}
+              "install_id": ..., "platform": "python-sdk",
+              "agent_version": ..., "commands": [...]}
     server → {"type": "authenticated", "source_id": ...}
+
+The server-returned `source_id` in the `authenticated` frame is
+authoritative: if the gateway auto-suffixed on a collision (e.g. the
+desired name was already claimed by a different install_id), the
+client's `source_id` is updated in place to match.
     client → {"type": "telemetry", "points": [...]}
     client → {"type": "heartbeat", "source_id": ..., "agent_version": ...}   # every 30s
     server → {"type": "typed_command", "id": ..., "command": ..., "params": {...}}
@@ -78,9 +84,11 @@ class WebSocketTransport:
         source_id: str,
         ws_url: str,
         *,
+        install_id: str = "",
         agent_version: str = "0.0.0",
         platform: str = "python-sdk",
         auto_reconnect: bool = True,
+        on_source_id_assigned: Optional[Callable[[str], None]] = None,
     ):
         if not api_key:
             raise ValueError("api_key required")
@@ -89,10 +97,12 @@ class WebSocketTransport:
 
         self.api_key = api_key
         self.source_id = source_id
+        self.install_id = install_id
         self.ws_url = _ensure_device_path(ws_url)
         self.agent_version = agent_version
         self.platform = platform
         self.auto_reconnect = auto_reconnect
+        self._on_source_id_assigned = on_source_id_assigned
 
         self._commands: Dict[str, _RegisteredCommand] = {}
         self._ws: Optional[websocket.WebSocket] = None
@@ -184,13 +194,16 @@ class WebSocketTransport:
             self._ws = ws
 
         # 1. Send device_auth
+        desired_source_id = self.source_id
         auth = {
             "type": "device_auth",
             "api_key": self.api_key,
-            "source_id": self.source_id,
+            "source_id": desired_source_id,
             "platform": self.platform,
             "agent_version": self.agent_version,
         }
+        if self.install_id:
+            auth["install_id"] = self.install_id
         if self._commands:
             auth["commands"] = [c.to_manifest() for c in self._commands.values()]
         ws.send(json.dumps(auth))
@@ -206,6 +219,22 @@ class WebSocketTransport:
         if msg.get("type") != "authenticated":
             raise RuntimeError(f"auth failed: {msg}")
 
+        # The gateway may return a different source_id if the desired name
+        # was already claimed by another install — adopt the assigned value
+        # so all subsequent frames (heartbeats, future reconnects) use it.
+        assigned = msg.get("source_id")
+        if isinstance(assigned, str) and assigned and assigned != self.source_id:
+            logger.info(
+                "plexus ws source_id auto-suffixed: requested=%s assigned=%s",
+                desired_source_id, assigned,
+            )
+            self.source_id = assigned
+            if self._on_source_id_assigned is not None:
+                try:
+                    self._on_source_id_assigned(assigned)
+                except Exception as e:  # pragma: no cover - callback errors must not break auth
+                    logger.debug("on_source_id_assigned callback raised: %s", e)
+
         self._authenticated.set()
         self._backoff_attempt = 0
         logger.info("plexus ws authenticated as %s", self.source_id)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.3.0"
+version = "0.4.1"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,6 +35,9 @@ dependencies = [
 [project.optional-dependencies]
 dev = ["pytest", "pytest-cov", "ruff", "websockets>=12"]
 
+[project.scripts]
+plexus = "plexus.cli:main"
+
 [project.urls]
 Homepage = "https://plexus.dev"
 Documentation = "https://docs.plexus.dev"

{plexus_python-0.3.0 → plexus_python-0.4.1}/scripts/setup.sh

@@ -43,6 +43,41 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+# --name is required so every device lands on a deliberate, unique identifier.
+# Previously we fell back to $(hostname), which silently merged streams on
+# cloned SD-card images where every device shared a hostname. If --name is
+# missing, prompt interactively in a TTY or fail loudly in non-interactive
+# contexts. Validation keeps the name safe for Redis keys, URLs, and logs.
+validate_device_name() {
+    local name="$1"
+    if [[ ! "$name" =~ ^[a-z0-9][a-z0-9_-]{1,62}$ ]]; then
+        echo -e "  ${RED}Invalid device name: \"$name\"${NC}"
+        echo "  Name must start with a letter or digit and contain only"
+        echo "  lowercase letters, digits, '-', or '_' (2-63 chars total)."
+        return 1
+    fi
+    return 0
+}
+
+if [ -z "$DEVICE_NAME" ]; then
+    if [ -t 0 ]; then
+        echo ""
+        echo "  Every device needs a unique name (e.g. drone-01, greenhouse-north)."
+        while [ -z "$DEVICE_NAME" ]; do
+            read -rp "  Device name: " DEVICE_NAME
+            if [ -n "$DEVICE_NAME" ] && ! validate_device_name "$DEVICE_NAME"; then
+                DEVICE_NAME=""
+            fi
+        done
+    else
+        echo -e "  ${RED}Error: --name is required${NC}" >&2
+        echo "  Example: curl -sL app.plexus.company/setup | bash -s -- --key plx_... --name drone-01" >&2
+        exit 1
+    fi
+elif ! validate_device_name "$DEVICE_NAME"; then
+    exit 1
+fi
+
 echo ""
 echo "┌─────────────────────────────────────────┐"
 echo "│  Plexus Agent Setup                     │"
@@ -282,14 +317,17 @@ echo ""
 if [ -n "$API_KEY" ]; then
     mkdir -p "$HOME/.plexus"
     ENDPOINT="https://app.plexus.company"
-    SOURCE_ID="${DEVICE_NAME:-$(hostname)}"
-    echo "{\"api_key\":\"$API_KEY\",\"endpoint\":\"$ENDPOINT\",\"source_id\":\"$SOURCE_ID\"}" > "$HOME/.plexus/config.json"
+    # install_id is intentionally NOT written here. The SDK generates it
+    # lazily on first run (plexus.config.get_install_id) so that pre-baked
+    # SD-card images get distinct install_ids per boot rather than sharing
+    # whatever we'd stamp here.
+    echo "{\"api_key\":\"$API_KEY\",\"endpoint\":\"$ENDPOINT\",\"source_id\":\"$DEVICE_NAME\"}" > "$HOME/.plexus/config.json"
 
     export PLEXUS_API_KEY="$API_KEY"
     echo -e "  ${GREEN}✓ API key configured${NC}"
-    if [ -n "$ORG_ID" ]; then
-        echo -e "  ${GREEN}✓ Organization resolved${NC}"
-    fi
+    echo -e "  ${GREEN}✓ Device name: ${CYAN}$DEVICE_NAME${NC}"
+    echo "    (the gateway may auto-suffix this if the name is already taken;"
+    echo "     the assigned name will be logged on first connect)"
     echo ""
 else
     echo "  No API key provided."
@@ -297,9 +335,7 @@ else
     echo "  To authenticate this device:"
     echo ""
     echo "  1. Get an API key from ${CYAN}https://app.plexus.company${NC} → Settings → Developer"
-    echo "  2. Run: ${CYAN}plexus start --key plx_xxxxx${NC}"
-    echo ""
-    echo "  Run ${CYAN}plexus start${NC} to sign in and connect."
+    echo "  2. Re-run this installer with: ${CYAN}--key plx_xxxxx --name $DEVICE_NAME${NC}"
     echo ""
 fi
 
@@ -308,10 +344,6 @@ echo "────────────────────────
 echo ""
 echo -e "  ${GREEN}Setup complete!${NC}"
 echo ""
-echo "  Quick commands:"
-echo "    plexus start     # Set up and stream"
-echo "    plexus reset     # Clear config and start over"
-echo ""
 echo "  Dashboard: ${CYAN}https://app.plexus.company${NC}"
 echo ""
 echo "  To uninstall:"

{plexus_python-0.3.0 → plexus_python-0.4.1}/tests/test_retry.py

@@ -329,23 +329,27 @@ class TestThreadSafety:
 
         def send_metric(metric_id):
             try:
-                with patch.object(client, "_get_session") as mock_session:
-                    mock_session.return_value.post.side_effect = (
-                        requests.exceptions.Timeout()
-                    )
-                    try:
-                        client.send(f"metric_{metric_id}", float(metric_id))
-                    except PlexusError:
-                        pass  # Expected
+                try:
+                    client.send(f"metric_{metric_id}", float(metric_id))
+                except PlexusError:
+                    pass  # Expected
             except Exception as e:
                 errors.append(e)
 
-        # Launch multiple threads
-        threads = [threading.Thread(target=send_metric, args=(i,)) for i in range(20)]
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join()
+        # Patch once outside the threads — patch.object mutates instance
+        # attrs and is not thread-safe under contention. We just need every
+        # call to fail so the buffer takes the write.
+        mock_session = MagicMock()
+        mock_session.return_value.post.side_effect = requests.exceptions.Timeout()
+
+        with patch.object(client, "_get_session", mock_session):
+            threads = [
+                threading.Thread(target=send_metric, args=(i,)) for i in range(20)
+            ]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join()
 
         # No errors should have occurred
         assert len(errors) == 0

{plexus_python-0.3.0 → plexus_python-0.4.1}/tests/test_ws.py

@@ -26,9 +26,13 @@ from plexus.ws import WebSocketTransport  # noqa: E402
 class _StubGateway:
     """Minimal gateway stub. Records every frame the client sends."""
 
-    def __init__(self):
+    def __init__(self, assigned_source_id: str | None = None):
         self.received: List[Dict[str, Any]] = []
         self.auth_frame: Dict[str, Any] = {}
+        # If set, the stub returns this value in the authenticated frame
+        # regardless of what the client asked for — used to exercise the
+        # auto-suffix path.
+        self.assigned_source_id = assigned_source_id
         self._loop: asyncio.AbstractEventLoop | None = None
         self._server = None
         self._thread: threading.Thread | None = None
@@ -53,9 +57,10 @@ class _StubGateway:
         raw = await ws.recv()
         msg = json.loads(raw)
         self.auth_frame = msg
+        returned_source_id = self.assigned_source_id or msg.get("source_id")
         await ws.send(json.dumps({
             "type": "authenticated",
-            "source_id": msg.get("source_id"),
+            "source_id": returned_source_id,
         }))
         try:
             async for raw in ws:
@@ -120,6 +125,7 @@ def test_auth_handshake_and_telemetry(gateway):
         api_key="plx_test_abc",
         source_id="drone-001",
         ws_url=_url(gateway.port),
+        install_id="install-A",
         agent_version="9.9.9",
     )
     t.start()
@@ -130,6 +136,7 @@ def test_auth_handshake_and_telemetry(gateway):
         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["install_id"] == "install-A"
         assert gateway.auth_frame["platform"] == "python-sdk"
         assert gateway.auth_frame["agent_version"] == "9.9.9"
         # commands is omitted when none registered
@@ -248,6 +255,78 @@ def test_handler_exception_returns_error(gateway):
         t.stop()
 
 
+def test_install_id_omitted_when_empty():
+    # Default install_id="" should not leak an empty install_id field into
+    # the auth frame — that keeps the wire shape identical for legacy SDK
+    # builds that don't set one.
+    g = _StubGateway()
+    g.start()
+    try:
+        t = WebSocketTransport(
+            api_key="plx_test_abc",
+            source_id="drone-001",
+            ws_url=_url(g.port),
+        )
+        t.start()
+        try:
+            assert t.wait_authenticated(timeout=3)
+            assert "install_id" not in g.auth_frame
+        finally:
+            t.stop()
+    finally:
+        g.stop()
+
+
+def test_server_assigned_source_id_is_adopted():
+    # Simulate the auto-suffix path: SDK asks for "drone-01", the gateway
+    # returns "drone-01_2" in the authenticated frame. The transport must
+    # adopt the assigned name and fire the on_source_id_assigned callback.
+    g = _StubGateway(assigned_source_id="drone-01_2")
+    g.start()
+    try:
+        seen: List[str] = []
+        t = WebSocketTransport(
+            api_key="plx_test_abc",
+            source_id="drone-01",
+            ws_url=_url(g.port),
+            install_id="install-B",
+            on_source_id_assigned=lambda s: seen.append(s),
+        )
+        t.start()
+        try:
+            assert t.wait_authenticated(timeout=3)
+            assert t.source_id == "drone-01_2"
+            assert seen == ["drone-01_2"]
+        finally:
+            t.stop()
+    finally:
+        g.stop()
+
+
+def test_same_assigned_source_id_does_not_fire_callback():
+    # Happy path — gateway returns the same name. No callback, source_id unchanged.
+    g = _StubGateway()  # echoes whatever was sent
+    g.start()
+    try:
+        seen: List[str] = []
+        t = WebSocketTransport(
+            api_key="plx_test_abc",
+            source_id="drone-01",
+            ws_url=_url(g.port),
+            install_id="install-A",
+            on_source_id_assigned=lambda s: seen.append(s),
+        )
+        t.start()
+        try:
+            assert t.wait_authenticated(timeout=3)
+            assert t.source_id == "drone-01"
+            assert seen == []
+        finally:
+            t.stop()
+    finally:
+        g.stop()
+
+
 def test_ensure_device_path():
     from plexus.ws import _ensure_device_path
     assert _ensure_device_path("wss://foo") == "wss://foo/ws/device"

plexus_python-0.3.0/CHANGELOG.md

@@ -1,45 +0,0 @@
-# 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()`.
-
-### Added
-
-- 5 runnable example scripts: `basic.py`, `mavlink.py`, `can.py`, `mqtt.py`, `i2c_bme280.py`
-
-### Removed
-
-- `plexus/adapters/` (MAVLink, CAN, MQTT, Modbus, OPC-UA, BLE, Serial — use the upstream lib directly)
-- `plexus/sensors/` (I2C drivers + auto-detect — use Adafruit CircuitPython or smbus2 directly)
-- `plexus/cameras/` (frame upload — out of scope)
-- `plexus/cli.py`, `plexus/connector.py`, `plexus/streaming.py`, `plexus/detect.py`, `plexus/tui.py`, `plexus/deps.py`
-- `plexus` console script, `python -m plexus`
-- Extras: `[sensors]`, `[system]`, `[tui]`, `[mqtt]`, `[can]`, `[mavlink]`, `[modbus]`, `[opcua]`, `[ble]`, `[serial]`, `[ros]`, `[camera]`, `[picamera]`, `[all]`
-- Runtime deps: `click`, `websockets`
-
-### Changed
-
-- Default ingest endpoint points directly at the Plexus gateway (`https://plexus-gateway.fly.dev/ingest`), not the Next.js app proxy
-- Client raises `ValueError` clearly when no API key is available, instead of invoking a login flow
-
-## [0.1.0] - Initial release
-
-- `Plexus` thin client for HTTP ingest
-- `plexus start` daemon with WebSocket streaming
-- Protocol adapters: MAVLink, CAN, MQTT, Modbus, OPC-UA, Serial, BLE
-- I2C sensor auto-detection and drivers
-- Store-and-forward buffering (SQLite)