plexus-python 0.4.5__tar.gz → 0.4.7__tar.gz

{plexus_python-0.4.5 → plexus_python-0.4.7}/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.5 → plexus_python-0.4.7}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.4.7] - 2026-05-14 - Video streaming API
+
+### Added
+
+- `Plexus.send_video_frame(frame, camera_id, quality, timestamp)` — high-level
+  API for streaming camera frames. Accepts a numpy array (e.g. from
+  `cv2.VideoCapture.read()`), handles JPEG encoding, base64, dimensions, and
+  auth wait internally. Requires `transport="ws"` and `opencv-python`.
+
+### Changed
+
+- Gateway WebSocket URL (`wss://plexus-gateway.fly.dev`) is now the SDK
+  default — no need to pass `ws_url` explicitly.
+- Removed the `[plexus]   endpoint: …` line from the connection printout.
+
+### Performance
+
+- Eliminated per-frame `buf.tobytes()` copy in `send_video_frame` by passing
+  the numpy buffer directly to `base64.b64encode` (buffer protocol).
+- `base64` imported at module level; `cv2` imported once on first call and
+  cached, removing repeated import overhead from the hot path.
+
 ## [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

{plexus_python-0.4.5 → plexus_python-0.4.7}/PKG-INFO

@@ -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.5 → plexus_python-0.4.7}/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.7/examples/.python-version

@@ -0,0 +1 @@
+3.12

{plexus_python-0.4.5 → plexus_python-0.4.7}/examples/README.md

@@ -9,5 +9,6 @@ Each script is standalone — copy into your project, adjust the `source_id`, an
 | `can.py` | Vehicle CAN bus (with optional DBC decode) | `python-can`, `cantools` |
 | `mqtt.py` | MQTT broker → Plexus bridge | `paho-mqtt` |
 | `i2c_bme280.py` | Raspberry Pi environmental sensor | `adafruit-circuitpython-bme280` |
+| `mac_metrics.py` | Mac system metrics + spike/pressure events | `psutil` |
 
 The pattern is always the same: use whatever library you'd use anyway, then call `px.send(metric, value)`. Plexus stays out of your decode path.

plexus_python-0.4.7/examples/mac_metrics.py

@@ -0,0 +1,81 @@
+"""
+Mac system metrics with structured event logs.
+
+Install deps:
+    pip install plexus-python psutil
+
+Run:
+    python examples/mac_metrics.py --api-key plx_xxx
+    python examples/mac_metrics.py --api-key plx_xxx --interval 10
+"""
+
+import argparse
+import time
+import psutil
+from plexus import Plexus
+
+parser = argparse.ArgumentParser(description="Stream Mac system metrics to Plexus.")
+parser.add_argument("--api-key", required=True, help="Plexus API key (plx_xxx)")
+parser.add_argument("--interval", type=float, default=5.0, metavar="SECONDS",
+                    help="Sampling interval in seconds (default: 5)")
+parser.add_argument("--source-id", default="macbook", help="Device source ID (default: macbook)")
+args = parser.parse_args()
+
+px = Plexus(api_key=args.api_key, source_id=args.source_id)
+
+CPU_SPIKE_THRESHOLD = 80.0   # %
+MEM_PRESSURE_THRESHOLD = 85.0  # %
+
+prev_net = psutil.net_io_counters()
+prev_disk = psutil.disk_io_counters()
+prev_charging = None
+
+while True:
+    net = psutil.net_io_counters()
+    disk = psutil.disk_io_counters()
+
+    cpu = psutil.cpu_percent(interval=None)
+    mem = psutil.virtual_memory()
+
+    # Numeric metrics
+    px.send("cpu.percent",     cpu)
+    px.send("memory.used_gb",  mem.used / 1e9)
+    px.send("memory.percent",  mem.percent)
+    px.send("net.rx_mbps",     (net.bytes_recv  - prev_net.bytes_recv)   / 1e6)
+    px.send("net.tx_mbps",     (net.bytes_sent  - prev_net.bytes_sent)   / 1e6)
+    px.send("disk.read_mbps",  (disk.read_bytes  - prev_disk.read_bytes)  / 1e6)
+    px.send("disk.write_mbps", (disk.write_bytes - prev_disk.write_bytes) / 1e6)
+    px.send("disk.free_gb",    psutil.disk_usage("/").free / 1e9)
+
+    # Battery metrics + charge-state change event
+    battery = psutil.sensors_battery()
+    if battery:
+        px.send("battery.percent", battery.percent)
+        charging = battery.power_plugged
+        if charging != prev_charging and prev_charging is not None:
+            px.event("battery.state_change", {
+                "charging": charging,
+                "percent": battery.percent,
+            })
+        prev_charging = charging
+
+    # CPU spike event — fires once per interval when threshold is crossed
+    if cpu >= CPU_SPIKE_THRESHOLD:
+        top = max(psutil.process_iter(["name", "cpu_percent"]), key=lambda p: p.info["cpu_percent"] or 0)
+        px.event("cpu.spike", {
+            "cpu_percent": cpu,
+            "top_process": top.info["name"],
+            "top_process_percent": top.info["cpu_percent"],
+        })
+
+    # Memory pressure event
+    if mem.percent >= MEM_PRESSURE_THRESHOLD:
+        top = max(psutil.process_iter(["name", "memory_percent"]), key=lambda p: p.info["memory_percent"] or 0)
+        px.event("memory.pressure", {
+            "memory_percent": mem.percent,
+            "top_process": top.info["name"],
+            "top_process_percent": round(top.info["memory_percent"], 1),
+        })
+
+    prev_net, prev_disk = net, disk
+    time.sleep(args.interval)

{plexus_python-0.4.5 → plexus_python-0.4.7}/examples/mqtt.py

@@ -41,7 +41,7 @@ def on_message(_client, _userdata, msg):
         px.send(name, data)
 
 
-client = mqtt.Client()
+client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION1)
 client.on_message = on_message
 client.connect(broker)
 client.subscribe(topic)

plexus_python-0.4.7/examples/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "examples"
+version = "0.1.0"
+description = "Standalone example scripts for plexus-python"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "adafruit-circuitpython-bme280>=2.6.32",
+    "cantools>=41.3.1",
+    "paho-mqtt>=2.1.0",
+    "plexus-python>=0.4.6",
+    "psutil>=7.2.2",
+    "pymavlink>=2.4.49",
+    "python-can>=4.6.1",
+]