plexus — a local-first hub for edge telemetry

plexus is where a fleet of edge controllers converges. It ingests their MQTT telemetry, stores every metric in a Gorilla-compressed time-series, watches each stream for drift and stuck sensors, and serves one dashboard — from a single package with no database, no broker service, and nothing to sign into.

It's the layer that ties the edge controllers together — the greenhouse and the coop — into one place you can actually reason about.

  greenhouse ─┐                        ┌── Gorilla time-series store
  coop ───────┤─ MQTT ─▶  plexus  ─────┼── drift / stuck detection
  (any device)┘                        └── built-in web dashboard

The built-in dashboard is for the hub itself — raw series, compression ratios, drift verdicts. For a branded, multi-site view with crop tracking, cameras and cultivation alerts layered on top, see Serra, which reads this hub's /api/overview server-side rather than duplicating any of the above.

pip install plexus-hub        # or: git clone && python -m plexus
python -m plexus              # http://127.0.0.1:8092

The demo streams synthetic greenhouse + coop telemetry into the hub, including two injected faults, so the dashboard tells a story immediately:

• coop/motor_current → drift — a slowly rising current, flagged 14σ off the startup baseline: a door-motor bearing wearing out.
• coop/climate/humidity_pct → stuck — a flatline of identical samples: a frozen sensor.

Everything else reads ok. Each card shows the live value, a sparkline, the drift verdict, and the Gorilla compression ratio for that stream.

To point it at a real broker instead of the demo feeder:

python -m plexus --mqtt 192.168.1.20 --topic '#'

The Gorilla codec in plexus/tsc/ is vendored verbatim from the author's own gorilla-tsc (MIT), so the hub stays a single zero-dependency package with nothing to pull at runtime.

python run_tests.py

Pure standard library, no services. It covers the store (with a lossless Gorilla round-trip and the retention ring), the ingest decoder (numeric fields in, states/alerts/booleans out), and the drift detector (insufficient data, stuck sensor, steady stream, and a real baseline shift). CI runs the suite on 3.11 and 3.12 plus ruff on every push.

• Local-first. No cloud, no account, no external time-series database. One pip install, one process, state you can inspect.
• Few dependencies. Standard library only at runtime, including the MQTT client and the Gorilla codec — the supply chain you don't pull can't bite you.
• Failure must be legible. Every drift verdict carries a reason ("14.7 sigma off the startup baseline", "flatline: 20 identical samples") so a human can tell why a stream was flagged.

MIT-licensed. Gorilla codec © the same author via gorilla-tsc.

Eight small repos, one chain: control → transport → hub → supervision. Each one stands alone and runs offline; together they are a working local-first stack with no cloud account anywhere in it.

You are here: plexus.