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

tescmd/telemetry/mapper.py

@@ -0,0 +1,239 @@
+"""Shared telemetry field -> VehicleData path mapping.
+
+Translates Fleet Telemetry proto field names (e.g. ``"Soc"``, ``"Location"``)
+into structured VehicleData paths (e.g. ``"charge_state.usable_battery_level"``).
+Used by :class:`~tescmd.telemetry.cache_sink.CacheSink` for cache warming
+and available for any consumer that needs to map telemetry into the
+VehicleData JSON structure.
+
+Keys match the ``vehicle_data.proto`` Field enum names exactly.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_lat(value: Any) -> float | None:
+    """Extract latitude from a Location value dict."""
+    try:
+        return float(value["latitude"])
+    except (TypeError, KeyError, ValueError):
+        return None
+
+
+def _extract_lon(value: Any) -> float | None:
+    """Extract longitude from a Location value dict."""
+    try:
+        return float(value["longitude"])
+    except (TypeError, KeyError, ValueError):
+        return None
+
+
+def _to_int(value: Any) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if isinstance(value, str):
+        return value.lower() in ("true", "1", "yes")
+    return None
+
+
+def _to_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _gear_str(value: Any) -> str | None:
+    """Map gear enum values to the API's shift_state strings."""
+    s = str(value) if value is not None else ""
+    mapping = {
+        "P": "P",
+        "Park": "P",
+        "R": "R",
+        "Reverse": "R",
+        "N": "N",
+        "Neutral": "N",
+        "D": "D",
+        "Drive": "D",
+        "DriveSport": "D",
+    }
+    return mapping.get(s, s or None)
+
+
+@dataclass(frozen=True)
+class FieldMapping:
+    """Maps a telemetry field to a VehicleData JSON path."""
+
+    path: str
+    """Dotted path into VehicleData (e.g. ``"charge_state.battery_level"``)."""
+
+    transform: Any
+    """Callable ``(value) -> transformed_value``. Returns ``None`` to skip."""
+
+
+# ---------------------------------------------------------------------------
+# Master field map: proto field name -> list of VehicleData path mappings
+#
+# Keys are vehicle_data.proto Field enum names.
+# ---------------------------------------------------------------------------
+
+TELEMETRY_FIELD_MAP: dict[str, list[FieldMapping]] = {
+    # -- charge_state --
+    "Soc": [FieldMapping("charge_state.usable_battery_level", _to_int)],
+    "BatteryLevel": [FieldMapping("charge_state.battery_level", _to_int)],
+    "ChargeState": [FieldMapping("charge_state.charging_state", _to_str)],
+    "DetailedChargeState": [FieldMapping("charge_state.charge_port_latch", _to_str)],
+    "EstBatteryRange": [FieldMapping("charge_state.est_battery_range", _to_float)],
+    "IdealBatteryRange": [FieldMapping("charge_state.ideal_battery_range", _to_float)],
+    "RatedRange": [FieldMapping("charge_state.battery_range", _to_float)],
+    "ChargerVoltage": [FieldMapping("charge_state.charger_voltage", _to_int)],
+    "ChargeAmps": [FieldMapping("charge_state.charge_amps", _to_int)],
+    "ChargerPhases": [FieldMapping("charge_state.charger_phases", _to_int)],
+    "ChargeLimitSoc": [FieldMapping("charge_state.charge_limit_soc", _to_int)],
+    "ChargeCurrentRequest": [FieldMapping("charge_state.charge_current_request", _to_int)],
+    "ChargeCurrentRequestMax": [
+        FieldMapping("charge_state.charge_current_request_max", _to_int),
+    ],
+    "ChargePortDoorOpen": [FieldMapping("charge_state.charge_port_door_open", _to_bool)],
+    "ChargePortLatch": [FieldMapping("charge_state.charge_port_latch", _to_str)],
+    "TimeToFullCharge": [FieldMapping("charge_state.time_to_full_charge", _to_float)],
+    "ACChargingPower": [FieldMapping("charge_state.charger_power", _to_float)],
+    "ACChargingEnergyIn": [FieldMapping("charge_state.charge_energy_added", _to_float)],
+    "FastChargerPresent": [FieldMapping("charge_state.fast_charger_present", _to_bool)],
+    "ScheduledChargingMode": [
+        FieldMapping("charge_state.scheduled_charging_mode", _to_str),
+    ],
+    "ScheduledChargingPending": [
+        FieldMapping("charge_state.scheduled_charging_pending", _to_bool),
+    ],
+    "ScheduledChargingStartTime": [
+        FieldMapping("charge_state.scheduled_charging_start_time", _to_float),
+    ],
+    "ScheduledDepartureTime": [
+        FieldMapping("charge_state.scheduled_departure_time_minutes", _to_int),
+    ],
+    "EnergyRemaining": [FieldMapping("charge_state.energy_remaining", _to_float)],
+    "PackVoltage": [FieldMapping("charge_state.pack_voltage", _to_float)],
+    "PackCurrent": [FieldMapping("charge_state.pack_current", _to_float)],
+    "ChargingCableType": [FieldMapping("charge_state.conn_charge_cable", _to_str)],
+    # -- climate_state --
+    "InsideTemp": [FieldMapping("climate_state.inside_temp", _to_float)],
+    "OutsideTemp": [FieldMapping("climate_state.outside_temp", _to_float)],
+    "HvacLeftTemperatureRequest": [
+        FieldMapping("climate_state.driver_temp_setting", _to_float),
+    ],
+    "HvacRightTemperatureRequest": [
+        FieldMapping("climate_state.passenger_temp_setting", _to_float),
+    ],
+    "HvacPower": [FieldMapping("climate_state.is_climate_on", _to_bool)],
+    "HvacFanStatus": [FieldMapping("climate_state.fan_status", _to_int)],
+    "SeatHeaterLeft": [FieldMapping("climate_state.seat_heater_left", _to_int)],
+    "SeatHeaterRight": [FieldMapping("climate_state.seat_heater_right", _to_int)],
+    "SeatHeaterRearLeft": [FieldMapping("climate_state.seat_heater_rear_left", _to_int)],
+    "SeatHeaterRearCenter": [
+        FieldMapping("climate_state.seat_heater_rear_center", _to_int),
+    ],
+    "SeatHeaterRearRight": [FieldMapping("climate_state.seat_heater_rear_right", _to_int)],
+    "HvacSteeringWheelHeatLevel": [
+        FieldMapping("climate_state.steering_wheel_heater", _to_bool),
+    ],
+    "DefrostMode": [FieldMapping("climate_state.defrost_mode", _to_int)],
+    "CabinOverheatProtectionMode": [
+        FieldMapping("climate_state.cabin_overheat_protection", _to_str),
+    ],
+    "PreconditioningEnabled": [
+        FieldMapping("climate_state.is_preconditioning", _to_bool),
+    ],
+    # -- drive_state --
+    "Location": [
+        FieldMapping("drive_state.latitude", _extract_lat),
+        FieldMapping("drive_state.longitude", _extract_lon),
+    ],
+    "VehicleSpeed": [FieldMapping("drive_state.speed", _to_int)],
+    "GpsHeading": [FieldMapping("drive_state.heading", _to_int)],
+    "Gear": [FieldMapping("drive_state.shift_state", _gear_str)],
+    # -- vehicle_state --
+    "Locked": [FieldMapping("vehicle_state.locked", _to_bool)],
+    "SentryMode": [FieldMapping("vehicle_state.sentry_mode", _to_bool)],
+    "Odometer": [FieldMapping("vehicle_state.odometer", _to_float)],
+    "Version": [FieldMapping("vehicle_state.car_version", _to_str)],
+    "ValetModeEnabled": [FieldMapping("vehicle_state.valet_mode", _to_bool)],
+    "TpmsPressureFl": [FieldMapping("vehicle_state.tpms_pressure_fl", _to_float)],
+    "TpmsPressureFr": [FieldMapping("vehicle_state.tpms_pressure_fr", _to_float)],
+    "TpmsPressureRl": [FieldMapping("vehicle_state.tpms_pressure_rl", _to_float)],
+    "TpmsPressureRr": [FieldMapping("vehicle_state.tpms_pressure_rr", _to_float)],
+    "CenterDisplay": [FieldMapping("vehicle_state.center_display_state", _to_int)],
+    "HomelinkNearby": [FieldMapping("vehicle_state.homelink_nearby", _to_bool)],
+    "DriverSeatOccupied": [FieldMapping("vehicle_state.is_user_present", _to_bool)],
+    "RemoteStartEnabled": [FieldMapping("vehicle_state.remote_start", _to_bool)],
+}
+
+
+class TelemetryMapper:
+    """Maps telemetry field names to VehicleData paths.
+
+    Usage::
+
+        mapper = TelemetryMapper()
+        for path, value in mapper.map("Soc", 80):
+            # path = "charge_state.usable_battery_level", value = 80
+            ...
+    """
+
+    def __init__(
+        self,
+        field_map: dict[str, list[FieldMapping]] | None = None,
+    ) -> None:
+        self._field_map = field_map or TELEMETRY_FIELD_MAP
+
+    def map(self, field_name: str, value: Any) -> list[tuple[str, Any]]:
+        """Map a telemetry field to zero or more ``(path, transformed_value)`` pairs.
+
+        Returns an empty list if the field is unmapped or all transforms
+        return ``None``.
+        """
+        mappings = self._field_map.get(field_name)
+        if mappings is None:
+            return []
+
+        results: list[tuple[str, Any]] = []
+        for mapping in mappings:
+            try:
+                transformed = mapping.transform(value)
+            except Exception:
+                logger.debug(
+                    "Transform failed for %s -> %s",
+                    field_name,
+                    mapping.path,
+                    exc_info=True,
+                )
+                continue
+            if transformed is not None:
+                results.append((mapping.path, transformed))
+        return results
+
+    @property
+    def mapped_fields(self) -> frozenset[str]:
+        """Return the set of telemetry field names that have mappings."""
+        return frozenset(self._field_map.keys())

