plexus-python 0.4.5__py3-none-any.whl → 0.4.7__py3-none-any.whl

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.4.5"
+__version__ = "0.4.7"
 __all__ = ["Plexus", "WebSocketTransport"]

plexus/client.py

@@ -33,6 +33,7 @@ Usage:
 Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
 """
 
+import base64
 import gzip
 import json
 import logging
@@ -134,12 +135,14 @@ class Plexus:
         self._run_id: Optional[str] = None
         self._session: Optional[requests.Session] = None
         self._store_frames: bool = False
+        self._cv2 = None
 
         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()
+        self._clock_offset_ms: int = 0
 
         # Pluggable buffer backend for failed sends
         if persistent_buffer:
@@ -175,17 +178,16 @@ class Plexus:
             self._session.headers["User-Agent"] = f"plexus-python/{__version__}"
         return self._session
 
-    @staticmethod
-    def _normalize_ts_ms(timestamp: Optional[float] = None) -> int:
+    def _normalize_ts_ms(self, timestamp: Optional[float] = None) -> int:
         """Normalize a timestamp to milliseconds.
 
         Accepts:
-            - None: returns current time in ms
-            - float seconds (e.g. time.time()): converts to ms
-            - int/float ms: returned as-is
+            - None: returns current time in ms, corrected by server clock offset
+            - float seconds (e.g. time.time()): converts to ms (no offset applied)
+            - int/float ms: returned as-is (no offset applied)
         """
         if timestamp is None:
-            return int(time.time() * 1000)
+            return int(time.time() * 1000) + self._clock_offset_ms
         # Heuristic: values < 1e12 are seconds
         if timestamp > 0 and timestamp < 1e12:
             return int(timestamp * 1000)
@@ -258,6 +260,30 @@ class Plexus:
         point = self._make_point(metric, value, timestamp, tags, data_class)
         return self._send_points([point])
 
+    def event(
+        self,
+        name: str,
+        data: FlexValue,
+        timestamp: Optional[float] = None,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> bool:
+        """
+        Send a named event with text or structured data.
+
+        Args:
+            name: Event type (e.g., "fault", "state_change", "log")
+            data: Text or JSON-serializable value (string, dict, list, bool, number)
+            timestamp: Unix timestamp. If not provided, uses current time.
+            tags: Optional key-value tags
+
+        Example:
+            px.event("fault", "E-stop triggered")
+            px.event("state_change", {"from": "IDLE", "to": "RUNNING"})
+            px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
+        """
+        point = self._make_point(name, data, timestamp, tags, data_class="event")
+        return self._send_points([point])
+
     def send_batch(
         self,
         points: List[Tuple[str, FlexValue]],
@@ -283,8 +309,8 @@ class Plexus:
                 ("position", {"x": 1.0, "y": 2.0}),
             ])
         """
-        ts = timestamp if timestamp is not None else time.time()
-        data_points = [self._make_point(m, v, ts, tags) for m, v in points]
+        ts_ms = self._normalize_ts_ms(timestamp)
+        data_points = [self._make_point(m, v, ts_ms, tags) for m, v in points]
         return self._send_points(data_points)
 
     def _ensure_ws(self):
@@ -300,10 +326,14 @@ class Plexus:
             install_id=get_install_id(),
             agent_version=__version__,
             on_source_id_assigned=self._on_source_id_assigned,
+            on_clock_synced=self._on_clock_synced,
         )
         self._ws.start()
         return self._ws
 
+    def _on_clock_synced(self, offset_ms: int) -> None:
+        self._clock_offset_ms = offset_ms
+
     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
@@ -314,6 +344,65 @@ class Plexus:
         except Exception as e:  # pragma: no cover - persistence failure is non-fatal
             logger.debug("failed to persist assigned source_id: %s", e)
 
