Create a universal telemetry receiver (wildcard server for any company)

[angeloINTJ]

What

Turn SIMUT's existing telemetry sinks into a deployable reference receiver — a lightweight, self-contained server that receives data from SIMUT devices and can be dropped into any company's infrastructure without vendor lock-in.

⚠️ Corrected premise — a reference server already exists

An earlier version of this issue said "there is no reference server — each company must build their own receiver from scratch." That is not accurate. Two of them are versioned in this repo and have been run against real hardware in a measured campaign (docs/telemetry-campaign-2026-08-02/):

• tools/telemetry_bench/server_http.py — HTTP/HTTPS sink. Records every byte, the wall-clock of every request, and every record it can parse out of the payload. Metrics to JSON (--stats), parsed records to NDJSON (--records).
• tools/telemetry_bench/server_mqtt.py — MQTT 3.1.1 broker written from the wire format.

So the receiving, parsing and TLS work is done. What is missing is everything that turns an instrument into a product: durable storage, a query API, a dashboard, packaging, and the removal of the deliberate-fault machinery that has no place in a receiver someone deploys.

This reframes the task from "write a server" to "promote and productize tools/telemetry_bench/" — a much smaller, much better-defined job with a working starting point.

Design philosophy

Not a SaaS. A self-hosted, open-source receiver that:

• Runs on-premises (lab server, Raspberry Pi, Docker, bare metal, cloud VM)
• Has pluggable storage (SQLite for single-site, PostgreSQL for multi-site)
• Exposes a simple REST API + minimal dashboard
• Works with any SIMUT device out of the box
• Zero external dependencies beyond the chosen database

Scope — Phase 1 (MVP)

Start from tools/telemetry_bench/, land the result in tools/receiver/ (or a top-level receiver/).

Carry over:

• HTTP POST endpoint accepting SIMUT JSON payloads (from server_http.py)
• MQTT subscriber (from server_mqtt.py)
• Payload parsing — already written, already validated against a real device

Remove or gate behind an explicit dev flag:

• Fault injection (--mode error500|blackhole|slow|half|rst, --tls-fault). These exist to break the device on purpose; a deployed receiver must not be able to do that by accident.

Add:

• SQLite storage backend (replacing NDJSON append)
• Device registry — auto-register by picoUID on first contact
• Timestamp normalization — devices can carry a provisional clock, and a record's stamp may not be trustworthy. Do not assume monotonic device time; record both device time and receipt time.
• GET /api/devices — registered devices with last-seen
• GET /api/devices/:id/readings?from=&to=
• GET /api/devices/:id/alarms
• GET /api/export?format=csv — compliance export
• Single-page dashboard: all devices, current readings, 24h chart
• Docker packaging (docker compose up) — note the repo's existing Dockerfile/docker-compose.yml are for building firmware; the receiver needs its own, kept separate
• README with deployment instructions (lab server, Docker, Raspberry Pi)
• TLS certificate guidance — the bench README's openssl recipe is a starting point; test certs must stay unversioned

Scope — Phase 2 (community-driven)

• Alerting — webhook/email on out-of-range
• Grafana data source
• Multi-tenancy per site/department
• Retention policies
• Authentication (API key or JWT)

Acceptance — Phase 1

• Receiver runs via docker compose up
• HTTP POST and MQTT both receive and store telemetry
• Device auto-registration by picoUID
• REST API for devices and readings
• Dashboard shows live device data
• SQLite works (PostgreSQL optional)
• Fault-injection paths absent or dev-flag-gated
• Deployment README

References

• tools/telemetry_bench/server_http.py, server_mqtt.py, README.md — the starting point
• docs/telemetry-campaign-2026-08-02/ — what these servers already proved
• src/TelemetryManager.cpp — the device-side client