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

tescmd/openclaw/emitter.py

@@ -0,0 +1,175 @@
+"""Transform telemetry data into OpenClaw ``req:agent`` event payloads.
+
+Maps Tesla Fleet Telemetry field names to OpenClaw event types as defined
+in the PRD:
+
+- ``Location``        → ``location``      {latitude, longitude, heading, speed}
+- ``Soc``             → ``battery``        {battery_level, range_miles}
+- ``InsideTemp``      → ``inside_temp``    {inside_temp_f}
+- ``OutsideTemp``     → ``outside_temp``   {outside_temp_f}
+- ``VehicleSpeed``    → ``speed``          {speed_mph}
+- ``ChargeState``     → ``charge_started`` / ``charge_complete`` / ``charge_stopped``
+- ``DetailedChargeState`` → same as ChargeState
+- ``Locked`` / ``SentryMode`` → ``security_changed``
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+
+def _celsius_to_fahrenheit(c: float) -> float:
+    return c * 9.0 / 5.0 + 32.0
+
+
+class EventEmitter:
+    """Stateless transformer: telemetry datum → OpenClaw req:agent payload.
+
+    Returns ``None`` for fields that don't map to an event type.
+    """
+
+    def __init__(self, client_id: str = "node-host") -> None:
+        self._client_id = client_id
+
+    def to_event(
+        self,
+        field_name: str,
+        value: Any,
+        vin: str,
+        timestamp: datetime | None = None,
+    ) -> dict[str, Any] | None:
+        """Convert a single telemetry datum to an OpenClaw event dict.
+
+        Returns ``None`` if the field doesn't map to an event type.
+        """
+        ts = timestamp or datetime.now(UTC)
+        ts_iso = ts.isoformat()
+
+        payload = self._build_payload(field_name, value)
+        if payload is None:
+            return None
+
+        event_type = payload.pop("_event_type")
+
+        return {
+            "method": "req:agent",
+            "params": {
+                "event_type": event_type,
+                "source": self._client_id,
+                "vin": vin,
+                "timestamp": ts_iso,
+                "data": payload,
+            },
+        }
+
+    def _build_payload(self, field_name: str, value: Any) -> dict[str, Any] | None:
+        """Build event-specific payload. Returns None for unmapped fields."""
+        if field_name == "Location":
+            return self._location_payload(value)
+        if field_name == "Soc":
+            return self._battery_payload(value)
+        if field_name in ("InsideTemp", "OutsideTemp"):
+            return self._temp_payload(field_name, value)
+        if field_name == "VehicleSpeed":
+            return self._speed_payload(value)
+        if field_name in ("ChargeState", "DetailedChargeState"):
+            return self._charge_state_payload(value)
+        if field_name in ("Locked", "SentryMode"):
+            return self._security_payload(field_name, value)
+        if field_name == "BatteryLevel":
+            return self._battery_level_payload(value)
+        if field_name == "EstBatteryRange":
+            return self._range_payload(value)
+        if field_name == "Gear":
+            return self._gear_payload(value)
+        return None
+
+    def _location_payload(self, value: Any) -> dict[str, Any] | None:
+        try:
+            return {
+                "_event_type": "location",
+                "latitude": float(value["latitude"]),
+                "longitude": float(value["longitude"]),
+                "heading": float(value.get("heading", 0)),
+                "speed": float(value.get("speed", 0)),
+            }
+        except (TypeError, KeyError, ValueError):
+            return None
+
+    def _battery_payload(self, value: Any) -> dict[str, Any] | None:
+        try:
+            return {
+                "_event_type": "battery",
+                "battery_level": float(value),
+            }
+        except (TypeError, ValueError):
+            return None
+
+    def _temp_payload(self, field_name: str, value: Any) -> dict[str, Any] | None:
+        try:
+            temp_c = float(value)
+            temp_f = _celsius_to_fahrenheit(temp_c)
+            event_type = "inside_temp" if field_name == "InsideTemp" else "outside_temp"
+            key = f"{event_type}_f"
+            return {
+                "_event_type": event_type,
+                key: round(temp_f, 1),
+            }
+        except (TypeError, ValueError):
+            return None
+
+    def _speed_payload(self, value: Any) -> dict[str, Any] | None:
+        try:
+            return {
+                "_event_type": "speed",
+                "speed_mph": float(value),
+            }
+        except (TypeError, ValueError):
+            return None
+
+    def _charge_state_payload(self, value: Any) -> dict[str, Any] | None:
+        state = str(value).lower()
+        if "charging" in state or state == "starting":
+            event_type = "charge_started"
+        elif "complete" in state:
+            event_type = "charge_complete"
+        elif "stopped" in state or "disconnected" in state:
+            event_type = "charge_stopped"
+        else:
+            event_type = "charge_state_changed"
+        return {
+            "_event_type": event_type,
+            "state": str(value),
+        }
+
+    def _security_payload(self, field_name: str, value: Any) -> dict[str, Any] | None:
+        return {
+            "_event_type": "security_changed",
+            "field": field_name.lower(),
+            "value": value,
+        }
+
+    def _battery_level_payload(self, value: Any) -> dict[str, Any] | None:
+        try:
+            return {
+                "_event_type": "battery",
+                "battery_level": float(value),
+            }
+        except (TypeError, ValueError):
+            return None
+
+    def _range_payload(self, value: Any) -> dict[str, Any] | None:
+        try:
+            return {
+                "_event_type": "battery",
+                "range_miles": float(value),
+            }
+        except (TypeError, ValueError):
+            return None
+
+    def _gear_payload(self, value: Any) -> dict[str, Any] | None:
+        return {
+            "_event_type": "gear_changed",
+            "gear": str(value),
+        }

tescmd/openclaw/filters.py

@@ -0,0 +1,123 @@
+"""Dual-gate filter for telemetry field emission.
+
+Both conditions must pass for a field to be emitted:
+
+1. **Delta gate** — the value has changed beyond a field-specific granularity
+   threshold since the last emitted value.
+2. **Throttle gate** — enough time has elapsed since the last emission.
+
+Fields with ``granularity=0`` emit on any value change (state fields like
+``ChargeState``, ``Locked``).  Fields with ``throttle_seconds=0`` have no
+time constraint.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tescmd.openclaw.config import FieldFilter
+
+
+def haversine(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Haversine distance in meters between two WGS-84 coordinates.
+
+    Pure stdlib implementation — no external dependencies.
+    """
+    r = 6_371_000.0  # Earth radius in meters
+    dlat = math.radians(lat2 - lat1)
+    dlon = math.radians(lon2 - lon1)
+    a = (
+        math.sin(dlat / 2) ** 2
+        + math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) * math.sin(dlon / 2) ** 2
+    )
+    return r * 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+
+
+def _numeric_delta(old: Any, new: Any) -> float:
+    """Absolute difference between two numeric values."""
+    try:
+        return abs(float(new) - float(old))
+    except (TypeError, ValueError):
+        # Non-numeric — treat as changed
+        return float("inf")
+
+
+def _location_delta(old: Any, new: Any) -> float:
+    """Distance in meters between two location values.
+
+    Location values are expected as ``{"latitude": float, "longitude": float}``.
+    """
+    try:
+        return haversine(
+            old["latitude"],
+            old["longitude"],
+            new["latitude"],
+            new["longitude"],
+        )
+    except (TypeError, KeyError, ValueError):
+        return float("inf")
+
+
+# Fields that use location-based delta comparison
+_LOCATION_FIELDS: frozenset[str] = frozenset({"Location"})
+
+
+class DualGateFilter:
+    """Dual-gate emission filter combining delta + throttle logic.
+
+    Usage::
+
+        filt = DualGateFilter(field_filters)
+        if filt.should_emit("Soc", 72, time.monotonic()):
+            filt.record_emit("Soc", 72, time.monotonic())
+            # ... emit the event
+    """
+
+    def __init__(self, filters: dict[str, FieldFilter]) -> None:
+        self._filters = filters
+        self._last_values: dict[str, Any] = {}
+        self._last_emit_times: dict[str, float] = {}
+
+    def should_emit(self, field: str, value: Any, now: float) -> bool:
+        """Check whether a field value passes both gates.
+
+        Returns ``True`` if the value should be emitted downstream.
+        """
+        cfg = self._filters.get(field)
+        if cfg is None or not cfg.enabled:
+            return False
+
+        # Throttle gate: enforce minimum interval
+        if cfg.throttle_seconds > 0:
+            last_time = self._last_emit_times.get(field)
+            if last_time is not None and (now - last_time) < cfg.throttle_seconds:
+                return False
+
+        # Delta gate: value must have changed beyond granularity
+        last_value = self._last_values.get(field)
+        if last_value is None:
+            # First value for this field — always emit
+            return True
+
+        if field in _LOCATION_FIELDS:
+            delta = _location_delta(last_value, value)
+        else:
+            delta = _numeric_delta(last_value, value)
+
+        # granularity=0 means any change triggers emission
+        if cfg.granularity == 0:
+            return bool(value != last_value)
+
+        return delta >= cfg.granularity
+
+    def record_emit(self, field: str, value: Any, now: float) -> None:
+        """Record that a value was emitted (call after ``should_emit`` returns True)."""
+        self._last_values[field] = value
+        self._last_emit_times[field] = now
+
+    def reset(self) -> None:
+        """Clear all tracked state."""
+        self._last_values.clear()
+        self._last_emit_times.clear()