plexus-python 0.4.3__tar.gz → 0.4.6__tar.gz

{plexus_python-0.4.3 → plexus_python-0.4.6}/API.md

@@ -98,7 +98,7 @@ x-api-key: plx_xxxxx
 | ------------ | ------ | -------- | ---------------------------------------------- |
 | `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`) |
 | `value`      | any    | Yes      | See supported value types below                |
-| `timestamp`  | float  | No       | Unix timestamp (seconds). Defaults to now      |
+| `timestamp`  | float  | No       | Unix timestamp in seconds (or ms if ≥ 1e12). Omit to use device time. Over WebSocket, the Python SDK applies a server-synced clock correction when omitted — see [Clock correction](#clock-correction). |
 | `source_id`  | string | Yes      | Your source identifier                         |
 | `tags`       | object | No       | Key-value labels                               |
 | `session_id` | string | No       | Group data into sessions                       |
@@ -168,18 +168,22 @@ Devices authenticate using an API key. The `source_id` in the request is the dev
 // Server → Device
 {
   "type": "authenticated",
-  "source_id": "drone-01"
+  "source_id": "drone-01",
+  "server_time_ms": 1746100800000
 }
 
 // Server → Device (collision case)
 {
   "type": "authenticated",
-  "source_id": "drone-01_2"
+  "source_id": "drone-01_2",
+  "server_time_ms": 1746100800000
 }
 ```
 
 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.
 
+`server_time_ms` is the gateway's current Unix time in milliseconds. The Python SDK uses it to compute a clock offset (`server_time - device_time`) that is applied to every SDK-generated timestamp for the lifetime of the connection. This corrects for devices that boot without NTP or have an unreliable RTC — a common condition on embedded Linux. See [Clock correction](#clock-correction) for details and limitations.
+
 `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)
