edge-sync-sdk 0.1.0__py3-none-any.whl

edge_sync/__init__.py

@@ -0,0 +1,7 @@
+"""Telemetry & Edge-Sync edge SDK."""
+
+from .client import Client, auto_init, force_flush, init, track
+
+__version__ = "0.1.0"
+
+__all__ = ["Client", "init", "auto_init", "track", "force_flush"]

edge_sync/client.py

@@ -0,0 +1,287 @@
+"""Edge SDK public API and background sync pipeline.
+
+What a developer using the SDK calls:
+
+    init(server_url, api_key, device_id)
+    track(metric, value, ts=None)      -- returns immediately, never blocks
+    force_flush()                      -- drain everything now (e.g. on shutdown)
+
+What happens after track():
+
+    1. The point is written to a durable SQLite queue (edge_sync/queue.py).
+    2. A background batcher pulls unsent points oldest-first and groups them.
+    3. The sender POSTs the batch to the REST server.
+    4. Points are marked sent only after the server acknowledges. Failed sends
+       retry with backoff, so a dropped connection just grows the backlog, which
+       then drains in chronological order once the network returns.
+
+The pipeline is deliberately data-agnostic: it only ever sees metric/value/ts.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import httpx
+
+from . import sync_policy
+from .queue import Queue
+
+
+class Client:
+    def __init__(
+        self,
+        server_url: str,
+        api_key: str,
+        device_id: str,
+        *,
+        db_path: str = "sdk_outbox.db",
+        metadata: dict | None = None,
+        batch_size: int = 50,
+        flush_interval: float = 2.0,
+        max_backoff: float = 30.0,
+        network: str | None = None,
+        battery: float | None = None,
+        sender=None,
+    ):
+        self.server_url = server_url.rstrip("/")
+        self.api_key = api_key
+        self.device_id = device_id
+        self.metadata = metadata or {}
+        self.max_backoff = max_backoff
+
+        # Link conditions drive the network-aware sync policy. When `network` is
+        # set, batch_size / flush_interval are derived from it dynamically;
+        # otherwise the fixed values passed in are used.
+        self.network = network
+        self.battery = battery
+        self._base_batch_size = batch_size
+        self._base_flush_interval = flush_interval
+        self.batch_size = batch_size          # current effective values
+        self.flush_interval = flush_interval
+        self._apply_policy()
+
+        self.queue = Queue(db_path)
+
+        # The sender is injectable so tests can simulate a flaky/offline network.
+        # It takes a batch dict and must raise on failure, return on success.
+        self._sender = sender or self._http_send
+        self._http = httpx.Client(timeout=10.0) if sender is None else None
+
+        self._seq = 0
+        self._seq_lock = threading.Lock()
+
+        self._stop = threading.Event()
+        self._wake = threading.Event()   # nudges the batcher to flush now
+        self._worker = threading.Thread(target=self._run, daemon=True)
+        self._worker.start()
+
+    # --- public API ---------------------------------------------------------
+
+    def track(self, metric: str, value: float, ts: int | None = None) -> str:
+        """Inject one data point. Persists it durably and returns immediately."""
+        if ts is None:
+            ts = int(time.time() * 1000)
+        point_id = self._next_id(ts)
+        self.queue.enqueue(point_id, metric, float(value), ts)
+        # If we've hit a full batch, nudge the worker instead of waiting.
+        if self.queue.unsent_count() >= self.batch_size:
+            self._wake.set()
+        return point_id
+
+    def force_flush(self, timeout: float = 15.0) -> bool:
+        """Block until the queue is fully drained or `timeout` elapses.
+
+        Returns True if everything was acknowledged, False on timeout.
+        """
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            if self.queue.unsent_count() == 0:
+                return True
+            self._wake.set()
+            time.sleep(0.05)
+        return self.queue.unsent_count() == 0
+
+    def close(self) -> None:
+        """Stop the background worker and release resources."""
+        self._stop.set()
+        self._wake.set()
+        self._worker.join(timeout=5.0)
+        if self._http is not None:
+            self._http.close()
+        self.queue.close()
+
+    # --- network-aware sync policy ------------------------------------------
+
+    def set_link(self, network: str | None = None, battery: float | None = None) -> None:
+        """Update the device's link conditions; the batcher adapts immediately."""
+        if network is not None:
+            self.network = network
+        if battery is not None:
+            self.battery = battery
+        self._apply_policy()
+        self._wake.set()   # re-evaluate the loop now
+
+    def _apply_policy(self) -> None:
+        """Recompute effective batch size / flush interval from link state."""
+        if self.network is None:
+            self.batch_size = self._base_batch_size
+            self.flush_interval = self._base_flush_interval
+            self._allow_send = True
+        else:
+            self.batch_size, self.flush_interval, self._allow_send = sync_policy.plan(
+                self.network, self.battery
+            )
+
+    def _send_metadata(self) -> dict:
+        """Static metadata plus current link state, sent once per batch."""
+        meta = dict(self.metadata)
+        if self.network is not None:
+            meta["network"] = self.network
+        if self.battery is not None:
+            meta["battery"] = self.battery
+        return meta
+
+    # --- id assignment ------------------------------------------------------
+
+    def _next_id(self, ts: int) -> str:
+        # device + sequence + timestamp -> globally unique, client-assigned.
+        # This is what makes server ingestion idempotent.
+        with self._seq_lock:
+            self._seq += 1
+            seq = self._seq
+        return f"{self.device_id}-{seq:06d}-{ts}"
+
+    # --- background batcher + sender ----------------------------------------
+
+    def _run(self) -> None:
+        backoff = 1.0
+        while not self._stop.is_set():
+            # Flush on a timer or when nudged (full batch / force_flush / close).
+            self._wake.wait(timeout=self.flush_interval)
+            self._wake.clear()
+
+            # Network-aware policy: when the device knows it's offline, don't
+            # attempt to send -- just keep buffering durably (saves the radio).
+            if not self._allow_send:
+                continue
+
+            sent_any = True
+            while sent_any and not self._stop.is_set():
+                points = self.queue.fetch_unsent(self.batch_size)
+                if not points:
+                    sent_any = False
+                    backoff = 1.0
+                    break
+                try:
+                    self._send_batch(points)
+                    self.queue.mark_sent([p["id"] for p in points])
+                    backoff = 1.0
+                except Exception:
+                    # Network/server failure: leave points unsent and back off.
+                    # They stay safely in the queue and are retried next loop.
+                    self._sleep_backoff(backoff)
+                    backoff = min(backoff * 2, self.max_backoff)
+                    sent_any = False
+
+        # On close, make a best-effort final drain of whatever is queued.
+        self._drain_remaining()
+
+    def _send_batch(self, points: list[dict]) -> None:
+        batch = {
+            "device_id": self.device_id,
+            "metadata": self._send_metadata(),
+            "points": points,
+        }
+        self._sender(batch)
+
+    def _http_send(self, batch: dict) -> None:
+        resp = self._http.post(
+            f"{self.server_url}/api/v1/telemetry",
+            json=batch,
+            headers={"X-API-Key": self.api_key},
+        )
+        resp.raise_for_status()
+
+    def _sleep_backoff(self, seconds: float) -> None:
+        # Interruptible sleep so close()/force_flush() stay responsive.
+        self._wake.wait(timeout=seconds)
+        self._wake.clear()
+
+    def _drain_remaining(self) -> None:
+        try:
+            points = self.queue.fetch_unsent(self.batch_size)
+            while points:
+                self._send_batch(points)
+                self.queue.mark_sent([p["id"] for p in points])
+                points = self.queue.fetch_unsent(self.batch_size)
+        except Exception:
+            pass  # best effort; unsent data remains durably on disk
+
+
+# --- module-level convenience API ------------------------------------------
+# Mirrors the architecture's public surface: init / track / force_flush.
+
+_default: Client | None = None
+
+
+def init(server_url: str, api_key: str, device_id: str, **kwargs) -> Client:
+    global _default
+    _default = Client(server_url, api_key, device_id, **kwargs)
+    return _default
+
+
+def auto_init(config_path: str | None = None) -> Client:
+    """Initialize the SDK without hand-coding init() — read config from, in order:
+
+      1. an explicit JSON file at `config_path`,
+      2. a `telemetry.json` file in the current directory (if present),
+      3. environment variables: TELEMETRY_SERVER_URL, TELEMETRY_API_KEY,
+         TELEMETRY_DEVICE_ID, and optional TELEMETRY_NETWORK.
+
+    A config file may set: server_url, api_key, device_id, network, and any other
+    Client option (batch_size, flush_interval, db_path, metadata, …). Handy on a
+    device that's provisioned once with a key from the dashboard's Setup tab.
+    """
+    import json
+    import os
+
+    cfg: dict = {}
+    path = config_path or ("telemetry.json" if os.path.exists("telemetry.json") else None)
+    if path:
+        with open(path, "r", encoding="utf-8") as f:
+            cfg = json.load(f)
+
+    server_url = cfg.get("server_url") or os.environ.get("TELEMETRY_SERVER_URL")
+    api_key = cfg.get("api_key") or os.environ.get("TELEMETRY_API_KEY")
+    device_id = cfg.get("device_id") or os.environ.get("TELEMETRY_DEVICE_ID")
+    network = cfg.get("network") or os.environ.get("TELEMETRY_NETWORK")
+
+    missing = [n for n, v in
+               (("server_url", server_url), ("api_key", api_key), ("device_id", device_id))
+               if not v]
+    if missing:
+        raise RuntimeError(
+            "auto_init() is missing: " + ", ".join(missing) +
+            ". Provide them in a config file or TELEMETRY_* environment variables."
+        )
+
+    # Pass through any extra Client options from the config file.
+    opts = {k: v for k, v in cfg.items()
+            if k not in ("server_url", "api_key", "device_id")}
+    if network and "network" not in opts:
+        opts["network"] = network
+    return init(server_url, api_key, device_id, **opts)
+
+
+def track(metric: str, value: float, ts: int | None = None) -> str:
+    if _default is None:
+        raise RuntimeError("SDK not initialized; call init() first")
+    return _default.track(metric, value, ts)
+
+
+def force_flush(timeout: float = 15.0) -> bool:
+    if _default is None:
+        raise RuntimeError("SDK not initialized; call init() first")
+    return _default.force_flush(timeout)

