plexus-python 0.11.4__tar.gz → 0.11.6__tar.gz

{plexus_python-0.11.4 → plexus_python-0.11.6}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,9 +6,9 @@ body:
   - type: input
     id: agent-version
     attributes:
-      label: Agent Version
+      label: SDK Version
       description: Output of `plexus --version` or version in pyproject.toml
-      placeholder: "0.9.6"
+      placeholder: "0.11.5"
     validations:
       required: true
 
@@ -57,8 +57,8 @@ body:
     id: extras
     attributes:
       label: Installed Extras
-      description: Which optional extras are installed? (e.g., sensors, can, mavlink, camera)
-      placeholder: "pip install plexus-python[sensors,can]"
+      description: Which optional extras are installed? The only one is `video`.
+      placeholder: "pip install plexus-python[video]"
 
   - type: textarea
     id: logs

{plexus_python-0.11.4 → plexus_python-0.11.6}/AGENTS.md

@@ -24,7 +24,8 @@ plexus whoami                          # Show the local credential summary
 
 `plexus init` opens a browser to `app.plexus.company/auth/cli`, waits for the callback, and
 persists the issued key to `~/.plexus/config.json`. Alternatively, set `PLEXUS_API_KEY` (or pass
-`api_key=` to `Plexus()`) instead of running `init`; get a key at app.plexus.company/api.
+`api_key=` to `Plexus()`) instead of running `init`; get a key at app.plexus.company/api. The optional
+"Limit to device slug" field there binds a key to one `source_id`; use it for devices in customer hands.
 
 ## Exit Codes
 
@@ -43,14 +44,22 @@ px = Plexus(api_key="plx_xxxxx", source_id="device-001")
 px.send("temperature", 72.5)
 px.send("pressure", 1013.25, tags={"unit": "hPa"})
 
-# Batch
+# One message for a list of readings
 px.send_batch([
     ("temperature", 72.5),
     ("pressure", 1013.25),
 ])
 
-# Persistent buffering for reliability
-px = Plexus(api_key="plx_xxxxx", persistent_buffer=True)
+# send() is one message per call and does not batch. Above a few readings
+# a second, let a background thread group them:
+with px.batch(interval_ms=50) as b:
+    b.send("temperature", 72.5)
+
+# Events (faults, state changes, log lines). No log upload, no logging.Handler.
+px.event("log", {"level": "error", "msg": "IMU read timed out"})
+
+# The on-disk (SQLite) buffer is on by default; this keeps it in memory only
+px = Plexus(api_key="plx_xxxxx", persistent_buffer=False)
 ```
 
 ## Key Conventions
@@ -58,5 +67,5 @@ px = Plexus(api_key="plx_xxxxx", persistent_buffer=True)
 - Config lives in `~/.plexus/config.json`
 - API keys are prefixed with `plx_`
 - Source IDs (device slugs) namespace metrics
-- HTTP ingest → `POST /ingest` on gateway; WebSocket → `/ws/device` for streaming + commands
+- HTTP ingest → `POST /ingest` on gateway; WebSocket → `/ws/device` for streaming (paid plans; the SDK falls back to HTTP on Free)
 - Gateway resolves `org_id` server-side from the API key — clients do not supply it

{plexus_python-0.11.4 → plexus_python-0.11.6}/API.md

@@ -9,7 +9,13 @@ Send telemetry data to Plexus using HTTP or WebSocket.
 | Method    | Use Case                                        |
 | --------- | ----------------------------------------------- |
 | HTTP POST | Simple scripts, batch uploads, embedded devices |
-| WebSocket | Real-time streaming, UI-controlled devices      |
+| WebSocket | Real-time streaming and video (paid plans)      |
+
+The Python SDK picks for you: it tries the WebSocket and falls back to HTTP on
+its own. On the Free plan the gateway refuses the device WebSocket
+(`streaming_requires_plan`), so the SDK sends everything over HTTP and
+telemetry and events still land. Live streaming and video need a paid plan.
+Free also allows up to 3 devices and 7 days of history.
 
 ## Quick Start
 
@@ -18,12 +24,12 @@ Send telemetry data to Plexus using HTTP or WebSocket.
 Set up your device with one command using an API key:
 
 ```bash
