plexus-python 0.5.1__tar.gz → 0.6.1__tar.gz

{plexus_python-0.5.1 → plexus_python-0.6.1}/.gitignore

@@ -52,3 +52,9 @@ htmlcov/
 # Local config
 .env
 .env.local
+
+# macOS
+.DS_Store
+
+# Logs
+*.log

{plexus_python-0.5.1 → plexus_python-0.6.1}/API.md

@@ -145,7 +145,7 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 
 ### Connection Flow
 
-1. Device connects to PartyKit server
+1. Device connects to the gateway
 2. Device authenticates with API key
 3. Device reports available sensors
 4. Dashboard controls streaming via messages

{plexus_python-0.5.1 → plexus_python-0.6.1}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.6.1] - 2026-05-28 - Thermal camera streaming
+
+### Added
+
+- `plexus.cameras.thermal` module with hardware-agnostic drivers for I2C sensors
+  (MLX90640, MLX90641) and USB cameras (Y16 pixel format). All drivers return a
+  unified `ThermalFrame` containing a colorized JPEG plus temperature metadata
+  (min, max, mean °C).
+- `ThermalSource.open()` auto-detects connected hardware; pass `"sim"` for a
+  simulated source with no physical device required.
+- `client.send_thermal_frame()` sends thermal frames over the existing WebSocket
+  connection. Small sensors (≤4096 pixels, e.g. 32×24 MLX90640) include the full
+  temperature array inline; larger USB sensors omit it to keep frame sizes manageable.
+- `examples/thermal_camera.py` — end-to-end example for streaming a thermal camera.
+
+## [0.5.2] - 2026-05-21 - DX hardening for hardware engineers
+
+### Fixed
+
+- Error messages now reference `plexus init` instead of the non-existent `plexus start`.
+- `close()` now attempts to flush any buffered points before tearing down the transport,
+  preventing silent data loss on graceful shutdown.
+- `persistent_buffer` default changed from `False` to `True` — store-and-forward is now
+  on by default, matching the `~/.plexus/config.json` default and the right choice for
+  field hardware. Pass `persistent_buffer=False` to opt out (e.g. in test fixtures).
+
+### Added
+
+- `send_batch()` now accepts 3-tuples `(metric, value, timestamp)` alongside the existing
+  2-tuple form. Per-point timestamps let sensors on different interrupt timers share a
+  single batch call. 2-tuples continue to use the shared `timestamp` argument.
+- `on_command()` now warns immediately via stderr if called after the WebSocket has already
+  authenticated, making the "register before first send()" ordering requirement visible
+  rather than silently broken.
+- `source_id` is validated against `^[a-z0-9][a-z0-9_-]{1,62}$` at construction time.
+  Invalid names now raise `ValueError` with a clear message instead of failing obscurely
+  at the gateway.
+
+### Changed
+
+- `_say()` / `_QUIET` consolidated into a new internal `plexus/_log.py` module.
+  Previously duplicated verbatim between `client.py` and `ws.py`.
+
 ## [0.5.1] - 2026-05-19 - Binary video frames + non-blocking send
 
 ### Performance