tescmd/telemetry/protos/__init__.py

@@ -0,0 +1,4 @@
+"""Generated protobuf bindings for Tesla Fleet Telemetry messages.
+
+Proto source: https://github.com/teslamotors/fleet-telemetry/tree/main/protos
+"""

tescmd/telemetry/protos/vehicle_alert.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package telemetry.vehicle_alerts;
+
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/teslamotors/fleet-telemetry/protos";
+
+
+// VehicleAlerts is a collection of recent alerts.
+message VehicleAlerts {
+  repeated VehicleAlert alerts = 1;
+  google.protobuf.Timestamp created_at = 2;
+  string vin = 3;
+}
+
+// Audience the target audience for the alert.
+enum Audience {
+  Unknown = 0;
+  Customer = 1;
+  Service = 2;
+  ServiceFix = 3;
+}
+
+// VehicleAlert is a single alert and is active if ended_at is nil.
+message VehicleAlert {
+  string name = 1;
+  repeated Audience audiences = 2;
+  google.protobuf.Timestamp started_at = 3;
+  google.protobuf.Timestamp ended_at = 4;
+}

tescmd/telemetry/protos/vehicle_alert_pb2.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: vehicle_alert.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'vehicle_alert.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x13vehicle_alert.proto\x12\x18telemetry.vehicle_alerts\x1a\x1fgoogle/protobuf/timestamp.proto\"\x84\x01\n\rVehicleAlerts\x12\x36\n\x06\x61lerts\x18\x01 \x03(\x0b\x32&.telemetry.vehicle_alerts.VehicleAlert\x12.\n\ncreated_at\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x0b\n\x03vin\x18\x03 \x01(\t\"\xb1\x01\n\x0cVehicleAlert\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x35\n\taudiences\x18\x02 \x03(\x0e\x32\".telemetry.vehicle_alerts.Audience\x12.\n\nstarted_at\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nded_at\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp*B\n\x08\x41udience\x12\x0b\n\x07Unknown\x10\x00\x12\x0c\n\x08\x43ustomer\x10\x01\x12\x0b\n\x07Service\x10\x02\x12\x0e\n\nServiceFix\x10\x03\x42/Z-github.com/teslamotors/fleet-telemetry/protosb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'vehicle_alert_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z-github.com/teslamotors/fleet-telemetry/protos'
+  _globals['_AUDIENCE']._serialized_start=397
+  _globals['_AUDIENCE']._serialized_end=463
+  _globals['_VEHICLEALERTS']._serialized_start=83
+  _globals['_VEHICLEALERTS']._serialized_end=215
+  _globals['_VEHICLEALERT']._serialized_start=218
+  _globals['_VEHICLEALERT']._serialized_end=395
+# @@protoc_insertion_point(module_scope)