+    def send_video_frame(
+        self,
+        frame,
+        camera_id: str = "camera:0",
+        quality: int = 85,
+        timestamp: Optional[float] = None,
+    ) -> bool:
+        """
+        Send a single video frame to Plexus (WebSocket transport only).
+
+        Args:
+            frame: A numpy array (H, W, C) as returned by cv2.VideoCapture.read()
+            camera_id: Logical camera identifier (e.g. "picam:0", "usb:1")
+            quality: JPEG compression quality, 1-100. Default 85.
+            timestamp: Unix timestamp. If not provided, uses current time.
+
+        Returns:
+            True if the frame was sent successfully.
+
+        Raises:
+            PlexusError: If transport is not 'ws', or if the send fails.
+            ImportError: If opencv-python is not installed.
+
+        Example:
+            cap = cv2.VideoCapture(0)
+            ret, frame = cap.read()
+            px.send_video_frame(frame, camera_id="picam:0")
+        """
+        if self.transport != "ws":
+            raise PlexusError("send_video_frame requires transport='ws'")
+
+        if self._cv2 is None:
+            try:
+                import cv2 as _cv2
+                self._cv2 = _cv2
+            except ImportError as e:
+                raise ImportError(
+                    "send_video_frame requires opencv-python. "
+                    "Install with: pip install opencv-python"
+                ) from e
+
+        height, width = frame.shape[:2]
+        _, buf = self._cv2.imencode(".jpg", frame, [self._cv2.IMWRITE_JPEG_QUALITY, quality])
+        b64 = base64.b64encode(buf).decode()
+
+        ws = self._ensure_ws()
+        if not ws.is_authenticated:
+            ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+
+        return ws._send_frame({
+            "type": "video_frame",
+            "source_id": self.source_id,
+            "camera_id": camera_id,
+            "frame": b64,
+            "width": width,
+            "height": height,
+            "timestamp": self._normalize_ts_ms(timestamp),
+        })
+
     def on_command(
         self,
         name: str,
@@ -555,7 +644,7 @@ class Plexus:
                     "source_id": self.source_id,
                     "status": "started",
                     "tags": tags,
-                    "timestamp": time.time(),
+                    "timestamp": (int(time.time() * 1000) + self._clock_offset_ms) / 1000,
                 },
                 timeout=self.timeout,
             )
@@ -573,7 +662,7 @@ class Plexus:
                         "run_id": run_id,
                         "source_id": self.source_id,
                         "status": "ended",
-                        "timestamp": time.time(),
+                        "timestamp": (int(time.time() * 1000) + self._clock_offset_ms) / 1000,
                     },
                     timeout=self.timeout,
                 )

plexus/ws.py

@@ -25,6 +25,7 @@ Runs the read loop on a background daemon thread so callers can stay sync.
 
 from __future__ import annotations
 
+import atexit
 import json
 import logging
 import os
@@ -108,6 +109,7 @@ class WebSocketTransport:
         platform: str = "python-sdk",
         auto_reconnect: bool = True,
         on_source_id_assigned: Optional[Callable[[str], None]] = None,
+        on_clock_synced: Optional[Callable[[int], None]] = None,
     ):
         if not api_key:
             raise ValueError("api_key required")
@@ -122,6 +124,7 @@ class WebSocketTransport:
         self.platform = platform
         self.auto_reconnect = auto_reconnect
         self._on_source_id_assigned = on_source_id_assigned
+        self._on_clock_synced = on_clock_synced
 
         self._commands: Dict[str, _RegisteredCommand] = {}
         self._ws: Optional[websocket.WebSocket] = None
@@ -130,6 +133,7 @@ class WebSocketTransport:
         self._stop = threading.Event()
         self._thread: Optional[threading.Thread] = None
         self._backoff_attempt = 0
+        self._clock_offset_ms: int = 0
 
     # ------------------------------------------------------------------ public
 
@@ -155,6 +159,7 @@ class WebSocketTransport:
             target=self._run, name="plexus-ws", daemon=True
         )
         self._thread.start()
+        atexit.register(self.stop)
 
     def stop(self, timeout: float = 2.0) -> None:
         self._stop.set()
@@ -175,6 +180,10 @@ class WebSocketTransport:
     def is_authenticated(self) -> bool:
         return self._authenticated.is_set()
 