{plexus_python-0.5.1 → plexus_python-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.5.1
+Version: 0.6.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
@@ -23,10 +23,15 @@ Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.10
 Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: opencv-python>=4.8; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
+Provides-Extra: thermal
+Requires-Dist: numpy>=1.24; extra == 'thermal'
+Requires-Dist: opencv-python>=4.8; extra == 'thermal'
 Provides-Extra: video
 Requires-Dist: pillow>=12.2.0; extra == 'video'
 Description-Content-Type: text/markdown

{plexus_python-0.5.1 → plexus_python-0.6.1}/SECURITY.md

@@ -23,8 +23,8 @@ Instead, email **support@plexus.company** with:
 
 | Version | Supported |
 | ------- | --------- |
-| 0.9.x   | Yes       |
-| < 0.9   | No        |
+| 0.5.x   | Yes       |
+| < 0.5   | No        |
 
 ## Disclosure Policy
 

plexus_python-0.6.1/examples/thermal_camera.py

@@ -0,0 +1,88 @@
+"""
+Thermal camera streaming to Plexus.
+
+Reads from any supported thermal camera and sends frames to Plexus using
+the SDK's send_thermal_frame() method. The gateway relays colorized JPEG
+frames to the app, along with temperature range and (for small sensors)
+per-pixel temperature data.
+
+Supported hardware (--camera argument):
+    sim         Simulated camera — no hardware needed (default)
+    mlx90640    MLX90640 32×24 I2C sensor (pip install adafruit-circuitpython-mlx90640)
+    mlx90641    MLX90641 16×12 I2C sensor (pip install adafruit-circuitpython-mlx90641)
+    usb         USB thermal camera in Y16 format (InfiRay, Topdon, Seek, etc.)
+
+Run:
+    export PLEXUS_API_KEY=plx_xxx
+    python thermal_camera.py
+    python thermal_camera.py --camera mlx90640
+    python thermal_camera.py --camera usb --device 2
+"""
+
+import argparse
+import sys
+import time
+
+from plexus import Plexus
+from plexus.cameras.thermal import NoCameraFound, ThermalSource
+
+CAMERA_ID = "thermal"
+FPS = 5
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Stream thermal camera to Plexus.")
+    parser.add_argument(
+        "--camera",
+        choices=["sim", "mlx90640", "mlx90641", "usb"],
+        default=None,
+        help="Camera driver (default: auto-detect)",
+    )
+    parser.add_argument(
+        "--device",
+        type=int,
+        default=0,
+        help="USB video device index (default: 0)",
+    )
+    args = parser.parse_args()
+
+    hint = args.device if args.camera == "usb" else args.camera
+    try:
+        cam = ThermalSource.open(hint)
+    except NoCameraFound as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    px = Plexus(transport="ws")
+    px.wait_connected()
+
+    interval = 1.0 / FPS
+    frame_count = 0
+    print(f"Streaming {cam.width}×{cam.height} thermal at {FPS} fps — Ctrl-C to stop")
+
+    try:
+        while True:
+            t0 = time.time()
+
+            temps = cam.read_frame()
+            px.send_thermal_frame(temps, camera_id=CAMERA_ID)
+
+            frame_count += 1
+            if frame_count % 50 == 0:
+                print(f"  {frame_count} frames sent")
+
+            elapsed = time.time() - t0
+            wait = interval - elapsed
+            if wait > 0:
+                time.sleep(wait)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        cam.close()
+        px.stop()
+        print(f"Done. {frame_count} frames sent.")
+
+
+if __name__ == "__main__":
+    main()

{plexus_python-0.5.1 → plexus_python-0.6.1}/examples/uv.lock

@@ -674,11 +674,11 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.6.3"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
 ]
 
 [[package]]

{plexus_python-0.5.1 → plexus_python-0.6.1}/plexus/__init__.py

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

plexus_python-0.6.1/plexus/_log.py

@@ -0,0 +1,15 @@
+import os
+import sys
+
+_QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
+
+
+def _say(line: str) -> None:
+    """Single-line status message to stderr. Skipped if PLEXUS_QUIET=1."""
+    if _QUIET:
+        return
+    try:
+        sys.stderr.write(f"[plexus] {line}\n")
+        sys.stderr.flush()
+    except Exception:
+        pass

plexus_python-0.6.1/plexus/cameras/__init__.py

@@ -0,0 +1,25 @@
+from plexus.cameras.thermal import (
+    NoCameraFound,
+    MLX90640Camera,
+    MLX90641Camera,
+    SimulatedThermalCamera,
+    ThermalCamera,
+    ThermalFrame,
+    ThermalSource,
+    USBThermalCamera,
+    build_thermal_frame,
+    encode_frame,
+)
+
+__all__ = [
+    "NoCameraFound",
+    "MLX90640Camera",
+    "MLX90641Camera",
+    "SimulatedThermalCamera",
+    "ThermalCamera",
+    "ThermalFrame",
+    "ThermalSource",
+    "USBThermalCamera",
+    "build_thermal_frame",
+    "encode_frame",
+]

plexus_python-0.6.1/plexus/cameras/thermal.py

