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

{plexus_python-0.3.0 → plexus_python-0.4.2}/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.2}/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.2/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+## [0.4.2] - 2026-04-27 - CLI auth: branded success page + auto-redirect
+
+### Changed
+
+- `plexus/cli.py` — the localhost callback's success and error pages now
+  match the Plexus app's dark aesthetic (black background, zinc-800
+  bordered card, white headlines, monospace URL, status-color badge).
+- After a successful `plexus init`, the browser tab now auto-redirects
+  to the configured app endpoint (`PLEXUS_ENDPOINT`, default
+  `https://app.plexus.company`) after a 10-second countdown, so first-
+  time users land on their dashboard without having to navigate there
+  manually. Falls back to `<meta http-equiv="refresh">` when JS is off.
+
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.3.0
+Version: 0.4.2
 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.2}/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.2}/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.2}/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.2}/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"]