edge_sync/integrations/__init__.py

@@ -0,0 +1,6 @@
+"""Optional integrations that bridge a specific device to the generic SDK.
+
+These are thin, device-specific helpers; the SDK core stays generic. The
+solar-race helper, for example, flattens a SolarRace-OS `vehicle_state` dict
+into `track()` calls.
+"""

edge_sync/integrations/raspberry_pi.py

@@ -0,0 +1,122 @@
+"""Raspberry Pi system-metrics integration — a hardware-free starting point.
+
+Reads the Pi's own health from the OS (CPU temperature, load, memory, uptime)
+and feeds it to the SDK. It needs **no extra sensors**, so it runs on any
+Raspberry Pi out of the box — useful on its own, and a demonstration that the
+SDK serves *any* Pi project, not one specific device.
+
+Reads are best-effort: anything the platform doesn't expose (e.g. off a Pi) is
+simply skipped, so this never crashes on a dev laptop. Standard library only.
+
+    from edge_sync.client import auto_init
+    from edge_sync.integrations.raspberry_pi import SystemMonitor
+
+    auto_init()
+    SystemMonitor(client=None, hz=1).start()   # streams cpu_temp_C, load, mem…
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+
+from ..client import track as _default_track
+
+
+def _read_cpu_temp_c():
+    """CPU temperature in °C from the thermal zone, or None if unavailable."""
+    try:
+        with open("/sys/class/thermal/thermal_zone0/temp") as f:
+            return round(int(f.read().strip()) / 1000.0, 1)
+    except Exception:
+        return None
+
+
+def _read_loadavg():
+    """(1m, 5m, 15m) load averages, or None (os.getloadavg is Unix-only)."""
+    try:
+        return os.getloadavg()
+    except (OSError, AttributeError):
+        return None
+
+
+def _read_mem_used_percent():
+    """Used memory as a percentage from /proc/meminfo, or None."""
+    try:
+        info = {}
+        with open("/proc/meminfo") as f:
+            for line in f:
+                key, _, rest = line.partition(":")
+                info[key] = int(rest.strip().split()[0])  # value is in kB
+        total, avail = info.get("MemTotal"), info.get("MemAvailable")
+        if total and avail is not None:
+            return round((total - avail) / total * 100.0, 1)
+    except Exception:
+        pass
+    return None
+
+
+def _read_uptime_s():
+    """Uptime in seconds from /proc/uptime, or None."""
+    try:
+        with open("/proc/uptime") as f:
+            return round(float(f.read().split()[0]), 0)
+    except Exception:
+        return None
+
+
+def read_system_metrics() -> dict:
+    """A dict of the Pi system metrics available on this host (skips missing)."""
+    metrics = {}
+    temp = _read_cpu_temp_c()
+    if temp is not None:
+        metrics["cpu_temp_C"] = temp
+    load = _read_loadavg()
+    if load is not None:
+        metrics["cpu_load_1m"] = round(load[0], 2)
+        metrics["cpu_load_5m"] = round(load[1], 2)
+    mem = _read_mem_used_percent()
+    if mem is not None:
+        metrics["mem_used_percent"] = mem
+    uptime = _read_uptime_s()
+    if uptime is not None:
+        metrics["uptime_s"] = uptime
+    return metrics
+
+
+def track_system_metrics(client=None, ts: int | None = None) -> int:
+    """Read the Pi's system metrics and hand each to the SDK via track()."""
+    track = client.track if client is not None else _default_track
+    n = 0
+    for name, value in read_system_metrics().items():
+        track(name, float(value), ts)
+        n += 1
+    return n
+
+
+class SystemMonitor:
+    """Polls the Pi's system metrics at `hz` and streams them through the SDK.
+
+    Drop-in like the solar-car simulator, but for the Pi itself — no hardware.
+    """
+
+    def __init__(self, client, hz: float = 1.0):
+        self.client = client
+        self.period = 1.0 / hz
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> "SystemMonitor":
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2.0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            # One device timestamp per sample, shared by all its metrics.
+            track_system_metrics(self.client, ts=int(time.time() * 1000))
+            time.sleep(self.period)