@@ -354,6 +358,9 @@ func main() {
 #include <WiFi.h>
 #include <HTTPClient.h>
 
+// Call configTime(0, 0, "pool.ntp.org") in setup() before sending.
+// time(nullptr) returns 0 until NTP sync completes — omit the timestamp
+// field entirely if you cannot guarantee NTP sync at send time.
 void sendToPlexus(const char* metric, float value) {
     HTTPClient http;
     http.begin("https://plexus-gateway.fly.dev/ingest");
@@ -363,7 +370,7 @@ void sendToPlexus(const char* metric, float value) {
     String payload = "{\"points\":[{";
     payload += "\"metric\":\"" + String(metric) + "\",";
     payload += "\"value\":" + String(value) + ",";
-    payload += "\"timestamp\":" + String(millis() / 1000.0) + ",";
+    payload += "\"timestamp\":" + String(time(nullptr)) + ",";
     payload += "\"source_id\":\"esp32-001\"";
     payload += "}]}";
 
@@ -469,10 +476,39 @@ class MySensor(BaseSensor):
 | 404    | Resource not found              |
 | 410    | Resource expired                |
 
+## Clock correction
+
+Embedded devices commonly boot with a wrong system clock — no hardware RTC, NTP unreachable on first boot, or a fresh OS image whose filesystem timestamp is months in the past. Without correction, all telemetry lands at the wrong place on the timeline.
+
+The Python SDK corrects for this automatically over WebSocket. On every connection the gateway returns `server_time_ms` in the `authenticated` frame. The SDK computes `offset = server_time - device_time` and adds it to every timestamp it generates. Data lands at the right time on the dashboard regardless of what the device clock says.
+
+**When the correction applies:**
+
+The offset is applied when `timestamp` is omitted (the SDK generates the time). If you pass an explicit `timestamp`, it is used as-is — the SDK cannot tell whether your value is a wall-clock time or a hardware-relative counter, so it leaves it alone.
+
+```python
+px.send("temperature", 72.5)                    # SDK picks time → correction applied
+px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is, no correction
+```
+
+**When to pass an explicit timestamp:**
+- You have a reliable wall-clock source (GPS, trusted hardware RTC, host NTP)
+- You are replaying or backfilling historical data
+- Your sensor provides its own wall-clock timestamp
+
+**When to omit timestamp:**
+- The device may have booted without NTP (Raspberry Pi, Jetson, field robots without network on first boot)
+- You have no reliable external time source
+
+**Known limitations:**
+- The clock offset refreshes only on WebSocket reconnect. A device with a drifting RTC that stays connected for many days will accumulate uncorrected drift between reconnects proportional to the drift rate.
+- HTTP transport (`transport="http"`) does not receive clock sync — timestamps default to the device clock uncorrected.
+- `send_batch()` takes one shared `timestamp` for the whole batch, not per-point. For per-point timestamps, call `send()` in a loop.
+
 ## Best Practices
 
 - **Batch points** - Send up to 100 points per request for HTTP
-- **Use timestamps** - Always include accurate timestamps
+- **Omit timestamp when unsure** - The Python SDK applies server-synced clock correction when `timestamp` is omitted over WebSocket; only pass an explicit timestamp when you have a reliable wall-clock source
 - **Consistent source_id** - Use the same ID for each physical device/source
 - **Use tags** - Label data for filtering (e.g., `{"location": "lab"}`)
 - **Use sessions** - Group related data for easier analysis

{plexus_python-0.4.3 → plexus_python-0.4.6}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.4.5] - 2026-04-27 - Stderr status output (re-release of 0.4.4)
+
+Same code as 0.4.4 — the 0.4.4 publish workflow failed lint on a stray
+`f`-prefix in `plexus/client.py:488`. PyPI doesn't allow re-uploading a
+version, so 0.4.5 is the corrected re-release.
+
+## [0.4.4] - 2026-04-27 - Stderr status output
+
+### Added
+
+- `[plexus] …` status lines on stderr at every meaningful state change so
+  scripts that don't configure the `logging` module still tell the user
+  what's going on. Set `PLEXUS_QUIET=1` to suppress.
+  - `✓ Connected to gateway as <source_id>` on first WS auth
+  - `✓ Reconnected as <source_id>` after a drop
+  - `✓ First N points landed (via ws|http)` on first successful send
+  - `⚠ WebSocket unavailable, falling back to POST /ingest` on WS failure
+  - `✗ Auth rejected by gateway: …` / `✗ Gateway rejected the API key (401)`
+    on auth failures, with a `plexus whoami` hint
+  - `⏸ Send failed, buffering points locally (N queued)` when offline
+  - `✓ Sending again (drained the local buffer)` on recovery
+
+### Why
+
+Users running `python my_script.py` saw nothing — by default Python's
+`logging` module emits at WARNING and above only on the console, so a
+silent SDK was indistinguishable from "everything's working" until they
+checked the dashboard. This makes the trip from `python my_script.py` to
+"first row visible in the UI" auditable in one terminal.
+
 ## [0.4.3] - 2026-04-27 - Re-release of 0.4.2 with correct __version__
 
 The 0.4.2 wheel shipped with `plexus.__version__ == "0.4.1"` because the

{plexus_python-0.4.3 → plexus_python-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.3
+Version: 0.4.6
 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.3 → plexus_python-0.4.6}/README.md

@@ -102,6 +102,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.3 → plexus_python-0.4.6}/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.3"
+__version__ = "0.4.6"
 __all__ = ["Plexus", "WebSocketTransport"]

{plexus_python-0.4.3 → plexus_python-0.4.6}/plexus/client.py

@@ -36,6 +36,8 @@ Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
 import gzip
 import json
 import logging
+import os
+import sys
 import time
 from contextlib import contextmanager
 from typing import Any, Dict, List, Optional, Tuple, Union
@@ -55,6 +57,20 @@ from plexus.config import (
 )
 logger = logging.getLogger(__name__)
 
+# Status messages to stderr so users running `python my_script.py` see what's
+# happening without having to configure logging. Set PLEXUS_QUIET=1 to disable.
+_QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
+
+
+def _say(line: str) -> None:
+    if _QUIET:
+        return
+    try:
+        sys.stderr.write(f"[plexus] {line}\n")
+        sys.stderr.flush()
+    except Exception:
+        pass
+
 # Flexible value type - supports any JSON-serializable value
 FlexValue = Union[int, float, str, bool, Dict[str, Any], List[Any]]
 
@@ -124,6 +140,7 @@ class Plexus:
         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:
@@ -133,6 +150,12 @@ class Plexus:
         else:
             self._buffer: BufferBackend = MemoryBuffer(max_size=max_buffer_size)
 
+        # State that drives the [plexus] stderr status line.
+        self._announced_first_send = False
+        self._announced_http_fallback = False
+        self._announced_buffering = False
+        self._send_count = 0
+
     @property
     def max_buffer_size(self):
         return self._max_buffer_size
@@ -153,17 +176,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)
@@ -236,6 +258,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]],
@@ -261,8 +307,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):
@@ -278,10 +324,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
@@ -344,8 +394,14 @@ class Plexus:
                 ws.wait_authenticated(timeout=min(self.timeout, 5.0))
             if ws.send_points(all_points):
                 self._clear_buffer()