-# With API key (fleet provisioning — get from Settings → Developer)
+# With an API key (get one at app.plexus.company/api)
 curl -sL https://app.plexus.company/setup | bash -s -- --key plx_your_api_key
 
 ```
 
-Then control streaming, recording, and configuration from [app.plexus.company/devices](https://app.plexus.company/devices).
+Then find the device at [app.plexus.company/devices](https://app.plexus.company/devices).
 
 ### Option 2: Direct HTTP
 
@@ -63,9 +69,16 @@ Plexus uses API keys for all authentication:
 **Option B: Manual creation**
 
 1. Sign up at [app.plexus.company](https://app.plexus.company)
-2. Go to Settings → Developer
+2. Go to [app.plexus.company/api](https://app.plexus.company/api)
 3. Create an API key (starts with `plx_`)
 
+**Limit to device slug** (optional, on the same form) binds the key to one
+`source_id`. The gateway then refuses it for any other source: `403` on
+`/ingest`, and a `source_not_allowed` error on the WebSocket. Use a bound key
+on every device you put in a customer's hands, so a key pulled off one unit
+cannot write as the rest of your fleet. Leave it empty for a fleet key that can
+write as any source in your org.
+
 ## HTTP API
 
 ### Authentication
@@ -97,6 +110,7 @@ x-api-key: plx_xxxxx
 
 | Field        | Type   | Required | Description                                                                                                                                                                                             |
 | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`      | string | WS only  | `"metric"` (numeric value) or `"event"` (anything else). Set it explicitly. Over HTTP a missing `class` is inferred from the value; over WebSocket it is required.                                        |
 | `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`)                                                                                                                                                          |
 | `value`      | any    | Yes      | See supported value types below                                                                                                                                                                         |
 | `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). |
@@ -113,6 +127,27 @@ x-api-key: plx_xxxxx
 | object  | `{"x": 1.2, "y": 3.4, "z": 5.6}` | Vector data, structured readings |
 | array   | `[1.0, 2.0, 3.0, 4.0]`           | Waveforms, multiple values       |
 
+### Events and logs
+
+Things that happen, rather than things you measure, are `class: "event"`
+points: faults, state changes, operator actions, log lines. The Python SDK
+sends them with `px.event(name, data)`.
+
+Limits per event point: a string value up to 256 bytes, an object or array
+value up to 4,096 bytes of JSON, and up to 16 tags. The gateway rejects larger
+points with a 400.
+
+There is no log-file upload and no `logging.Handler`. Forward the log lines
+that matter as events:
+
+```python
+px.event("log", {"level": "error", "msg": "IMU read timed out"})
+```
+
+Send errors, warnings and state changes, not every debug line: each call is
+one message, and the gateway limits messages (see
+[Rate limits and batching](#rate-limits-and-batching)).
+
 ### Runs
 
 A **run** is a named time window on a source — a hot-fire, a bench sequence, a
@@ -158,14 +193,21 @@ To group data without a window, plain `tags` on each point still work.
 
 ## WebSocket API
 
-For real-time UI-controlled streaming, devices connect via WebSocket.
+For real-time streaming and video, devices connect via WebSocket. This needs a
+paid plan: on Free, the gateway answers `device_auth` with an error frame
+(`"code": "streaming_requires_plan"`) and closes. Send over HTTP instead; the
+Python SDK does this for you.
+
+Video frames go over this socket. They are relayed live to anyone watching and
+stored only when someone presses **Record** in the app, for up to 4 hours per
+recording.
 
 ### Connection Flow
 
 1. Device connects to the gateway
 2. Device authenticates with API key (and advertises any registered commands)
 3. Device streams `telemetry` frames
-4. Dashboard/API invokes registered commands via `typed_command`
+4. Plexus invokes registered commands via `typed_command` (see the note under Commands)
 
 ### Device Authentication
 
@@ -227,7 +269,9 @@ Devices authenticate using an API key. The gateway echoes the declared `source_i
 
 ### Commands
 