edge_sync/integrations/solar_race.py

@@ -0,0 +1,139 @@
+"""SolarRace-OS integration for the Edge-Sync SDK.
+
+The solar car's Raspberry Pi reads the CAN bus and decodes it into a nested
+`vehicle_state` dict (BMS / motor controller / battery-temp controller).
+
+`track_vehicle_state()` takes that dict and hands every meaningful numeric signal
+to the SDK via `track()`, which buffers it durably, batches it, and syncs it to
+the REST server in order even across network dropouts. No CAN decoding happens
+here — the Pi already did it.
+
+    # in your main loop, once you have a decoded vehicle_state:
+    from edge_sync.client import init
+    from edge_sync.integrations.solar_race import track_vehicle_state
+
+    init(SERVER_URL, API_KEY, device_id="solar-car-01", network="lte")
+    ...
+    track_vehicle_state(self.vehicle_state)     # <- one line, resilient
+
+`SimulatedSolarCar` reproduces a realistic `vehicle_state` off-car (no hardware)
+and feeds it through the very same bridge, so the demo exercises the real path.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+
+from ..client import track as _default_track
+
+# Fields that are identifiers, counters, codes, or duplicates — not telemetry
+# worth charting. Kept out so the dashboard stays a clean, meaningful set.
+_SKIP_KEYS = {
+    "temp_module", "bms_balance_mask",
+    "bms_string_count", "bms_ntc_count",          # static hardware specs
+    "bms_cycles", "bms_full_capacity_Ah",         # rarely-changing / spec
+    "bms_error_code", "mms_error_code", "mms_limit_code",  # bitmask codes, not series
+    "calculated_lap",                             # derived counter
+    "battery_temp_avg_C", "battery_temp_low_C",   # duplicate of battery_temp_C / less useful
+}
+
+
+def track_vehicle_state(vehicle_state: dict, client=None, ts: int | None = None) -> int:
+    """Hand the meaningful numeric signals in a `vehicle_state` dict to the SDK.
+
+    Walks each section (battery / motor / temp_controller / …) and calls
+    `track(name, value, ts)` for each chartable numeric signal. To keep the
+    dashboard readable it does two clean-ups:
+
+      * the 30+ per-cell voltages (`bms_cell_01_V` …) are collapsed into a
+        compact **min / max / spread** summary — the numbers that actually
+        indicate pack health — instead of 30 separate series;
+      * identifiers, counters, bitmask codes, and duplicate fields are skipped
+        (see `_SKIP_KEYS`). Booleans and lists are skipped too.
+
+    Pass `ts` (the car's snapshot timestamp, epoch ms) so every signal in one
+    decoded frame shares the same device time — that's what keeps the history
+    chronologically correct, exactly like the car's own `timestamp` field. When
+    omitted, the SDK stamps each point at track() time.
+
+    Pass `client` to target a specific SDK instance; otherwise the module-level
+    SDK configured via `init()` is used. Returns how many points were tracked.
+    """
+    track = client.track if client is not None else _default_track
+    n = 0
+    for section, signals in vehicle_state.items():
+        if not isinstance(signals, dict):
+            continue
+
+        # Collapse per-cell voltages (bms_cell_01_V …) into a 3-number summary.
+        cells = [v for k, v in signals.items()
+                 if k.startswith("bms_cell_") and isinstance(v, (int, float))
+                 and not isinstance(v, bool)]
+        if cells:
+            track("bms_cell_min_V", round(min(cells), 3), ts)
+            track("bms_cell_max_V", round(max(cells), 3), ts)
+            track("bms_cell_spread_V", round(max(cells) - min(cells), 3), ts)
+            n += 3
+
+        for name, value in signals.items():
+            if name.startswith("bms_cell_") or name in _SKIP_KEYS or isinstance(value, bool):
+                continue
+            if isinstance(value, (int, float)):
+                track(name, float(value), ts)
+                n += 1
+    return n
+
+
+class SimulatedSolarCar:
+    """Off-car simulator: produces a SolarRace-OS-shaped `vehicle_state` and
+    feeds it through `track_vehicle_state()`, so `python scripts/run.py` on a laptop
+    looks like the real car. Several signals are tuned to cross the server's
+    alert thresholds so the Alerts panel has something to show.
+    """
+
+    def __init__(self, client, hz: float = 5.0):
+        self.client = client
+        self.period = 1.0 / hz
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> "SimulatedSolarCar":
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2.0)
+
+    def _state(self, t: float) -> dict:
+        battery_temp = round(42 + 6 * math.sin(t / 7), 1)        # ~36-48, crosses 45
+        return {
+            "battery": {
+                "bms_voltage_V": round(108 + 6 * math.sin(t / 20), 2),
+                "bms_current_A": round(18 + 12 * math.sin(t / 5), 2),
+                "bms_soc_percent": round(max(2.0, 100 - (t * 1.2) % 100), 1),  # drains <20
+                "bms_temp_1_C": round(44 + 8 * math.sin(t / 13), 1),           # crosses 50
+                "bms_temp_2_C": round(40 + 5 * math.sin(t / 15), 1),
+            },
+            "motor": {
+                "mms_rpm": int(2500 + 1800 * math.sin(t / 4)),
+                "mms_power_W": int(1500 + 1200 * math.sin(t / 4)),
+                "mms_temperature_C": round(72 + 15 * math.sin(t / 11), 1),     # crosses 80
+            },
+            "temp_controller": {
+                "battery_temp_C": battery_temp,
+                "battery_temp_high_C": round(battery_temp + 3, 1),
+                "battery_temp_low_C": round(battery_temp - 3, 1),
+            },
+        }
+
+    def _run(self) -> None:
+        t = 0.0
+        while not self._stop.is_set():
+            # One device timestamp per snapshot, shared by all its signals.
+            ts = int(time.time() * 1000)
+            track_vehicle_state(self._state(t), self.client, ts=ts)
+            t += self.period
+            time.sleep(self.period)

edge_sync/queue.py

@@ -0,0 +1,81 @@
+"""Durable local queue for the edge SDK.
+
+Every tracked point is written to SQLite *before* anything tries to send it.
+That is the whole durability story: if the network is down or the device
+reboots mid-flight, the data is still on disk and gets drained later.
+
+The queue is the only shared state between the caller's thread (which calls
+`enqueue` via `track()`) and the background batcher thread (which calls
+`fetch_unsent` / `mark_sent`), so every operation is guarded by a lock and uses
+a single connection opened with check_same_thread=False.
+"""
+
+import sqlite3
+import threading
+
+
+class Queue:
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS outbox (
+                id     TEXT PRIMARY KEY,   -- client-assigned point id
+                metric TEXT NOT NULL,
+                value  REAL NOT NULL,
+                ts     INTEGER NOT NULL,   -- device timestamp (epoch ms)
+                sent   INTEGER NOT NULL DEFAULT 0,
+                seq    INTEGER             -- monotonic insert order, for stable tiebreak
+            )
+            """
+        )
+        self._conn.commit()
+
+    def enqueue(self, id: str, metric: str, value: float, ts: int) -> None:
+        """Persist one point. INSERT OR IGNORE so a duplicate id is a no-op."""
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR IGNORE INTO outbox (id, metric, value, ts, sent, seq) "
+                "VALUES (?, ?, ?, ?, 0, (SELECT COALESCE(MAX(seq), 0) + 1 FROM outbox))",
+                (id, metric, value, ts),
+            )
+            self._conn.commit()
+
+    def fetch_unsent(self, limit: int) -> list[dict]:
+        """Oldest-first batch of points not yet acknowledged by the server.
+
+        Ordered by device timestamp (then insert order) so the backlog drains in
+        chronological order the moment the network returns.
+        """
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT id, metric, value, ts FROM outbox "
+                "WHERE sent = 0 ORDER BY ts ASC, seq ASC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def mark_sent(self, ids: list[str]) -> None:
+        """Mark points sent -- only ever called after the server acknowledges."""
+        if not ids:
+            return
+        with self._lock:
+            self._conn.executemany(
+                "UPDATE outbox SET sent = 1 WHERE id = ?", [(i,) for i in ids]
+            )
+            self._conn.commit()
+
+    def unsent_count(self) -> int:
+        with self._lock:
+            (n,) = self._conn.execute(
+                "SELECT COUNT(*) FROM outbox WHERE sent = 0"
+            ).fetchone()
+        return n
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()

