tescmd 0.2.0__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

@@ -158,8 +158,8 @@ class TelemetryDashboard:
         temp_fields = {
             "InsideTemp",
             "OutsideTemp",
-            "DriverTempSetting",
-            "PassengerTempSetting",
+            "HvacLeftTemperatureRequest",
+            "HvacRightTemperatureRequest",
             "ModuleTempMax",
             "ModuleTempMin",
         }
@@ -173,7 +173,7 @@ class TelemetryDashboard:
             "Odometer",
             "EstBatteryRange",
             "IdealBatteryRange",
-            "RatedBatteryRange",
+            "RatedRange",
             "MilesToArrival",
         }
         if field_name in distance_fields and isinstance(value, (int, float)):
@@ -182,7 +182,7 @@ class TelemetryDashboard:
             return f"{value:.1f} mi"
 
         # Speed fields (API returns mph)
-        speed_fields = {"VehicleSpeed", "CruiseSetSpeed", "MaxSpeedLimit"}
+        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"

tescmd/telemetry/fanout.py

@@ -0,0 +1,49 @@
+"""Fan-out dispatcher for telemetry frames.
+
+Multiplexes a single ``on_frame`` callback to N sinks, each error-isolated.
+One sink failing does not affect others.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from tescmd.telemetry.decoder import TelemetryFrame
+
+logger = logging.getLogger(__name__)
+
+
+class FrameFanout:
+    """Fan-out dispatcher: delivers each telemetry frame to all registered sinks."""
+
+    def __init__(self) -> None:
+        self._sinks: list[Callable[[TelemetryFrame], Awaitable[None]]] = []
+
+    def add_sink(self, callback: Callable[[TelemetryFrame], Awaitable[None]]) -> None:
+        """Register a sink to receive telemetry frames."""
+        self._sinks.append(callback)
+
+    @property
+    def sink_count(self) -> int:
+        """Number of registered sinks."""
+        return len(self._sinks)
+
+    def has_sinks(self) -> bool:
+        """Return ``True`` if at least one sink is registered."""
+        return len(self._sinks) > 0
+
+    async def on_frame(self, frame: TelemetryFrame) -> None:
+        """Dispatch *frame* to all registered sinks.
+
+        Each sink is called independently. If a sink raises, the exception
+        is logged and the remaining sinks still receive the frame.
+        """
+        for sink in self._sinks:
+            try:
+                await sink(frame)
+            except Exception:
+                logger.warning("Sink %s failed for frame", sink, exc_info=True)