-Dashboard/API actions reach the device as a single `typed_command` envelope; the device replies with `command_result` frames. Register handlers with `px.on_command(...)` before the first `send()`.
+Commands reach the device as a single `typed_command` envelope; the device replies with `command_result` frames. Register handlers with `px.on_command(...)` before the first `send()`.
+
+> **Note:** the public API route for sending commands (`POST /v1/sources/{id}/commands`) was turned off on 2026-09-21 and returns `410 Gone`. Nothing in Plexus can currently trigger a custom handler.
 
 ```json
 // Server → Device
@@ -275,6 +319,7 @@ await fetch("https://gateway.plexus.company/ingest", {
   body: JSON.stringify({
     points: [
       {
+        class: "metric",
         metric: "temperature",
         value: 72.5,
         timestamp: Date.now() / 1000,
@@ -333,6 +378,7 @@ void sendToPlexus(const char* metric, float value) {
     http.addHeader("x-api-key", "plx_xxxxx");
 
     String payload = "{\"points\":[{";
+    payload += "\"class\":\"metric\",";
     payload += "\"metric\":\"" + String(metric) + "\",";
     payload += "\"value\":" + String(value) + ",";
     payload += "\"timestamp\":" + String(time(nullptr)) + ",";
@@ -356,6 +402,7 @@ curl -X POST https://gateway.plexus.company/ingest \
   -H "Content-Type: application/json" \
   -d "{
     \"points\": [{
+      \"class\": \"metric\",
       \"metric\": \"temperature\",
       \"value\": 72.5,
       \"timestamp\": $(date +%s),
@@ -406,25 +453,25 @@ while True:
 | 200    | Success                         |
 | 400    | Bad request (check JSON format) |
 | 401    | Invalid or missing API key      |
-| 403    | API key lacks permissions       |
+| 403    | API key lacks permissions, or is limited to another device |
 | 404    | Resource not found              |
 | 410    | Resource expired                |
 
 ## Rate limits and batching
 
 The gateway meters **messages**, not points. One `px.send()` call is one
-message, whatever it carries:
+message, whatever it carries. `send()` does not batch:
 
 | Limit                              | Value            |
 | ---------------------------------- | ---------------- |
-| Telemetry messages per WS connection | 500/s sustained, 2000 burst |
-| Hard ceiling per source (WS + HTTP) | 2000 messages/s  |
+| Telemetry messages per WS connection | 2,000/s          |
+| Hard ceiling per source (WS + HTTP) | 2,000 messages/s, bursts up to 500 |
 | Points per message                 | 10,000           |
 | Message size                       | 1 MB             |
 
 Because the ceiling counts messages, the shape of your sends decides whether
-you hit it. Eight channels at 100 Hz sent one at a time is 800 messages/s —
-over the limit. The same 800 readings/s batched every 100 ms is 10 messages/s,
+you hit it. 25 channels at 100 Hz sent one at a time is 2,500 messages/s —
+over the limit. The same 2,500 readings/s batched every 100 ms is 10 messages/s,
 and the batches are also several times cheaper to store.
 
 **Over the limit, the gateway discards the whole message.** It replies with a
@@ -493,4 +540,4 @@ px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is
 - **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 and grouping (e.g., `{"location": "lab"}`)
-- **Prefer WebSocket** - For real-time UI-controlled devices, the SDK connects over WebSocket by default
+- **Let the SDK pick the transport** - It uses the WebSocket when your plan allows it and falls back to HTTP otherwise

{plexus_python-0.11.4 → plexus_python-0.11.6}/CHANGELOG.md

@@ -1,6 +1,90 @@
 # Changelog
 
-## [Unreleased]
+## [0.11.6] - 2026-09-22 - Docs and skills catch up
+
+Docs and agent skills caught up with the platform. The only code change is
+one error message. The skills ship inside the wheel, so this release is how
+they reach users.
+
+### Fixed
+
+- **The 0.11.4 entry below overstated the `class` bug.** It said raw-HTTP
+  examples without `class` return 400. They don't: `POST /ingest` infers a
+  missing `class` (numbers become metrics, everything else events). The
+  WebSocket is the path that requires it, and `"class": "metric"` on a
+  non-number is still a 400. The skills and `API.md` now say that, and still
+  tell raw-HTTP senders to set `class` explicitly. The JavaScript, Arduino
+  and Bash examples in `API.md` now set it too.
+
+- **Where to get an API key.** The README said "Devices → Add Device" and
+  `API.md` said "Settings → Developer". Keys are made at
+  `app.plexus.company/api`, and the "no API key" error now says so instead
+  of pointing at `/devices`.
+
+- **The README said `setup.sh` refuses to run without `--name`.** It
+  doesn't. Without a name the SDK makes up a random `source-xxxxxxxx` id.
+  The README now says to pass `--name` and what happens if you don't.
+
+- **The README said to "enable" the SQLite buffer.** It is on by default.
+  The example now shows how to turn it off.
+
+- **The firmware skill said `px.send()` is "batched for you".** It is one
+  message per call. Only `px.batch()` batches.
+
+- **The bug-report template asked which of `sensors`, `can`, `mavlink` and
+  `camera` you had installed.** None of those extras exist. The only one is
+  `video`.
+
+### Changed
+
+- **The read API host in the skills is `https://api.plexus.company`**, not
+  the raw Fly hostname. `scripts/verify_skills.py` checks it by default, and
+  a test keeps the old hostname out of the skills.
+
+- **Documented "Limit to device slug".** A key made with it can only send as
+  that one `source_id`. The docs recommend one for every device in a
+  customer's hands.
+
+- **Documented the Free plan's limits.** The gateway refuses the device
+  WebSocket on Free (`streaming_requires_plan`); the SDK falls back to HTTP,
+  so telemetry and events still land. Live streaming and video need a paid
+  plan. Free allows 3 devices and 7 days of history.
+
+- **Documented how video is kept.** Frames are relayed live, and stored only
+  when someone presses Record in the app, up to 4 hours per recording.
+
+- **Documented logs.** There is no log upload and no `logging.Handler`.
+  Forward the lines that matter with `px.event("log", {...})`. Event limits
+  are now written down: 256 bytes for a string value, 4,096 bytes of JSON
+  for an object or array, 16 tags.
+
+- **`scripts/setup.sh` re-synced with the script `/setup` serves.** The old
+  copy still installed `[sensors]` and `[picamera]` extras that were removed
+  in 0.2.0. It also links `github.com/plexus-oss/plexus-python` and
+  `app.plexus.company/api` now.
+
+- **The skills read device events from `/v1/sources/{id}/events`.** It is
+  live on the data API as of 2026-09-22. `/logs` still works as an alias.
+
+- **Rate limits quote the gateway's current ceiling**: 2,000 messages/s per
+  connection and per source, not the old 500/s.
+
+## [0.11.5] - 2026-09-21 - The commands API is off
+
+No code changes. The docs described a way to send commands to a device that
+no longer exists.
+
+### Changed
+
+- **`POST /v1/sources/{id}/commands` is turned off, and the docs now say so.**
+  Plexus turned the endpoint off on 2026-09-21. It returns `410 Gone`.
+  Any API key of any scope could send any command name to any device in
+  the org, which is not safe for commands that reach hardware.
+  - The agent skill no longer offers to send commands, and it tells agents
+    not to call the endpoint.
+  - README and `API.md` say plainly that nothing in Plexus can currently
+    trigger an `on_command` handler.
+  - `on_command` itself is unchanged.
 
 ## [0.11.4] - 2026-09-08 - Docs that actually work
 