edge_sync/sync_policy.py

@@ -0,0 +1,49 @@
+"""Network-aware sync policy.
+
+A cellular-aware device shouldn't sync the same way on Wi-Fi as it does on a
+weak Edge link with a near-dead battery. This module maps the current link
+conditions (network type + battery level) to two knobs the batcher uses:
+
+  * batch_size      -- how many points to group per request
+  * flush_interval  -- how often to attempt a send
+
+The intent: on a fast link, send small batches often (low latency); on a slow
+or expensive link, send larger batches less often (fewer round-trips, less
+radio wake-up). On low battery, back off further. When the device knows it's
+offline, don't even try -- just keep buffering durably.
+
+This lives outside the pipeline so the policy is swappable and testable on its
+own; the SDK core stays generic.
+"""
+
+from __future__ import annotations
+
+# Faster / cheaper links -> smaller batches, more often (low latency). Slower /
+# costlier links -> bigger batches, less often, so each expensive round-trip and
+# radio wake-up carries more samples.
+NETWORK_PROFILES = {
+    "wifi":    {"batch_size": 25,  "flush_interval": 1.0},
+    "5g":      {"batch_size": 40,  "flush_interval": 1.5},
+    "lte":     {"batch_size": 50,  "flush_interval": 2.0},
+    "3g":      {"batch_size": 75,  "flush_interval": 4.0},
+    "edge":    {"batch_size": 100, "flush_interval": 6.0},
+    "offline": {"batch_size": 50,  "flush_interval": 2.0},  # buffer only
+}
+
+LOW_BATTERY_PCT = 20
+
+
+def plan(network: str, battery: float | None = None) -> tuple[int, float, bool]:
+    """Return (batch_size, flush_interval, allow_send) for the conditions."""
+    profile = NETWORK_PROFILES.get(network, NETWORK_PROFILES["lte"])
+    batch_size = profile["batch_size"]
+    flush_interval = profile["flush_interval"]
+    allow_send = network != "offline"
+
+    # Low battery: sync less aggressively, in fewer/larger bursts, to cut the
+    # number of energy-hungry radio wake-ups.
+    if battery is not None and battery < LOW_BATTERY_PCT:
+        flush_interval *= 2.0
+        batch_size = min(batch_size * 2, 200)
+
+    return batch_size, flush_interval, allow_send

