tescmd 0.1.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

tescmd/telemetry/cache_sink.py

@@ -0,0 +1,154 @@
+"""Cache-warming telemetry sink.
+
+Receives decoded telemetry frames, translates field values via
+:class:`~tescmd.telemetry.mapper.TelemetryMapper`, and merges them into
+a :class:`~tescmd.cache.response_cache.ResponseCache`.  This keeps the
+MCP tool cache warm so read operations are free while telemetry is active.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tescmd.cache.response_cache import ResponseCache
+    from tescmd.telemetry.decoder import TelemetryFrame
+    from tescmd.telemetry.mapper import TelemetryMapper
+
+logger = logging.getLogger(__name__)
+
+
+def _deep_set(target: dict[str, Any], dotted_path: str, value: Any) -> None:
+    """Set a value in a nested dict using a dotted path.
+
+    Creates intermediate dicts as needed.
+
+    >>> d: dict[str, Any] = {}
+    >>> _deep_set(d, "charge_state.battery_level", 80)
+    >>> d
+    {'charge_state': {'battery_level': 80}}
+    """
+    keys = dotted_path.split(".")
+    for key in keys[:-1]:
+        if key not in target or not isinstance(target[key], dict):
+            target[key] = {}
+        target = target[key]
+    target[keys[-1]] = value
+
+
+def _deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> None:
+    """Recursively merge *overlay* into *base* (mutates *base*).
+
+    Dict values are merged recursively; all other values are overwritten.
+    """
+    for key, value in overlay.items():
+        if key in base and isinstance(base[key], dict) and isinstance(value, dict):
+            _deep_merge(base[key], value)
+        else:
+            base[key] = value
+
+
+class CacheSink:
+    """Telemetry sink that warms the response cache.
+
+    Accumulates telemetry updates in a buffer and flushes them to the
+    :class:`ResponseCache` at a configurable interval.  While active,
+    cached data is given a generous TTL so MCP reads don't trigger API
+    requests.
+
+    Parameters:
+        cache: The file-based response cache to write into.
+        mapper: Field mapper for telemetry → VehicleData translation.
+        vin: Vehicle VIN to cache data for.
+        flush_interval: Minimum seconds between disk flushes.
+        telemetry_ttl: TTL in seconds for cache entries while streaming.
+    """
+
+    def __init__(
+        self,
+        cache: ResponseCache,
+        mapper: TelemetryMapper,
+        vin: str,
+        *,
+        flush_interval: float = 1.0,
+        telemetry_ttl: int = 120,
+    ) -> None:
+        self._cache = cache
+        self._mapper = mapper
+        self._vin = vin
+        self._flush_interval = flush_interval
+        self._telemetry_ttl = telemetry_ttl
+        self._pending: dict[str, Any] = {}
+        self._last_flush: float = float("-inf")
+        self._frame_count: int = 0
+        self._field_count: int = 0
+
+    @property
+    def frame_count(self) -> int:
+        """Total frames processed."""
+        return self._frame_count
+
+    @property
+    def field_count(self) -> int:
+        """Total field updates applied to cache."""
+        return self._field_count
+
+    @property
+    def pending_count(self) -> int:
+        """Number of buffered updates not yet flushed."""
+        return self._count_leaves(self._pending)
+
+    async def on_frame(self, frame: TelemetryFrame) -> None:
+        """Process a decoded telemetry frame into the cache buffer.
+
+        Skips frames for other VINs. Maps each datum through the
+        :class:`TelemetryMapper` and buffers the results for the next
+        flush cycle.
+        """
+        if frame.vin != self._vin:
+            return
+
+        self._frame_count += 1
+
+        for datum in frame.data:
+            for path, value in self._mapper.map(datum.field_name, datum.value):
+                _deep_set(self._pending, path, value)
+                self._field_count += 1
+
+        now = time.monotonic()
+        if now - self._last_flush >= self._flush_interval:
+            self.flush()
+            self._last_flush = now
+
+    def flush(self) -> None:
+        """Merge buffered updates into the response cache immediately.
+
+        Called automatically during ``on_frame`` when the flush interval
+        has elapsed, or manually for cleanup / testing.
+        """
+        if not self._pending:
+            return
+
+        # Read-modify-write: merge into existing cached data
+        existing = self._cache.get(self._vin)
+        blob: dict[str, Any] = existing.data if existing else {"vin": self._vin, "state": "online"}
+
+        _deep_merge(blob, self._pending)
+        self._cache.put(self._vin, blob, ttl=self._telemetry_ttl)
+        self._cache.put_wake_state(self._vin, "online", ttl=self._telemetry_ttl)
+        self._pending.clear()
+
+        logger.debug("Cache flushed for %s (%d fields)", self._vin, self._field_count)
+
+    @staticmethod
+    def _count_leaves(d: dict[str, Any]) -> int:
+        """Count leaf (non-dict) values in a nested dict."""
+        count = 0
+        for v in d.values():
+            if isinstance(v, dict):
+                count += CacheSink._count_leaves(v)
+            else:
+                count += 1
+        return count

tescmd/telemetry/csv_sink.py

@@ -0,0 +1,180 @@
+"""Wide-format CSV log sink for vehicle telemetry.
+
+Writes one row per telemetry frame with one column per subscribed field.
+The header extends dynamically as new fields are discovered.
+
+Output format::
+
+    timestamp,vin,BatteryLevel,ChargeLimitSoc,InsideTemp,...
+    2026-02-01T12:34:55Z,5YJ3E...,80,90,22.5,...
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tescmd.telemetry.decoder import TelemetryFrame
+
+logger = logging.getLogger(__name__)
+
+# Fixed columns that always appear first.
+_FIXED_COLUMNS = ("timestamp", "vin")
+
+# Flush to disk every N frames for crash safety.
+_FLUSH_INTERVAL = 10
+
+
+def create_log_path(vin: str, config_dir: Path | None = None) -> Path:
+    """Build a timestamped CSV log path under the config directory.
+
+    Returns a path like ``~/.config/tescmd/logs/serve-{VIN}-{YYYYMMDD-HHMMSS}.csv``.
+    Creates the ``logs/`` subdirectory if it does not exist.
+    """
+    if config_dir is None:
+        config_dir = Path.home() / ".config" / "tescmd"
+    log_dir = config_dir / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    return log_dir / f"serve-{vin}-{stamp}.csv"
+
+
+class CSVLogSink:
+    """Telemetry sink that writes wide-format CSV.
+
+    Raw API values are written without unit conversion (Celsius, miles, bar)
+    so the CSV is a faithful record of what the vehicle reported.
+
+    Parameters:
+        path: Destination CSV file path.
+        vin: Only log frames matching this VIN (``None`` = log all).
+    """
+
+    def __init__(self, path: Path, vin: str | None = None) -> None:
+        import atexit
+
+        self._path = path
+        self._vin = vin
+        self._fh: IO[str] | None = None
+        self._writer: csv.DictWriter[str] | None = None
+        self._fieldnames: list[str] = list(_FIXED_COLUMNS)
+        self._frame_count: int = 0
+        self._since_flush: int = 0
+        atexit.register(self.close)
+
+    # -- Properties -----------------------------------------------------------
+
+    @property
+    def log_path(self) -> Path:
+        """The CSV file path."""
+        return self._path
+
+    @property
+    def frame_count(self) -> int:
+        """Total frames written."""
+        return self._frame_count
+
+    # -- Sink callback --------------------------------------------------------
+
+    async def on_frame(self, frame: TelemetryFrame) -> None:
+        """Write a single telemetry frame as a CSV row.
+
+        Called by :class:`~tescmd.telemetry.fanout.FrameFanout`.
+        Frames for other VINs are silently skipped.
+        """
+        if self._vin is not None and frame.vin != self._vin:
+            return
+
+        # Build the row dict from frame data.
+        row: dict[str, Any] = {
+            "timestamp": frame.created_at.isoformat(),
+            "vin": frame.vin,
+        }
+        for datum in frame.data:
+            value = datum.value
+            # Flatten location dicts to a string representation.
+            if isinstance(value, dict):
+                value = ";".join(f"{k}={v}" for k, v in value.items())
+            row[datum.field_name] = value
+
+        # Discover new fields and rewrite the header if needed.
+        new_fields = [f for f in row if f not in self._fieldnames]
+        if new_fields:
+            self._fieldnames.extend(new_fields)
+            if self._fh is not None:
+                self._rewrite_header()
+
+        # Lazily open the file on the first frame.
+        if self._fh is None:
+            self._open()
+
+        assert self._writer is not None
+        self._writer.writerow(row)
+        self._frame_count += 1
+        self._since_flush += 1
+
+        if self._since_flush >= _FLUSH_INTERVAL:
+            self._flush()
+
+    # -- Lifecycle ------------------------------------------------------------
+
+    def close(self) -> None:
+        """Flush and close the CSV file."""
+        if self._fh is not None:
+            self._flush()
+            self._fh.close()
+            self._fh = None
+            self._writer = None
+
+    # -- Internals ------------------------------------------------------------
+
+    def _open(self) -> None:
+        """Open the CSV file and write the initial header."""
+        self._fh = open(self._path, "w", newline="", encoding="utf-8")  # noqa: SIM115
+        self._writer = csv.DictWriter(
+            self._fh,
+            fieldnames=self._fieldnames,
+            extrasaction="ignore",
+        )
+        self._writer.writeheader()
+
+    def _rewrite_header(self) -> None:
+        """Rewrite the file with the expanded header, preserving existing rows.
+
+        This is called when a new telemetry field is discovered mid-stream.
+        The approach is: read existing content, rewrite with new fieldnames.
+        """
+        if self._fh is None:
+            return
+
+        self._fh.flush()
+        self._fh.close()
+
+        # Read existing rows.
+        rows: list[dict[str, str]] = []
+        with open(self._path, newline="", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+            for r in reader:
+                rows.append(r)
+
+        # Rewrite with expanded header.
+        self._fh = open(self._path, "w", newline="", encoding="utf-8")  # noqa: SIM115
+        self._writer = csv.DictWriter(
+            self._fh,
+            fieldnames=self._fieldnames,
+            extrasaction="ignore",
+        )
+        self._writer.writeheader()
+        for r in rows:
+            self._writer.writerow(r)
+
+    def _flush(self) -> None:
+        """Flush the file handle to disk."""
+        if self._fh is not None:
+            self._fh.flush()
+            self._since_flush = 0

tescmd/telemetry/dashboard.py

@@ -0,0 +1,227 @@
+"""Rich Live TUI dashboard for real-time telemetry display."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from rich.console import Console, RenderableType
+    from rich.live import Live
+
+    from tescmd.output.rich_output import DisplayUnits
+    from tescmd.telemetry.decoder import TelemetryFrame
+
+
+class TelemetryDashboard:
+    """Rich Live TUI renderer for streaming telemetry data."""
+
+    def __init__(self, console: Console, units: DisplayUnits) -> None:
+        self._console = console
+        self._units = units
+        self._state: dict[str, Any] = {}
+        self._timestamps: dict[str, datetime] = {}
+        self._frame_count: int = 0
+        self._vin: str = ""
+        self._started_at: datetime = datetime.now(tz=UTC)
+        self._live: Live | None = None
+        self._connected: bool = False
+        self._tunnel_url: str = ""
+
+    def update(self, frame: TelemetryFrame) -> None:
+        """Ingest a telemetry frame and refresh the display."""
+        self._frame_count += 1
+        self._connected = True
+        if frame.vin:
+            self._vin = frame.vin
+
+        for datum in frame.data:
+            self._state[datum.field_name] = datum.value
+            self._timestamps[datum.field_name] = frame.created_at
+
+        # Trigger an immediate refresh so data appears without waiting for the
+        # next auto-refresh tick.  We do NOT call live.update(self.render())
+        # because that would replace the Live renderable with a static snapshot,
+        # breaking the uptime counter between frames.  The Live object already
+        # holds a reference to `self` (via __rich__), so refresh() re-renders
+        # the dashboard with the freshly updated state.
+        if self._live is not None:
+            self._live.refresh()
+
+    def set_live(self, live: Live) -> None:
+        """Attach a Rich Live instance for auto-refresh."""
+        self._live = live
+
+    def set_tunnel_url(self, url: str) -> None:
+        """Set the tunnel URL for display."""
+        self._tunnel_url = url
+
+    def __rich__(self) -> RenderableType:
+        """Allow Rich Live to call render() on every refresh tick."""
+        return self.render()
+
+    def render(self) -> RenderableType:
+        """Build the full dashboard renderable."""
+        from rich.console import Group
+
+        parts: list[RenderableType] = []
+
+        # Header panel
+        parts.append(self._render_header())
+
+        # Data table
+        if self._state:
+            parts.append(self._render_data_table())
+        else:
+            parts.append(
+                Panel(
+                    "[dim]Waiting for telemetry data...[/dim]",
+                    title="Telemetry Data",
+                    border_style="dim",
+                )
+            )
+
+        # Footer
+        parts.append(self._render_footer())
+
+        return Group(*parts)
+
+    def _render_header(self) -> Panel:
+        """Render the status header panel."""
+        now = datetime.now(tz=UTC)
+        uptime = now - self._started_at
+        hours, remainder = divmod(int(uptime.total_seconds()), 3600)
+        minutes, seconds = divmod(remainder, 60)
+
+        status_style = "green" if self._connected else "yellow"
+        status_text = "Connected" if self._connected else "Waiting"
+
+        header = Text()
+        header.append("VIN: ", style="bold")
+        header.append(self._vin or "(waiting)", style="cyan")
+        header.append("  |  Status: ", style="bold")
+        header.append(status_text, style=status_style)
+        header.append("  |  Frames: ", style="bold")
+        header.append(str(self._frame_count), style="cyan")
+        header.append("  |  Uptime: ", style="bold")
+        header.append(f"{hours:02d}:{minutes:02d}:{seconds:02d}", style="cyan")
+
+        return Panel(header, title="Fleet Telemetry Stream", border_style="blue")
+
+    def _render_data_table(self) -> Table:
+        """Render the telemetry data table."""
+        table = Table(title="Telemetry Data", expand=True)
+        table.add_column("Field", style="bold", no_wrap=True)
+        table.add_column("Value", style="cyan")
+        table.add_column("Last Update", style="dim", no_wrap=True)
+
+        for field_name in sorted(self._state.keys()):
+            value = self._state[field_name]
+            display_value = self._format_value(field_name, value)
+            ts = self._timestamps.get(field_name)
+            ts_str = ts.strftime("%H:%M:%S") if ts else ""
+            table.add_row(field_name, display_value, ts_str)
+
+        return table
+
+    def _render_footer(self) -> Text:
+        """Render the footer with stream URL and exit hint."""
+        footer = Text()
+        if self._tunnel_url:
+            footer.append("  Stream: ", style="dim")
+            footer.append(self._tunnel_url, style="dim cyan")
+            footer.append("  |  ", style="dim")
+        footer.append("Press q or Ctrl+C to stop", style="dim")
+        return footer
+
+    def _format_value(self, field_name: str, value: Any) -> str:
+        """Format a telemetry value with unit conversion where applicable."""
+        from tescmd.output.rich_output import DistanceUnit, PressureUnit, TempUnit
+
+        if value is None:
+            return "—"
+
+        if isinstance(value, dict):
+            # Location
+            lat = value.get("latitude", 0.0)
+            lng = value.get("longitude", 0.0)
+            return f"{lat:.6f}, {lng:.6f}"
+
+        if isinstance(value, bool):
+            return "Yes" if value else "No"
+
+        # Temperature fields (API returns Celsius)
+        temp_fields = {
+            "InsideTemp",
+            "OutsideTemp",
+            "HvacLeftTemperatureRequest",
+            "HvacRightTemperatureRequest",
+            "ModuleTempMax",
+            "ModuleTempMin",
+        }
+        if field_name in temp_fields and isinstance(value, (int, float)):
+            if self._units.temp == TempUnit.F:
+                return f"{value * 9 / 5 + 32:.1f}°F"
+            return f"{value:.1f}°C"
+
+        # Distance fields (API returns miles)
+        distance_fields = {
+            "Odometer",
+            "EstBatteryRange",
+            "IdealBatteryRange",
+            "RatedRange",
+            "MilesToArrival",
+        }
+        if field_name in distance_fields and isinstance(value, (int, float)):
+            if self._units.distance == DistanceUnit.KM:
+                return f"{value * 1.60934:.1f} km"
+            return f"{value:.1f} mi"
+
+        # Speed fields (API returns mph)
+        speed_fields = {"VehicleSpeed", "CruiseSetSpeed", "CurrentLimitMph"}
+        if field_name in speed_fields and isinstance(value, (int, float)):
+            if self._units.distance == DistanceUnit.KM:
+                return f"{value * 1.60934:.0f} km/h"
+            return f"{value:.0f} mph"
+
+        # Pressure fields (API returns bar)
+        pressure_fields = {
+            "TpmsPressureFl",
+            "TpmsPressureFr",
+            "TpmsPressureRl",
+            "TpmsPressureRr",
+        }
+        if field_name in pressure_fields and isinstance(value, (int, float)):
+            if self._units.pressure == PressureUnit.PSI:
+                return f"{value * 14.5038:.1f} psi"
+            return f"{value:.2f} bar"
+
+        # Percentage fields
+        pct_fields = {"Soc", "BatteryLevel", "ChargeLimitSoc"}
+        if field_name in pct_fields and isinstance(value, (int, float)):
+            return f"{value}%"
+
+        # Voltage / current
+        if "Voltage" in field_name and isinstance(value, (int, float)):
+            return f"{value:.1f} V"
+        if ("Current" in field_name or "Amps" in field_name) and isinstance(value, (int, float)):
+            return f"{value:.1f} A"
+
+        # Power
+        if "Power" in field_name and isinstance(value, (int, float)):
+            return f"{value:.2f} kW"
+
+        # Time-to-full
+        if field_name == "TimeToFullCharge" and isinstance(value, (int, float)):
+            hours = int(value)
+            mins = int((value - hours) * 60)
+            return f"{hours}h {mins}m" if hours else f"{mins}m"
+
+        if isinstance(value, float):
+            return f"{value:.2f}"
+
+        return str(value)