{plexus_python-0.11.4 → plexus_python-0.11.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.4
+Version: 0.11.6
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company
@@ -55,7 +55,9 @@ px = Plexus(api_key="plx_xxx", source_id="device-001")
 px.send("temperature", 72.5)
 ```
 
-Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
+Get an API key at [app.plexus.company/api](https://app.plexus.company/api), or run `plexus init` to authorize the machine in a browser.
+
+When you create a key there, you can fill in **Limit to device slug**. That key can then only send as that one `source_id`; the gateway refuses it for any other. Use one of these for every device you put in a customer's hands, so a key pulled off one unit cannot write as the rest of your fleet.
 
 ## Device identity
 
@@ -66,7 +68,7 @@ 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._-]*$` (max 256 chars). `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`.
+The name is turned into the device's `source_id`, which must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars). Pass `--name` every time. Without it, and without `source_id=...` in code, the SDK makes up a random id like `source-1a2b3c4d` on first run and saves it to `~/.plexus/config.json`. Don't use the hostname: cloned SD-card images all boot as `raspberrypi`, and their telemetry merges into one source.
 
 **Names are not auto-deduplicated.** The gateway echoes back whatever `source_id` you declare, unchanged — pick a unique name per device (that's what `--name` and `source_id=...` are for). Two devices that declare the same name write into the same source.
 
@@ -115,7 +117,7 @@ px.send_batch([
 
 ### `batch()` — coalesce a fast stream of readings
 
-Use this above a few readings per second. Every `send()` is one WebSocket message, and the gateway limits **messages**, not points — 500/s on a connection. Eight channels at 100 Hz sent one at a time is 800 messages/s, and the overflow is discarded before it is stored.
+Use this above a few readings per second. Every `send()` is one WebSocket message, and the gateway limits **messages**, not points — 2,000/s on a connection. 25 channels at 100 Hz sent one at a time is 2,500 messages/s, and the overflow is discarded before it is stored.
 
 ```python
 with px.batch(interval_ms=50) as b:
@@ -154,10 +156,24 @@ px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
 
 The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
 
+Limits per event: a string value up to 256 bytes, a dict or list value up to 4,096 bytes of JSON, and up to 16 tags. The gateway rejects anything larger.
+
+### Logs
+
+There is no log-file upload and no `logging.Handler` in this package. To get important log lines into Plexus, send them as events:
+
+```python
+px.event("log", {"level": "error", "msg": "IMU read timed out"})
+```
+
+Forward the lines you would want on the timeline next to your telemetry (errors, warnings, state changes), not every debug line. Each call is one message, and the gateway limits messages (see [`batch()`](#batch--coalesce-a-fast-stream-of-readings)).
+
 ## Video streaming
 
 Two methods depending on whether you control the capture loop or just have a URL.
 
+Video needs a paid plan: frames go over the WebSocket, which the gateway refuses on the Free plan. Frames are relayed live to anyone watching. They are stored only when someone presses **Record** in the app, for up to 4 hours per recording.
+
 ### `send_video_frame(frame, camera_id)` — send frames you capture yourself
 
 Use this when your code owns the capture loop — a `picamera2` callback, an OpenCV `VideoCapture` loop, or an FFmpeg pipe you manage. Pass each frame and the SDK ships it to Plexus over WebSocket.
@@ -219,10 +235,10 @@ See [`examples/`](examples/) for runnable versions of each.
 
 ## Reliability
 
-Every send buffers locally before hitting the network, retries with exponential backoff, and keeps your data safe across outages. Enable SQLite persistence to survive restarts and power loss:
+Every send buffers locally before hitting the network, retries with exponential backoff, and keeps your data safe across outages. The buffer is on disk (SQLite) by default, so it survives restarts and power loss. To keep it in memory only:
 
 ```python
-px = Plexus(persistent_buffer=True)
+px = Plexus(persistent_buffer=False)
 ```
 
 Point counts and flush:
@@ -255,7 +271,7 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — the gateway's device wire protocol. This gives you:
 
 - lower-latency streaming of telemetry,
-- live command delivery from the UI / API to the device.
+- the channel that will carry actions triggered from a Plexus dashboard.
 
 If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
 
@@ -266,6 +282,10 @@ px = Plexus()
 
 There is no transport selector: the SDK always prefers the WebSocket and falls back to `POST /ingest` on its own when the socket is unavailable.
 
+Either way, plain `px.send()` is one message per call; it does not batch. `px.send_batch()` sends one list as one message, and `px.batch()` groups a fast stream for you in the background.
+
+**On the Free plan** the gateway refuses the device WebSocket (`streaming_requires_plan`). The SDK falls back to HTTP by itself, so `send()`, `send_batch()`, `batch()` and `event()` all still work. Live streaming and video need a paid plan. Free also caps you at 3 devices and 7 days of history.
+
 ### Handling commands
 
 Register a handler before the first `send()` so the command is advertised in the auth frame:
@@ -283,6 +303,8 @@ px.send("temperature", 72.5)   # opens the socket, waits for auth
 
 The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
 
+> **Note:** nothing in Plexus can currently trigger a custom handler. The API route for sending commands was turned off on 2026-09-21. Triggering handlers from a dashboard, with permissions and a record of every run, is being rebuilt.
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
@@ -308,7 +330,7 @@ credentials. See [skills/README.md](skills/README.md).
 ## Architecture
 
 ```
-Your code ── px.send() ── HTTP POST /ingest ──> plexus-gateway ──> ClickHouse + Dashboard
+Your code ── px.send() ── WebSocket /ws/device (or HTTP POST /ingest) ──> plexus-gateway ──> ClickHouse + Dashboard
 ```
 
 One thin path. No agent, no daemon, no adapters. If you want the full HardwareOps platform — dashboards, alerts, RCA, fleet views — that's the web UI at app.plexus.company. This package gets your data there.

{plexus_python-0.11.4 → plexus_python-0.11.6}/README.md

@@ -18,7 +18,9 @@ px = Plexus(api_key="plx_xxx", source_id="device-001")
 px.send("temperature", 72.5)
 ```
 
-Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
+Get an API key at [app.plexus.company/api](https://app.plexus.company/api), or run `plexus init` to authorize the machine in a browser.
+
+When you create a key there, you can fill in **Limit to device slug**. That key can then only send as that one `source_id`; the gateway refuses it for any other. Use one of these for every device you put in a customer's hands, so a key pulled off one unit cannot write as the rest of your fleet.
 
 ## Device identity
 
@@ -29,7 +31,7 @@ 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._-]*$` (max 256 chars). `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`.
+The name is turned into the device's `source_id`, which must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars). Pass `--name` every time. Without it, and without `source_id=...` in code, the SDK makes up a random id like `source-1a2b3c4d` on first run and saves it to `~/.plexus/config.json`. Don't use the hostname: cloned SD-card images all boot as `raspberrypi`, and their telemetry merges into one source.
 
 **Names are not auto-deduplicated.** The gateway echoes back whatever `source_id` you declare, unchanged — pick a unique name per device (that's what `--name` and `source_id=...` are for). Two devices that declare the same name write into the same source.
 
@@ -78,7 +80,7 @@ px.send_batch([
 
 ### `batch()` — coalesce a fast stream of readings
 
-Use this above a few readings per second. Every `send()` is one WebSocket message, and the gateway limits **messages**, not points — 500/s on a connection. Eight channels at 100 Hz sent one at a time is 800 messages/s, and the overflow is discarded before it is stored.
+Use this above a few readings per second. Every `send()` is one WebSocket message, and the gateway limits **messages**, not points — 2,000/s on a connection. 25 channels at 100 Hz sent one at a time is 2,500 messages/s, and the overflow is discarded before it is stored.
 
 ```python
 with px.batch(interval_ms=50) as b:
@@ -117,10 +119,24 @@ px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
 
 The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
 
+Limits per event: a string value up to 256 bytes, a dict or list value up to 4,096 bytes of JSON, and up to 16 tags. The gateway rejects anything larger.
+
+### Logs
+
+There is no log-file upload and no `logging.Handler` in this package. To get important log lines into Plexus, send them as events:
+
+```python
+px.event("log", {"level": "error", "msg": "IMU read timed out"})
+```
+
+Forward the lines you would want on the timeline next to your telemetry (errors, warnings, state changes), not every debug line. Each call is one message, and the gateway limits messages (see [`batch()`](#batch--coalesce-a-fast-stream-of-readings)).
+
 ## Video streaming
 
 Two methods depending on whether you control the capture loop or just have a URL.
 
+Video needs a paid plan: frames go over the WebSocket, which the gateway refuses on the Free plan. Frames are relayed live to anyone watching. They are stored only when someone presses **Record** in the app, for up to 4 hours per recording.
+
 ### `send_video_frame(frame, camera_id)` — send frames you capture yourself
 
 Use this when your code owns the capture loop — a `picamera2` callback, an OpenCV `VideoCapture` loop, or an FFmpeg pipe you manage. Pass each frame and the SDK ships it to Plexus over WebSocket.
@@ -182,10 +198,10 @@ See [`examples/`](examples/) for runnable versions of each.
 
 ## Reliability
 
-Every send buffers locally before hitting the network, retries with exponential backoff, and keeps your data safe across outages. Enable SQLite persistence to survive restarts and power loss:
+Every send buffers locally before hitting the network, retries with exponential backoff, and keeps your data safe across outages. The buffer is on disk (SQLite) by default, so it survives restarts and power loss. To keep it in memory only:
 
 ```python
-px = Plexus(persistent_buffer=True)
+px = Plexus(persistent_buffer=False)
 ```
 
 Point counts and flush:
@@ -218,7 +234,7 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — the gateway's device wire protocol. This gives you:
 
 - lower-latency streaming of telemetry,
-- live command delivery from the UI / API to the device.
+- the channel that will carry actions triggered from a Plexus dashboard.
 
 If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
 
@@ -229,6 +245,10 @@ px = Plexus()
 
 There is no transport selector: the SDK always prefers the WebSocket and falls back to `POST /ingest` on its own when the socket is unavailable.
 
+Either way, plain `px.send()` is one message per call; it does not batch. `px.send_batch()` sends one list as one message, and `px.batch()` groups a fast stream for you in the background.
+
+**On the Free plan** the gateway refuses the device WebSocket (`streaming_requires_plan`). The SDK falls back to HTTP by itself, so `send()`, `send_batch()`, `batch()` and `event()` all still work. Live streaming and video need a paid plan. Free also caps you at 3 devices and 7 days of history.
+
 ### Handling commands
 
 Register a handler before the first `send()` so the command is advertised in the auth frame:
@@ -246,6 +266,8 @@ px.send("temperature", 72.5)   # opens the socket, waits for auth
 
 The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
 
+> **Note:** nothing in Plexus can currently trigger a custom handler. The API route for sending commands was turned off on 2026-09-21. Triggering handlers from a dashboard, with permissions and a record of every run, is being rebuilt.
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
@@ -271,7 +293,7 @@ credentials. See [skills/README.md](skills/README.md).
 ## Architecture
 
 ```
-Your code ── px.send() ── HTTP POST /ingest ──> plexus-gateway ──> ClickHouse + Dashboard
+Your code ── px.send() ── WebSocket /ws/device (or HTTP POST /ingest) ──> plexus-gateway ──> ClickHouse + Dashboard
 ```
 
 One thin path. No agent, no daemon, no adapters. If you want the full HardwareOps platform — dashboards, alerts, RCA, fleet views — that's the web UI at app.plexus.company. This package gets your data there.

{plexus_python-0.11.4 → plexus_python-0.11.6}/plexus/__init__.py

@@ -23,7 +23,7 @@ from plexus.client import (
 )
 from plexus.config import RetryConfig
 
-__version__ = "0.11.4"
+__version__ = "0.11.6"
 __all__ = [
     "AuthenticationError",
     "BatchSender",

{plexus_python-0.11.4 → plexus_python-0.11.6}/plexus/batching.py

@@ -2,11 +2,10 @@
 
 `px.send()` transmits immediately: every call is its own WebSocket frame. That
 is the right shape for a script sampling a sensor once a second, and the wrong
-one for a test bench. The gateway allows 500 telemetry messages per second on a
-connection and hard-drops a source above 2000/s, and both ceilings count
-*messages*, not points — so eight channels at 100 Hz is 800 frames/s and lands
-over the limit, while the same 800 readings coalesced into ten frames is not
-close to it. The dropped frames come back as `RATE_LIMITED`, after `send()` has
+one for a test bench. The gateway allows 2,000 telemetry messages per second on
+a connection and per source, and the ceiling counts *messages*, not points — so
+25 channels at 100 Hz is 2,500 frames/s and lands over the limit, while the same
+2,500 readings coalesced into ten frames is not close to it. The dropped frames come back as `RATE_LIMITED`, after `send()` has
 already returned True, which is why this is a batching problem rather than a
 retry one: by the time anyone can react, the points are gone.
 

{plexus_python-0.11.4 → plexus_python-0.11.6}/plexus/client.py

@@ -182,8 +182,8 @@ class RateLimitedError(PlexusError):
 # The wire slug rule (gateway validate.go sourceIDPattern, max length =
 # MaxStringLen 256) — the old stricter local regex rejected dots, 1-char and
 # >63-char slugs that the gateway accepts. Uuid-shaped slugs are additionally
-# rejected (TypeScript SDK parity): the Plexus app resolves uuid-shaped refs
-# as internal ids, which would make such a source unreachable.
+# rejected: the Plexus app resolves uuid-shaped refs as internal ids, which
+# would make such a source unreachable.
 _SOURCE_ID_RE = re.compile(r'^[a-z0-9][a-z0-9._-]*$')
 _SOURCE_ID_UUID_RE = re.compile(
     r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
@@ -271,7 +271,7 @@ class Plexus:
         if not self.api_key:
             raise ValueError(
                 "No API key. Pass api_key=... or set PLEXUS_API_KEY. "
-                "Get a key at app.plexus.company/devices."
+                "Get a key at app.plexus.company/api."
             )
 
         self.endpoint = (endpoint or get_endpoint()).rstrip("/")
@@ -372,9 +372,9 @@ class Plexus:
     def _infer_class(value: FlexValue) -> str:
         """Numbers are metrics; everything else (str/bool/dict/list) is an event.
 
-        Mirrors the gateway (ingest.go inferClass) and the TypeScript SDK
-        (wire.ts inferClass). bool is a subclass of int in Python, so it must
-        be excluded explicitly or True/False would wrongly become metrics.
+        Mirrors the gateway, which infers class the same way on HTTP /ingest
+        (ingest.go). bool is a subclass of int in Python, so it must be
+        excluded explicitly or True/False would wrongly become metrics.
         """
         return "metric" if isinstance(value, (int, float)) and not isinstance(value, bool) else "event"
 
@@ -543,9 +543,9 @@ class Plexus:
 
         Use this whenever readings arrive faster than a few times a second.
         `send()` puts every reading in its own WebSocket frame, and the gateway
-        limits *frames*, not points — so eight channels at 100 Hz is 800
-        frames/s against a 500/s ceiling, and the overflow is discarded.
-        Batched, the same 800 readings/s is 10 frames/s.
+        limits *frames*, not points — so 25 channels at 100 Hz is 2,500
+        frames/s against a 2,000/s ceiling, and the overflow is discarded.
+        Batched, the same 2,500 readings/s is 10 frames/s.
 
             with px.batch(interval_ms=50) as b:
                 while running:

{plexus_python-0.11.4 → plexus_python-0.11.6}/pyproject.toml

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