+                self._note_send(len(all_points), via="ws")
                 return True
             # Socket unavailable → fall through to HTTP.
+            if not self._announced_http_fallback:
+                _say(
+                    f"⚠ WebSocket unavailable, falling back to POST {self.gateway_url}/ingest"
+                )
+                self._announced_http_fallback = True
 
         url = f"{self.gateway_url}/ingest"
         last_error: Optional[Exception] = None
@@ -372,8 +428,11 @@ class Plexus:
 
                 # Auth errors - don't retry, raise immediately
                 if response.status_code == 401:
+                    _say("✗ Gateway rejected the API key (401).")
+                    _say("  Run `plexus whoami` to confirm what's on disk.")
                     raise AuthenticationError("Invalid API key")
                 elif response.status_code == 403:
+                    _say("✗ API key lacks write scope (403).")
                     raise AuthenticationError("API key doesn't have write permissions")
 
                 # Bad request errors - don't retry (client error)
@@ -403,6 +462,7 @@ class Plexus:
                 # Success - clear the buffer and return
                 elif response.status_code < 400:
                     self._clear_buffer()
+                    self._note_send(len(all_points), via="http")
                     return True
 
                 # Other 4xx errors - don't retry
@@ -427,11 +487,35 @@ class Plexus:
 
         # All retries failed - buffer the points for later
         self._add_to_buffer(points)
+        if not self._announced_buffering:
+            _say(
+                f"⏸ Send failed, buffering points locally ({self.buffer_size()} queued). "
+                f"Will retry on next call."
+            )
+            self._announced_buffering = True
 
         if last_error:
             raise last_error
         raise PlexusError("Send failed after all retries")
 
+    def _note_send(self, count: int, via: str) -> None:
+        """Bookkeeping so the user sees the moment data starts flowing.
+
+        First successful send → "✓ First N points landed (via WS/HTTP)".
+        Recovery from a buffering state → "✓ Sending again (was buffered)".
+        Otherwise silent — every-send chatter would be unbearable at 100 Hz.
+        """
+        self._send_count += count
+        if not self._announced_first_send:
+            _say(
+                f"✓ First {count} point{'s' if count != 1 else ''} landed "
+                f"(via {via}). source_id={self.source_id!r}"
+            )
+            self._announced_first_send = True
+        elif self._announced_buffering:
+            _say("✓ Sending again (drained the local buffer).")
+            self._announced_buffering = False
+
     def _add_to_buffer(self, points: List[Dict[str, Any]]) -> None:
         """Add points to the local buffer for later retry."""
         self._buffer.add(points)
@@ -499,7 +583,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,
             )
@@ -517,7 +601,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_python-0.4.3 → plexus_python-0.4.6}/plexus/ws.py

@@ -25,9 +25,12 @@ 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
 import random
+import sys
 import threading
 import time
 from dataclasses import dataclass, field
@@ -43,6 +46,23 @@ except ImportError as e:  # pragma: no cover - import-time failure is obvious
 
 logger = logging.getLogger(__name__)
 
+# By default, print connection status to stderr so users running
+# `python my_script.py` can see what's happening without having to
+# configure the logging module. Set PLEXUS_QUIET=1 to disable.
+_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:
+        # Stderr blew up — don't take the whole client down with it.
+        pass
+
 AUTH_TIMEOUT_S = 10.0
 HEARTBEAT_INTERVAL_S = 30.0
 BACKOFF_BASE_S = 1.0
@@ -89,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")
@@ -103,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
@@ -111,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
 