@@ -0,0 +1,388 @@
+"""
+Thermal camera drivers for Plexus.
+
+Provides a hardware-agnostic interface over I2C sensors (MLX90640, MLX90641)
+and USB thermal cameras (Y16 pixel format). All drivers return a unified
+ThermalFrame containing a colorized JPEG image plus temperature metadata.
+
+Usage:
+    from plexus.cameras.thermal import ThermalSource
+
+    cam = ThermalSource.open()          # auto-detect
+    cam = ThermalSource.open("sim")     # simulated, no hardware
+
+    while True:
+        px.send_thermal_frame(cam.read_frame(), camera_id="thermal")
+        time.sleep(1 / 5)
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import cv2
+import numpy as np
+
+# Inferno is perceptually uniform and well-suited for thermal imaging.
+# Swap for cv2.COLORMAP_HOT or cv2.COLORMAP_JET if preferred.
+_COLORMAP = cv2.COLORMAP_INFERNO
+
+# Sensors at or below this pixel count include the full temps array in the
+# wire message. I2C sensors (32×24 = 768, 16×12 = 192) always qualify.
+# USB thermal cameras (256×192 = 49 152) do not.
+_TEMPS_INLINE_THRESHOLD = 4096
+
+# Upscale sensors whose shortest side is below this threshold.
+_MIN_DISPLAY_SIDE = 160
+
+
+class NoCameraFound(RuntimeError):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Abstract interface
+# ---------------------------------------------------------------------------
+
+
+class ThermalCamera(ABC):
+    """Hardware-agnostic thermal camera interface.
+
+    Subclass and implement read_frame() to support any sensor.
+    read_frame() must return a 2-D float32 array of temperatures in Celsius,
+    shaped (height, width).
+    """
+
+    @property
+    @abstractmethod
+    def width(self) -> int: ...
+
+    @property
+    @abstractmethod
+    def height(self) -> int: ...
+
+    @abstractmethod
+    def read_frame(self) -> np.ndarray: ...
+
+    def close(self) -> None:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Unified output
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ThermalFrame:
+    """Encoded output from a ThermalCamera, ready to send to the gateway."""
+
+    image: np.ndarray        # uint8 BGR colorized image (display size)
+    width: int               # display width (may differ from sensor if upscaled)
+    height: int              # display height
+    sensor_width: int        # native sensor width
+    sensor_height: int       # native sensor height
+    temp_min: float
+    temp_max: float
+    temps: Optional[np.ndarray]  # native res; None when sensor > threshold
+    timestamp_ms: int
+
+    def to_message(
+        self, camera_id: str, source_id: Optional[str] = None, quality: int = 85
+    ) -> Dict[str, Any]:
+        """Build the gateway `video_frame` wire message for this frame."""
+        _, buf = cv2.imencode(".jpg", self.image, [cv2.IMWRITE_JPEG_QUALITY, quality])
+        b64 = base64.b64encode(buf.tobytes()).decode("ascii")
+
+        msg: Dict[str, Any] = {
+            "type": "video_frame",
+            "camera_id": camera_id,
+            "frame": b64,
+            "width": self.width,
+            "height": self.height,
+            "timestamp": self.timestamp_ms,
+            "video_type": "thermal",
+            "sensor_width": self.sensor_width,
+            "sensor_height": self.sensor_height,
+            "temp_min": self.temp_min,
+            "temp_max": self.temp_max,
+        }
+        if source_id is not None:
+            msg["source_id"] = source_id
+        if self.temps is not None:
+            msg["temps"] = self.temps.flatten().tolist()
+        return msg
+
+
+# ---------------------------------------------------------------------------
+# Encoding — single shared path used by both encode_frame() and the SDK's
+# Plexus.send_thermal_frame().
+# ---------------------------------------------------------------------------
+
+
+def _upscale_size(sw: int, sh: int) -> tuple[int, int]:
+    if sw >= _MIN_DISPLAY_SIDE and sh >= _MIN_DISPLAY_SIDE:
+        return sw, sh
+    scale = max(_MIN_DISPLAY_SIDE / sw, _MIN_DISPLAY_SIDE / sh)
+    return round(sw * scale), round(sh * scale)
+
+
+def build_thermal_frame(
+    temps: np.ndarray, timestamp_ms: Optional[int] = None
+) -> ThermalFrame:
+    """Colorize a temperature array into a ThermalFrame.
+
+    temps: 2-D float32 Celsius array, shape (height, width).
+    timestamp_ms: wire timestamp; defaults to current time.
+    """
+    sh, sw = temps.shape[:2]
+
+    temp_min = float(np.min(temps))
+    temp_max = float(np.max(temps))
+    span = temp_max - temp_min
+
+    normalized = (
+        np.zeros((sh, sw), dtype=np.uint8)
+        if span < 1e-6
+        else ((temps - temp_min) / span * 255).astype(np.uint8)
+    )
+
+    colored = cv2.applyColorMap(normalized, _COLORMAP)
+
+    dw, dh = _upscale_size(sw, sh)
+    if (dw, dh) != (sw, sh):
+        colored = cv2.resize(colored, (dw, dh), interpolation=cv2.INTER_CUBIC)
+
+    return ThermalFrame(
+        image=colored,
+        width=dw,
+        height=dh,
+        sensor_width=sw,
+        sensor_height=sh,
+        temp_min=round(temp_min, 2),
+        temp_max=round(temp_max, 2),
+        temps=temps if sw * sh <= _TEMPS_INLINE_THRESHOLD else None,
+        timestamp_ms=timestamp_ms if timestamp_ms is not None else int(time.time() * 1000),
+    )
+
+
+def encode_frame(cam: ThermalCamera) -> ThermalFrame:
+    """Read one frame from a camera and colorize it."""
+    return build_thermal_frame(cam.read_frame())
+
+
+# ---------------------------------------------------------------------------
+# Drivers
+# ---------------------------------------------------------------------------
+
+
+class SimulatedThermalCamera(ThermalCamera):
+    """Simulated thermal camera for testing without hardware.
+
+    Produces a moving warm blob over a noisy background at 32×24.
+    """
+
+    def __init__(self, width: int = 32, height: int = 24) -> None:
+        self._width = width
+        self._height = height
+        self._t = 0.0
+
+    @property
+    def width(self) -> int:
+        return self._width
+
+    @property
+    def height(self) -> int:
+        return self._height
+
+    def read_frame(self) -> np.ndarray:
+        self._t += 0.1
+        x = np.linspace(0, 2 * np.pi, self._width)
+        y = np.linspace(0, 2 * np.pi, self._height)
+        xx, yy = np.meshgrid(x, y)
+        base = 22.0 + 3.0 * np.sin(xx + self._t) * np.cos(yy + self._t * 0.7)
+        cx = int((np.sin(self._t * 0.5) * 0.4 + 0.5) * self._width)
+        cy = int((np.cos(self._t * 0.3) * 0.4 + 0.5) * self._height)
+        yg, xg = np.ogrid[: self._height, : self._width]
+        hotspot = 15.0 * np.exp(-((xg - cx) ** 2 + (yg - cy) ** 2) / 20.0)
+        return (base + hotspot).astype(np.float32)
+
+
+class USBThermalCamera(ThermalCamera):
+    """USB thermal camera via V4L2/UVC in Y16 pixel format.
+
+    Most USB thermal cameras (InfiRay, Topdon, Seek, some FLIR) present as
+    standard UVC video devices outputting Y16 frames where each uint16 pixel
+    encodes temperature as: celsius = (value / 100.0) - 273.15
+
+    Requires: pip install opencv-python
+    """
+
+    _KELVIN_SCALE = 100.0
+    _KELVIN_OFFSET = 273.15
+
+    def __init__(self, device_index: int = 0) -> None:
+        self._cap = cv2.VideoCapture(device_index)
+        if not self._cap.isOpened():
+            raise NoCameraFound(f"Cannot open video device {device_index}")
+        self._cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"Y16 "))
+        ret, frame = self._cap.read()
+        if not ret or frame is None:
+            self._cap.release()
+            raise NoCameraFound(
+                f"Device {device_index} opened but could not read a frame. "
+                "Check that it supports Y16 format."
+            )
+        self._width = int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        self._height = int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+    @property
+    def width(self) -> int:
+        return self._width
+
+    @property
+    def height(self) -> int:
+        return self._height
+
+    def read_frame(self) -> np.ndarray:
+        ret, raw = self._cap.read()
+        if not ret or raw is None:
+            raise RuntimeError("Failed to read frame from USB thermal camera")
+        u16 = raw.view(np.uint16).reshape(self._height, self._width)
+        return (u16.astype(np.float32) / self._KELVIN_SCALE) - self._KELVIN_OFFSET
+
+    def close(self) -> None:
+        self._cap.release()
+
+
+class MLX90640Camera(ThermalCamera):
+    """MLX90640 32×24 thermal array via I2C.
+
+    Requires: pip install adafruit-circuitpython-mlx90640
+    Wiring:   SCL → GPIO 3, SDA → GPIO 2, 3.3V power (Raspberry Pi).
+    """
+
+    def __init__(self) -> None:
+        import adafruit_mlx90640
+        import board
+        import busio
+
+        i2c = busio.I2C(board.SCL, board.SDA, frequency=800_000)
+        self._mlx = adafruit_mlx90640.MLX90640(i2c)
+        self._mlx.refresh_rate = adafruit_mlx90640.RefreshRate.REFRESH_4_HZ
+        self._buf = [0.0] * 768
+
+    @property
+    def width(self) -> int:
+        return 32
+
+    @property
+    def height(self) -> int:
+        return 24
+
+    def read_frame(self) -> np.ndarray:
+        self._mlx.getFrame(self._buf)
+        return np.array(self._buf, dtype=np.float32).reshape(24, 32)
+
+
+class MLX90641Camera(ThermalCamera):
+    """MLX90641 16×12 thermal array via I2C.
+
+    Requires: pip install adafruit-circuitpython-mlx90641
+    Wiring:   SCL → GPIO 3, SDA → GPIO 2, 3.3V power (Raspberry Pi).
+    """
+
+    def __init__(self) -> None:
+        import adafruit_mlx90641
+        import board
+        import busio
+
+        i2c = busio.I2C(board.SCL, board.SDA, frequency=400_000)
+        self._mlx = adafruit_mlx90641.MLX90641(i2c)
+        self._mlx.refresh_rate = adafruit_mlx90641.RefreshRate.REFRESH_4_HZ
+        self._buf = [0.0] * 192
+
+    @property
+    def width(self) -> int:
+        return 16
+
+    @property
+    def height(self) -> int:
+        return 12
+
+    def read_frame(self) -> np.ndarray:
+        self._mlx.getFrame(self._buf)
+        return np.array(self._buf, dtype=np.float32).reshape(12, 16)
+
+
+# ---------------------------------------------------------------------------
+# Auto-detection factory
+# ---------------------------------------------------------------------------
+
+
+class ThermalSource:
+    """Factory that opens the first available thermal camera.
+
+    Examples:
+        ThermalSource.open()             # auto-detect
+        ThermalSource.open("sim")        # simulated
+        ThermalSource.open("mlx90640")   # force I2C MLX90640
+        ThermalSource.open("mlx90641")   # force I2C MLX90641
+        ThermalSource.open("usb")        # USB thermal at index 0
+        ThermalSource.open(2)            # USB thermal at index 2
+    """
+
+    @staticmethod
+    def open(hint: str | int | None = None) -> ThermalCamera:
+        if hint == "sim":
+            return SimulatedThermalCamera()
+        if hint == "mlx90640":
+            return MLX90640Camera()
+        if hint == "mlx90641":
+            return MLX90641Camera()
+        if hint == "usb" or isinstance(hint, int):
+            return USBThermalCamera(0 if hint == "usb" else hint)
+        return ThermalSource._autodetect()
+
+    @staticmethod
+    def _autodetect() -> ThermalCamera:
+        cam = ThermalSource._try_i2c()
+        if cam:
+            return cam
+        cam = ThermalSource._try_usb()
+        if cam:
+            return cam
+        raise NoCameraFound(
+            "No thermal camera detected. Use ThermalSource.open('sim') to run without hardware."
+        )
+
+    @staticmethod
+    def _try_i2c() -> ThermalCamera | None:
+        try:
+            import board
+            import busio
+
+            i2c = busio.I2C(board.SCL, board.SDA)
+            i2c.try_lock()
+            addrs = i2c.scan()
+            i2c.unlock()
+            if 0x33 in addrs:
+                return MLX90640Camera()
+            if 0x60 in addrs:
+                return MLX90641Camera()
+        except Exception:
+            pass
+        return None
+
+    @staticmethod
+    def _try_usb() -> ThermalCamera | None:
+        for idx in range(10):
+            try:
+                return USBThermalCamera(idx)
+            except NoCameraFound:
+                continue
+        return None