+    @property
+    def clock_offset_ms(self) -> int:
+        return self._clock_offset_ms
+
     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."""
@@ -250,6 +259,15 @@ class WebSocketTransport:
         if msg.get("type") != "authenticated":
             raise RuntimeError(f"auth failed: {msg}")
 
+        server_ts = msg.get("server_time_ms")
+        if isinstance(server_ts, (int, float)) and server_ts > 0:
+            self._clock_offset_ms = int(server_ts) - int(time.time() * 1000)
+            if self._on_clock_synced is not None:
+                try:
+                    self._on_clock_synced(self._clock_offset_ms)
+                except Exception as e:
+                    logger.debug("on_clock_synced callback raised: %s", e)
+
         # 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.
@@ -274,7 +292,6 @@ class WebSocketTransport:
             _say(f"✓ Reconnected as {self.source_id}")
         else:
             _say(f"✓ Connected to gateway as {self.source_id}")
-            _say(f"  endpoint: {self.ws_url}")
 
         # 3. Read loop with heartbeat pump
         ws.settimeout(1.0)

{plexus_python-0.4.5.dist-info → plexus_python-0.4.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.5
+Version: 0.4.7
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -136,6 +136,24 @@ px.buffer_size()
 px.flush_buffer()
 ```
 
+## Timestamps and clock correction
+
+By default — `px.send("temp", 72.5)` with no `timestamp` argument — the SDK picks the time itself. Over WebSocket, it synchronizes with the gateway clock on every connection, so data lands at the right place on the timeline even if the device's system clock is wrong (no NTP on first boot, stale RTC, fresh OS image).
+
+```python
+px.send("temperature", 72.5)                # SDK picks time; gateway-synced over WS
+px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no correction
+```
+
+**Pass an explicit timestamp when** you have a reliable external time source (GPS, trusted RTC, host NTP) or are replaying historical data with known timestamps.
+
+**Omit timestamp when** the device may have booted without NTP — which is the default on Raspberry Pi, Jetson, and most embedded Linux boards without a network connection at first boot.
+
+**Known limits:**
+- Clock sync refreshes on WebSocket (re)connect. A device with a drifting RTC that stays connected for many days accumulates uncorrected drift between reconnects.
+- HTTP-only transport (`transport="http"`) does not receive clock sync — timestamps default to the uncorrected device clock.
+- `send_batch()` shares one timestamp across the whole batch. For per-point timestamps, call `send()` in a loop.
+
 ## 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:

plexus_python-0.4.7.dist-info/RECORD

@@ -0,0 +1,11 @@
+plexus/__init__.py,sha256=5Ef1BoSacfFvLTXaSV84bJWMSelmuX43AzO7QRphoys,345
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=uSmgxeGs3BOFfhtnTwH2L-uia-zyRuJTtTYEjyCMl0g,25016
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=4nmNganwS_1BujdFkH3u3lLBB7rEkPYd_oYrbdYkdY4,14818
+plexus_python-0.4.7.dist-info/METADATA,sha256=4tdaBPCjJn2jWzk52vQLSg6zGtq2RrvSU5eF6yanqbI,8121
+plexus_python-0.4.7.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.4.7.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.4.7.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.4.7.dist-info/RECORD,,

plexus_python-0.4.5.dist-info/RECORD

@@ -1,11 +0,0 @@
-plexus/__init__.py,sha256=9USZDYoueDQVWKI7HREgzoDRIaPaxNCYmf8ng-CcDn0,345
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
-plexus/client.py,sha256=YtPa7lT5gC0etglIJEs1DInsE3qtPBaMZDZ552DKgS4,21706
-plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
-plexus/ws.py,sha256=qGZL9TsYUpzUwEew1tgXIvQdYm1GNxnFu-pLqxfAulA,14134
-plexus_python-0.4.5.dist-info/METADATA,sha256=SLGrAflShkZdfXBbyjZwJIsFUt63tGnd38Hd0ZrwOI0,6800
-plexus_python-0.4.5.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.4.5.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.4.5.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.4.5.dist-info/RECORD,,