@@ -136,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()
@@ -156,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."""
@@ -169,11 +197,22 @@ class WebSocketTransport:
     # ------------------------------------------------------------------ thread
 
     def _run(self) -> None:
+        first_attempt = True
         while not self._stop.is_set():
             try:
                 self._connect_and_serve()
             except Exception as e:
-                logger.warning("plexus ws loop error: %s", e)
+                msg = str(e)
+                logger.warning("plexus ws loop error: %s", msg)
+                # Loud the first time so users running a script see it,
+                # quieter on subsequent retries to avoid log spam.
+                if first_attempt:
+                    if "auth failed" in msg.lower() or "invalid api key" in msg.lower():
+                        _say(f"✗ Auth rejected by gateway: {msg}")
+                        _say("  Check your key — `plexus whoami` shows what's on disk.")
+                    else:
+                        _say(f"✗ Connection failed: {msg}")
+                        _say("  SDK will keep retrying with backoff.")
             finally:
                 self._authenticated.clear()
                 with self._ws_lock:
@@ -185,6 +224,7 @@ class WebSocketTransport:
             delay = _backoff_delay(self._backoff_attempt)
             self._backoff_attempt = min(self._backoff_attempt + 1, 10)
             logger.info("plexus ws reconnect in %.1fs", delay)
+            first_attempt = False
             if self._stop.wait(timeout=delay):
                 break
 
@@ -219,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.
@@ -235,9 +284,15 @@ class WebSocketTransport:
                 except Exception as e:  # pragma: no cover - callback errors must not break auth
                     logger.debug("on_source_id_assigned callback raised: %s", e)
 
+        was_reconnect = self._backoff_attempt > 0
         self._authenticated.set()
         self._backoff_attempt = 0
         logger.info("plexus ws authenticated as %s", self.source_id)
+        if was_reconnect:
+            _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.3 → plexus_python-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.4.3"
+version = "0.4.6"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"

{plexus_python-0.4.3 → plexus_python-0.4.6}/tests/test_basic.py

@@ -1,5 +1,7 @@
 """Basic tests for plexus-python."""
 
+import time
+
 from plexus import __version__
 from plexus.client import Plexus
 from plexus.config import DEFAULT_CONFIG
@@ -41,3 +43,19 @@ def test_make_point_with_tags():
     point = px._make_point("temperature", 72.5, tags={"sensor": "A1"})
 
     assert point["tags"] == {"sensor": "A1"}
+
+
+def test_normalize_ts_ms_applies_clock_offset():
+    px = Plexus(api_key="test", endpoint="http://localhost")
+    px._clock_offset_ms = 5000
+    before = int(time.time() * 1000)
+    ts = px._normalize_ts_ms(None)
+    after = int(time.time() * 1000)
+    assert before + 5000 <= ts <= after + 5000
+
+
+def test_normalize_ts_ms_ignores_offset_for_supplied_timestamp():
+    px = Plexus(api_key="test", endpoint="http://localhost")
+    px._clock_offset_ms = 5000
+    ts = px._normalize_ts_ms(1_700_000_000.0)
+    assert ts == 1_700_000_000_000

{plexus_python-0.4.3 → plexus_python-0.4.6}/tests/test_ws.py

@@ -61,6 +61,7 @@ class _StubGateway:
         await ws.send(json.dumps({
             "type": "authenticated",
             "source_id": returned_source_id,
+            "server_time_ms": int(time.time() * 1000),
         }))
         try:
             async for raw in ws:
@@ -332,3 +333,48 @@ def test_ensure_device_path():
     assert _ensure_device_path("wss://foo") == "wss://foo/ws/device"
     assert _ensure_device_path("wss://foo/") == "wss://foo/ws/device"
     assert _ensure_device_path("wss://foo/ws/device") == "wss://foo/ws/device"
+
+
+def test_clock_offset_computed_from_authenticated_frame():
+    # Stub sends a server_time_ms that is 30 seconds ahead of real time.
+    # The transport's clock_offset_ms should be close to +30_000.
+    fake_offset_ms = 30_000
+
+    class _OffsetStubGateway(_StubGateway):
+        async def _handler(self, ws, path="/ws/device"):
+            self._ws = ws
+            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": returned_source_id,
+                "server_time_ms": int(time.time() * 1000) + fake_offset_ms,
+            }))
+            try:
+                async for raw in ws:
+                    self.received.append(json.loads(raw))
+            except websockets.ConnectionClosed:
+                return
+
+    g = _OffsetStubGateway()
+    g.start()
+    try:
+        seen: List[int] = []
+        t = WebSocketTransport(
+            api_key="plx_test_abc",
+            source_id="drone-001",
+            ws_url=_url(g.port),
+            on_clock_synced=lambda offset: seen.append(offset),
+        )
+        t.start()
+        try:
+            assert t.wait_authenticated(timeout=3)
+            assert abs(t.clock_offset_ms - fake_offset_ms) < 500
+            assert len(seen) == 1
+            assert abs(seen[0] - fake_offset_ms) < 500
+        finally:
+            t.stop()
+    finally:
+        g.stop()