tescmd/telemetry/protos/vehicle_alert_pb2.pyi

@@ -0,0 +1,44 @@
+import datetime
+
+from google.protobuf import timestamp_pb2 as _timestamp_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Audience(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    Unknown: _ClassVar[Audience]
+    Customer: _ClassVar[Audience]
+    Service: _ClassVar[Audience]
+    ServiceFix: _ClassVar[Audience]
+Unknown: Audience
+Customer: Audience
+Service: Audience
+ServiceFix: Audience
+
+class VehicleAlerts(_message.Message):
+    __slots__ = ("alerts", "created_at", "vin")
+    ALERTS_FIELD_NUMBER: _ClassVar[int]
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    VIN_FIELD_NUMBER: _ClassVar[int]
+    alerts: _containers.RepeatedCompositeFieldContainer[VehicleAlert]
+    created_at: _timestamp_pb2.Timestamp
+    vin: str
+    def __init__(self, alerts: _Optional[_Iterable[_Union[VehicleAlert, _Mapping]]] = ..., created_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., vin: _Optional[str] = ...) -> None: ...
+
+class VehicleAlert(_message.Message):
+    __slots__ = ("name", "audiences", "started_at", "ended_at")
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    AUDIENCES_FIELD_NUMBER: _ClassVar[int]
+    STARTED_AT_FIELD_NUMBER: _ClassVar[int]
+    ENDED_AT_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    audiences: _containers.RepeatedScalarFieldContainer[Audience]
+    started_at: _timestamp_pb2.Timestamp
+    ended_at: _timestamp_pb2.Timestamp
+    def __init__(self, name: _Optional[str] = ..., audiences: _Optional[_Iterable[_Union[Audience, str]]] = ..., started_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., ended_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ...) -> None: ...

tescmd/telemetry/protos/vehicle_connectivity.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package telemetry.vehicle_connectivity;
+
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/teslamotors/fleet-telemetry/protos";
+
+// VehicleConnectivity represents connection status change for the vehicle
+message VehicleConnectivity {
+  string vin = 1;
+  string connection_id = 2;
+  ConnectivityEvent status = 3;
+  google.protobuf.Timestamp created_at = 4;
+  string network_interface = 5;
+}
+
+// ConnectivityEvent represents connection state of the vehicle
+enum ConnectivityEvent {
+  UNKNOWN = 0;
+  CONNECTED = 1;
+  DISCONNECTED = 2;
+}

tescmd/telemetry/protos/vehicle_connectivity_pb2.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: vehicle_connectivity.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'vehicle_connectivity.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1avehicle_connectivity.proto\x12\x1etelemetry.vehicle_connectivity\x1a\x1fgoogle/protobuf/timestamp.proto\"\xc7\x01\n\x13VehicleConnectivity\x12\x0b\n\x03vin\x18\x01 \x01(\t\x12\x15\n\rconnection_id\x18\x02 \x01(\t\x12\x41\n\x06status\x18\x03 \x01(\x0e\x32\x31.telemetry.vehicle_connectivity.ConnectivityEvent\x12.\n\ncreated_at\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x19\n\x11network_interface\x18\x05 \x01(\t*A\n\x11\x43onnectivityEvent\x12\x0b\n\x07UNKNOWN\x10\x00\x12\r\n\tCONNECTED\x10\x01\x12\x10\n\x0c\x44ISCONNECTED\x10\x02\x42/Z-github.com/teslamotors/fleet-telemetry/protosb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'vehicle_connectivity_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z-github.com/teslamotors/fleet-telemetry/protos'
+  _globals['_CONNECTIVITYEVENT']._serialized_start=297
+  _globals['_CONNECTIVITYEVENT']._serialized_end=362
+  _globals['_VEHICLECONNECTIVITY']._serialized_start=96
+  _globals['_VEHICLECONNECTIVITY']._serialized_end=295
+# @@protoc_insertion_point(module_scope)

tescmd/telemetry/protos/vehicle_connectivity_pb2.pyi

@@ -0,0 +1,33 @@
+import datetime
+
+from google.protobuf import timestamp_pb2 as _timestamp_pb2
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class ConnectivityEvent(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    UNKNOWN: _ClassVar[ConnectivityEvent]
+    CONNECTED: _ClassVar[ConnectivityEvent]
+    DISCONNECTED: _ClassVar[ConnectivityEvent]
+UNKNOWN: ConnectivityEvent
+CONNECTED: ConnectivityEvent
+DISCONNECTED: ConnectivityEvent
+
+class VehicleConnectivity(_message.Message):
+    __slots__ = ("vin", "connection_id", "status", "created_at", "network_interface")
+    VIN_FIELD_NUMBER: _ClassVar[int]
+    CONNECTION_ID_FIELD_NUMBER: _ClassVar[int]
+    STATUS_FIELD_NUMBER: _ClassVar[int]
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    NETWORK_INTERFACE_FIELD_NUMBER: _ClassVar[int]
+    vin: str
+    connection_id: str
+    status: ConnectivityEvent
+    created_at: _timestamp_pb2.Timestamp
+    network_interface: str
+    def __init__(self, vin: _Optional[str] = ..., connection_id: _Optional[str] = ..., status: _Optional[_Union[ConnectivityEvent, str]] = ..., created_at: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., network_interface: _Optional[str] = ...) -> None: ...