edge_sync_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: edge-sync-sdk
+Version: 0.1.0
+Summary: Resilient telemetry & edge-sync SDK for the Raspberry Pi — buffer sensor data locally and sync it reliably across network dropouts, in order, with no duplicates.
+Project-URL: Homepage, https://github.com/leerosenblit/Telemetry-Edge-Sync-SDK
+Project-URL: Repository, https://github.com/leerosenblit/Telemetry-Edge-Sync-SDK
+Project-URL: Issues, https://github.com/leerosenblit/Telemetry-Edge-Sync-SDK/issues
+Author-email: Lee Rosenblit <Lee.Rosenblit@au10tix.com>
+License: MIT License
+        
+        Copyright (c) 2026 Lee Rosenblit
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: buffering,edge,iot,offline-first,raspberry-pi,rest,sqlite,sync,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# Telemetry & Edge-Sync SDK
+
+> A resilient telemetry & edge-sync SDK for the **Raspberry Pi** — buffer sensor data
+> locally, sync it reliably across network dropouts, in correct time order, with no
+> duplicates. Works with **any sensors**; ships with a solar-race-car integration as a
+> real, proven example.
+
+## Description
+
+Lots of Raspberry Pi projects stream sensor data over a flaky link — a field weather
+station, a robot, an environmental or industrial monitor, or a solar race car threading
+through tunnels and dead zones. A naive "push to the cloud" loses every sample sent
+during an outage.
+
+This SDK is the fix. On the device it **buffers telemetry to a local SQLite queue
+first**, batches it, and syncs it to a REST server — surviving network dropouts *and*
+reboots. A web portal visualizes it live. Your code integrates in **three lines**
+(`init` / `track` / `force_flush`); whoever watches the dashboard writes **zero**.
+
+The pipeline is **sensor-agnostic** — it only moves `metric / value / timestamp`. Two
+ready integrations show the range: a hardware-free **Raspberry Pi system-metrics** one
+that runs on any Pi out of the box, and the **flagship solar race car** (BMS / motor /
+battery-temp decoded from CAN).
+
+> **The one guarantee:** no data is lost when the device loses signal, and it arrives in
+> correct chronological order, with no duplicates.
+
+## Install
+
+```bash
+pip install edge-sync-sdk
+```
+
+```python
+from edge_sync import init, track, force_flush
+
+init("https://your-server.example.com", api_key="<key>", device_id="pi-01")
+track("cpu_temp_C", 54.2)      # any metric — non-blocking, persisted to disk
+force_flush()                  # drain the queue before exit
+```
+
+Requires Python 3.9+. The only dependency is [`httpx`](https://www.python-httpx.org/).
+(To run the **server + dashboard** locally, clone the repo and `pip install -r
+requirements.txt` — see [Quick start](#quick-start).)
+
+## Features
+
+- **Durable offline queue** — every reading is written to on-device SQLite *before* any
+  send, so dropouts and reboots lose nothing.
+- **Smart batching** — many samples per request (by count or time): fewer round-trips,
+  less radio/battery cost.
+- **Auto-sync recovery** — backlog drains **oldest-first** the moment the link returns.
+- **Ordered, idempotent ingestion** — points carry a client-assigned id; the server
+  upserts on it, so retries never duplicate. Stored by **device time**, not arrival time.
+- **Network-aware sync policy** — batch size & frequency adapt to link type and battery.
+- **Server-side alert rule engine** — threshold rules over your signals, editable
+  live from the portal.
+- **API keys** — generate/revoke keys from the dashboard; the SDK can `auto_init()` from
+  config or environment.
+- **Pit-wall portal** — live charts, device health, alerts, rules editor, device setup.
+- **Your own backend** — plain REST to your own server, no vendor lock-in and no cloud
+  credentials on the car.
+
+## Screenshots
+
+**Overview — live charts**
+
+![Overview](docs/media/overview.png)
+
+**Alerts**
+
+![Alerts](docs/media/alerts.png)
+
+**Rules editor**
+
+![Rules](docs/media/rules.png)
+
+## Video
+
+▶ **[Watch the demo walkthrough ](https://github.com/leerosenblit/Telemetry-Edge-Sync-SDK/issues/1)** 
+
+<!-- To embed an inline PLAYER instead of a link: in issue #1, right-click the video ->
+     "Copy link address" to get its asset URL (https://github.com/.../assets/.../….mp4),
+     then paste that URL on its own line here, replacing the link line above. -->
+
+---
+
+## Data model (JSON)
+
+A **telemetry point** the SDK produces:
+
+```json
+{ "id": "solar-car-01-000042-1718900000123", "metric": "battery_temp_C", "value": 46.2, "ts": 1718900000123 }
+```
+
+`id` = `device-sequence-timestamp` (client-assigned → enables idempotent ingestion).
+`ts` is the **device** timestamp in epoch ms (the source of truth for ordering).
+
+A **batch** the SDK POSTs (static metadata once, dynamic points many):
+
+```json
+{
+  "device_id": "solar-car-01",
+  "metadata": { "fw": "RaceOS-2.0", "type": "solar-car", "network": "lte" },
+  "points": [
+    { "id": "solar-car-01-000001-1718900000100", "metric": "bms_voltage_V",   "value": 108.4, "ts": 1718900000100 },
+    { "id": "solar-car-01-000002-1718900000101", "metric": "bms_soc_percent", "value": 76.0,  "ts": 1718900000101 }
+  ]
+}
+```
+
+## Database
+
+Server storage is SQLite. The core table (full schema + ERD in
+[docs/diagrams.md](docs/diagrams.md)):
+
+```sql
+CREATE TABLE telemetry (
+  id          TEXT PRIMARY KEY,   -- client-assigned -> idempotent upsert
+  device_id   TEXT NOT NULL,
+  metric      TEXT NOT NULL,
+  value       REAL NOT NULL,
+  device_ts   INTEGER NOT NULL,   -- order + late-arrival by device time
+  received_ts INTEGER NOT NULL    -- server arrival (diagnostics only)
+);
+-- sample row:
+-- ('solar-car-01-000042-...', 'solar-car-01', 'battery_temp_C', 46.2, 1718900000123, 1718900000130)
+```
+
+Other tables: `device_meta` (latest metadata per device), `alerts` (rule breaches),
+`rules` (editable alert rules), `api_keys` (issued keys). On the car, the SDK keeps a
+durable `outbox` table.
+
+---
+
+## Public functions
+
+What the car's software calls. Full reference + examples in
+[docs/sdk-reference.md](docs/sdk-reference.md).
+
+| Function | Purpose |
+|---|---|
+| `init(server_url, api_key, device_id, **opts)` | Configure the SDK (target, auth, identity, options). |
+| `auto_init(config_path=None)` | Configure from a `telemetry.json` file or `TELEMETRY_*` env vars — no hand-coding. |
+| `track(metric, value, ts=None)` | Record one data point. Non-blocking, durable. Returns the point id. |
+| `force_flush(timeout=15.0)` | Block until the queue drains (e.g. before shutdown). |
+| `Client(...)` | The SDK object behind the module API (use directly for multiple devices/instances). |
+| `Client.set_link(network=, battery=)` | Update link conditions at runtime; the batcher adapts immediately. |
+| `track_vehicle_state(vehicle_state, client=None, ts=None)` | Hand a SolarRace-OS dict to the SDK — tracks every numeric signal. |
+
+```python
+from edge_sync.client import init, track, force_flush
+init("https://your-server.example.com", api_key="<key>", device_id="pi-01")
+track("cpu_temp_C", 54.2)      # any metric — a sensor reading, a system stat, …
+force_flush()
+```
+
+### Integrations
+
+Device-specific bridges live in `edge_sync/integrations/` — write a small one for your
+project, or just call `track()` directly. Two ship with the SDK:
+
+| Integration | What it does |
+|---|---|
+| `raspberry_pi` | Streams the Pi's own system metrics (CPU temp, load, memory, uptime) — **no hardware needed**, runs on any Pi. |
+| `solar_race` (flagship) | Hands a solar car's decoded `vehicle_state` (BMS / motor / battery-temp) to the SDK in one call. |
+
+## Internal functions
+
+The implementation behind the guarantee (see [docs/implementation.md](docs/implementation.md)).
+
+| Where | Function | Role |
+|---|---|---|
+| `edge_sync/queue.py` | `Queue.enqueue / fetch_unsent / mark_sent` | Durable SQLite outbox; fetch oldest-first; mark sent only after ack. |
+| `edge_sync/client.py` | `_run` | Background batcher loop: flush on timer/nudge, retry with exponential backoff. |
+| `edge_sync/client.py` | `_send_batch / _http_send` | Package points into a batch and POST with `X-API-Key`. |
+| `edge_sync/client.py` | `_apply_policy / _next_id` | Apply network policy; mint the client-assigned point id. |
+| `edge_sync/sync_policy.py` | `plan(network, battery)` | Map link conditions → `(batch_size, flush_interval, allow_send)`. |
+| `server/main.py` | `ingest / _valid_key / load_rules` | Auth, idempotent upsert, alert-rule evaluation. |
+
+---
+
+## Diagrams
+
+(Also in [docs/diagrams.md](docs/diagrams.md). Mermaid renders on GitHub.)
+
+### System architecture
+
+```mermaid
+flowchart LR
+    subgraph CAR["Solar car — Raspberry Pi"]
+        OS["SolarRace-OS<br/>decodes CAN → vehicle_state"] --> BRIDGE["track_vehicle_state()"]
+        subgraph SDK["Edge-Sync SDK"]
+            BRIDGE --> Q[("SQLite outbox")] --> BATCH["Batcher"] --> SEND["Sender (retry)"]
+        end
+    end
+    SEND -- "POST /api/v1/telemetry (X-API-Key)" --> API
+    subgraph SERVER["REST API server (FastAPI)"]
+        API["Ingest: auth · upsert · rules"] --> DB[("SQLite")]
+    end
+    DB --> READ["GET /metrics · /alerts · /devices"] -- "poll 1.5s" --> PORTAL["Pit-wall portal"]
+```
+
+### Entity-relationship diagram
+
+```mermaid
+erDiagram
+    OUTBOX      ||..|| TELEMETRY : "syncs (by point id)"
+    TELEMETRY   ||--o{ ALERTS    : "breach raises"
+    RULES       ||--o{ ALERTS    : "evaluated into"
+    DEVICE_META ||--o{ TELEMETRY : "describes (device_id)"
+    API_KEYS    ||..o{ TELEMETRY : "authenticates ingest"
+```
+
+> Full table-by-table ERD with columns is in [docs/diagrams.md](docs/diagrams.md).
+
+### Sequence (track → chart, with offline recovery)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Pi as Car (SolarRace-OS)
+    participant SDK as Edge-Sync SDK
+    participant API as REST server
+    participant UI as Pit portal
+    Pi->>SDK: track_vehicle_state(vehicle_state, ts)
+    SDK->>SDK: enqueue to SQLite (durable)
+    loop batcher
+        alt network up
+            SDK->>API: POST /telemetry (batch)
+            API->>API: validate key · upsert · rules
+            API-->>SDK: 200 {accepted, alerts}
+            SDK->>SDK: mark_sent
+        else network down
+            SDK--xAPI: fails → backoff, keep buffering
+        end
+    end
+    UI->>API: GET /metrics (poll)
+    API-->>UI: points (device-time order) + alerts
+```
+
+### State (the batcher)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Draining: timer / full / force_flush
+    Draining --> Sending: unsent exist
+    Draining --> Idle: empty
+    Sending --> Idle: 200 OK (mark_sent)
+    Sending --> Backoff: send failed
+    Backoff --> Sending: wait (1s→2s→4s…)
+    Idle --> BufferOnly: network = offline
+    BufferOnly --> Idle: link restored
+```
+
+---
+
+## Quick start
+
+```bash
+pip install -r requirements.txt
+```
+
+**Run the server only** (no simulator — use this with a real Pi, and it's exactly what the
+cloud runs):
+
+```bash
+uvicorn server.main:app --host 0.0.0.0 --port 8000
+```
+
+**Or run the all-in-one local demo** (server **+** a simulated solar car + opens the portal —
+for trying it out with no hardware):
+
+```bash
+python scripts/run.py
+```
+
+- **Portal:** http://127.0.0.1:8000/ · **API docs (Swagger):** http://127.0.0.1:8000/docs
+- In the portal's **Setup** tab, generate an API key — it shows a ready-to-paste
+  `auto_init()` snippet for your device. Full walkthrough: [docs/getting-started.md](docs/getting-started.md).
+- **On a real Pi**, stream its own system metrics (no hardware) with
+  `python examples/pi_metrics.py`, or wire your sensors with three `track()` calls.
+- To run the server **publicly** (so a remote Pi can reach it), deploy it with the
+  included [`render.yaml`](render.yaml) / [`Procfile`](Procfile).
+
+Resilience demo: while data is streaming, stop and restart the server — the device keeps
+buffering and drains the backlog **in order**, nothing lost.
+
+## REST API
+
+| Method & path | Role |
+|---|---|
+| `POST /api/v1/telemetry` | Ingest a batch (auth `X-API-Key`). Idempotent upsert by point id. |
+| `GET /api/v1/metrics?device=&metric=&from=&to=` | Read points, ordered by device time. |
+| `GET /api/v1/devices` | Per-device health + latest metadata. |
+| `GET /api/v1/alerts?device=&limit=` | Recent alerts. |
+| `GET/POST/PATCH/DELETE /api/v1/rules` | Manage alert rules. |
+| `GET/POST/DELETE /api/v1/keys` | Issue / list / revoke API keys. |
+
+Full reference: [docs/rest-api.md](docs/rest-api.md).
+
+## Documentation
+
+Full docs live in **[`docs/`](docs/)** (the permalink once pushed to GitHub):
+[index](docs/index.md) · [use cases](docs/use-cases.md) · [features](docs/features.md) ·
+[getting started](docs/getting-started.md) · [SDK reference](docs/sdk-reference.md) ·
+[user init & API keys](docs/user-init.md) · [dashboard](docs/dashboard.md) ·
+[implementation](docs/implementation.md) · [REST API](docs/rest-api.md) ·
+[diagrams](docs/diagrams.md).
+
+## Deploying to the cloud
+
+To run the server publicly so a remote Pi (on cellular) can reach it, deploy to Render (or
+any Procfile host) using the included [`render.yaml`](render.yaml) / [`Procfile`](Procfile).
+
+## Project layout
+
+```
+edge_sync/              edge SDK: client (queue→batch→retry), durable queue, sync policy, auto_init
+  integrations/   device bridges — raspberry_pi.py (system metrics) + solar_race.py (flagship)
+server/           FastAPI REST API + alert rule engine + API keys, serves the portal
+dashboard/        single-page command-center portal (no build step, no CDN)
+docs/             the documentation set (architecture, API reference, diagrams, …)
+examples/         runnable demo.py + pi_metrics.py + the telemetry.json config template
+scripts/          run.py — one-command launcher (server + simulated solar car)
+tests/            test suite + shared conftest fixtures
+pyproject.toml · requirements.txt        project config + dependencies
+Procfile · render.yaml · runtime.txt     cloud-deploy config (Render)
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+Covers the core guarantees: no-loss across a network drop, idempotency on lost
+acknowledgements, data survival across a process restart, the alert rule engine, the
+network-aware sync policy, API-key validation, and `auto_init`.
+
+## Design & scope
+
+- [docs/architecture.md](docs/architecture.md) — full design and key engineering decisions.
+- [docs/future-work.md](docs/future-work.md) — what's deferred (TSDB, message broker, Protobuf,
+  WebSocket push, multi-car fleet) and why, with the path to add each.

edge_sync_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+edge_sync/__init__.py,sha256=OQ1clIJhuEPNNHbYO1UtZaEjtr_yEmWLK2GRRLeK6pI,193
+edge_sync/client.py,sha256=Fz6nBMo5wINa434zF1cuK8UA-_E7vUo-HKnlXFCS-YM,10831
+edge_sync/queue.py,sha256=CaNz_pMPs8nA23AxFbjwyTZ6YM6mz5C7LK0iL-Pv78g,3085
+edge_sync/sync_policy.py,sha256=PaEfwhqyRmD_ddswssft04-eNo40EvZFxwlxzwsiA7g,2086
+edge_sync/integrations/__init__.py,sha256=M-haAybvUMRESDNQ0-OewE6zX86aSgs8uS1JeNk3GWU,252
+edge_sync/integrations/raspberry_pi.py,sha256=anoAxXv88xN-cKlzyCUygV-kmqcl5u2EYdgFHxWvuGo,3896
+edge_sync/integrations/solar_race.py,sha256=TjMmVZZ11DOz7Vx9YdS13AcUrNwUrGCfY5jFtULBCmw,6030
+edge_sync_sdk-0.1.0.dist-info/METADATA,sha256=43Dmut1tmdhEsaf4yQUkJvNahaK2SccYi-t3VPzuMk8,16370
+edge_sync_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+edge_sync_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=GbvURq0hC1Cc6LFkw4MGZlUt-71bi5gx6BZT6rWup68,1070
+edge_sync_sdk-0.1.0.dist-info/RECORD,,

edge_sync_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

edge_sync_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Rosenblit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.