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

tescmd/telemetry/decoder.py

@@ -0,0 +1,284 @@
+"""Decode Fleet Telemetry messages from Tesla vehicles.
+
+Tesla vehicles send telemetry data as **Flatbuffers envelopes** wrapping
+protobuf payloads.  The :class:`TelemetryDecoder` handles both layers:
+
+1. Unwrap the Flatbuffers ``FlatbuffersEnvelope`` → ``FlatbuffersStream``
+   to extract the topic, VIN, timestamp, and raw protobuf bytes.
+2. Decode the protobuf ``Payload`` message using generated bindings from
+   Tesla's ``vehicle_data.proto``.
+
+Proto source: https://github.com/teslamotors/fleet-telemetry/tree/main/protos
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Value oneof variants that are enum types (wire varint) — map to enum name.
+_ENUM_VARIANTS: frozenset[str] = frozenset(
+    {
+        "charging_value",
+        "shift_state_value",
+        "lane_assist_level_value",
+        "scheduled_charging_mode_value",
+        "sentry_mode_state_value",
+        "speed_assist_level_value",
+        "bms_state_value",
+        "buckle_status_value",
+        "car_type_value",
+        "charge_port_value",
+        "charge_port_latch_value",
+        "drive_inverter_state_value",
+        "hvil_status_value",
+        "window_state_value",
+        "seat_fold_position_value",
+        "tractor_air_status_value",
+        "follow_distance_value",
+        "forward_collision_sensitivity_value",
+        "guest_mode_mobile_access_value",
+        "trailer_air_status_value",
+        "detailed_charge_state_value",
+        "hvac_auto_mode_value",
+        "cabin_overheat_protection_mode_value",
+        "cabin_overheat_protection_temperature_limit_value",
+        "defrost_mode_value",
+        "climate_keeper_mode_value",
+        "hvac_power_value",
+        "fast_charger_value",
+        "cable_type_value",
+        "tonneau_tent_mode_value",
+        "tonneau_position_value",
+        "powershare_type_value",
+        "powershare_state_value",
+        "powershare_stop_reason_value",
+        "display_state_value",
+        "distance_unit_value",
+        "temperature_unit_value",
+        "pressure_unit_value",
+        "charge_unit_preference_value",
+        "turn_signal_state_value",
+        "media_status_value",
+        "sunroof_installed_state_value",
+    }
+)
+
+
+@dataclass
+class TelemetryDatum:
+    """A single decoded telemetry field."""
+
+    field_name: str
+    field_id: int
+    value: Any
+    value_type: str  # "string", "int", "float", "bool", "location", "enum"
+
+
+@dataclass
+class TelemetryFrame:
+    """A decoded telemetry payload from one vehicle push."""
+
+    vin: str
+    created_at: datetime
+    data: list[TelemetryDatum] = field(default_factory=list)
+    is_resend: bool = False
+    topic: str = "V"
+
+
+class TelemetryDecoder:
+    """Decodes binary Fleet Telemetry messages into :class:`TelemetryFrame`.
+
+    Handles the full Flatbuffers → protobuf pipeline.
+    """
+
+    def decode(self, raw: bytes) -> TelemetryFrame:
+        """Decode a raw WebSocket binary message.
+
+        The message is expected to be a Flatbuffers ``FlatbuffersEnvelope``
+        containing a ``FlatbuffersStream`` with a protobuf payload.
+
+        Args:
+            raw: The raw binary WebSocket message.
+
+        Returns:
+            A :class:`TelemetryFrame` with decoded telemetry data.
+
+        Raises:
+            ValueError: If the message is fundamentally malformed.
+        """
+        from tescmd.telemetry.flatbuf import parse_envelope
+
+        envelope = parse_envelope(raw)
+        topic = envelope.topic.decode("utf-8", errors="replace")
+        vin = envelope.device_id.decode("utf-8", errors="replace")
+        created_at = datetime.fromtimestamp(envelope.created_at, tz=UTC)
+
+        if topic != "V":
+            # Non-telemetry topics (alerts, errors, connectivity) — return
+            # a frame with no data items for now.
+            logger.debug("Received non-telemetry topic: %s", topic)
+            return TelemetryFrame(
+                vin=vin,
+                created_at=created_at,
+                topic=topic,
+            )
+
+        return self._decode_payload(envelope.payload, vin, created_at, topic)
+
+    def decode_protobuf(self, raw: bytes) -> TelemetryFrame:
+        """Decode a raw protobuf ``Payload`` message directly.
+
+        Bypasses the Flatbuffers envelope — use this when the envelope has
+        already been unwrapped, or for testing with hand-crafted protobuf.
+
+        Args:
+            raw: Raw protobuf bytes of a ``Payload`` message.
+
+        Returns:
+            A :class:`TelemetryFrame` with decoded telemetry data.
+        """
+        return self._decode_payload(raw, vin="", created_at=datetime.now(tz=UTC), topic="V")
+
+    def _decode_payload(
+        self,
+        payload_bytes: bytes,
+        vin: str,
+        created_at: datetime,
+        topic: str,
+    ) -> TelemetryFrame:
+        """Decode the protobuf Payload message using generated bindings."""
+        from tescmd.telemetry.protos import vehicle_data_pb2
+
+        payload = vehicle_data_pb2.Payload()
+        payload.ParseFromString(payload_bytes)
+
+        # Use VIN and timestamp from protobuf if present (more accurate
+        # than the Flatbuffers envelope which has second granularity).
+        if payload.vin:
+            vin = payload.vin
+        if payload.HasField("created_at"):
+            ts = payload.created_at
+            created_at = datetime.fromtimestamp(ts.seconds + ts.nanos / 1_000_000_000, tz=UTC)
+
+        data_items: list[TelemetryDatum] = []
+        for datum in payload.data:
+            item = self._decode_datum(datum)
+            if item is not None:
+                data_items.append(item)
+
+        return TelemetryFrame(
+            vin=vin,
+            created_at=created_at,
+            data=data_items,
+            is_resend=payload.is_resend,
+            topic=topic,
+        )
+
+    @staticmethod
+    def _decode_datum(
+        datum: Any,
+    ) -> TelemetryDatum | None:
+        """Extract a single Datum into a TelemetryDatum."""
+        from tescmd.telemetry.protos import vehicle_data_pb2
+
+        field_id: int = datum.key
+        if field_id == 0:
+            return None
+
+        # Get field name from proto enum, fall back to our registry
+        try:
+            field_name = vehicle_data_pb2.Field.Name(field_id)
+        except ValueError:
+            from tescmd.telemetry.fields import FIELD_NAMES
+
+            field_name = FIELD_NAMES.get(field_id, f"Unknown({field_id})")
+
+        value_msg = datum.value
+        which = value_msg.WhichOneof("value")
+        if which is None:
+            return None
+
+        val: Any
+        value_type: str
+
+        # --- Primitive types ---
+        if which == "string_value":
+            val, value_type = value_msg.string_value, "string"
+        elif which == "int_value":
+            val, value_type = value_msg.int_value, "int"
+        elif which == "long_value":
+            val, value_type = value_msg.long_value, "int"
+        elif which == "float_value":
+            val, value_type = value_msg.float_value, "float"
+        elif which == "double_value":
+            val, value_type = value_msg.double_value, "float"
+        elif which == "boolean_value":
+            val, value_type = value_msg.boolean_value, "bool"
+        elif which == "invalid":
+            val, value_type = None, "invalid"
+
+        # --- Structured types ---
+        elif which == "location_value":
+            loc = value_msg.location_value
+            val = {"latitude": loc.latitude, "longitude": loc.longitude}
+            value_type = "location"
+        elif which == "door_value":
+            doors = value_msg.door_value
+            val = {
+                "DriverFront": doors.DriverFront,
+                "DriverRear": doors.DriverRear,
+                "PassengerFront": doors.PassengerFront,
+                "PassengerRear": doors.PassengerRear,
+                "TrunkFront": doors.TrunkFront,
+                "TrunkRear": doors.TrunkRear,
+            }
+            value_type = "doors"
+        elif which == "tire_location_value":
+            tire = value_msg.tire_location_value
+            val = {
+                "front_left": tire.front_left,
+                "front_right": tire.front_right,
+                "rear_left": tire.rear_left,
+                "rear_right": tire.rear_right,
+            }
+            value_type = "tires"
+        elif which == "time_value":
+            t = value_msg.time_value
+            val = f"{t.hour:02d}:{t.minute:02d}:{t.second:02d}"
+            value_type = "time"
+
+        # --- Enum types → resolve to human-readable name ---
+        elif which in _ENUM_VARIANTS:
+            raw_val = getattr(value_msg, which)
+            # Enum fields are ints; get the name from the descriptor
+            enum_descriptor = value_msg.DESCRIPTOR.fields_by_name[which].enum_type
+            if enum_descriptor is not None:
+                try:
+                    val = enum_descriptor.values_by_number[raw_val].name
+                except (KeyError, IndexError):
+                    val = raw_val
+            else:
+                val = raw_val
+            value_type = "enum"
+
+        else:
+            # Unknown variant — store the raw value
+            val = getattr(value_msg, which, None)
+            value_type = which
+
+        return TelemetryDatum(
+            field_name=field_name,
+            field_id=field_id,
+            value=val,
+            value_type=value_type,
+        )
+
+
+def _zigzag_decode(n: int) -> int:
+    """Decode a ZigZag-encoded signed integer."""
+    return (n >> 1) ^ -(n & 1)

tescmd/telemetry/fields.py

@@ -0,0 +1,248 @@
+"""Fleet Telemetry field name registry and preset configurations.
+
+Field IDs sourced from Tesla's ``vehicle_data.proto`` Field enum.
+Presets define commonly-used field groups with appropriate polling
+intervals for different use cases.
+"""
+
+from __future__ import annotations
+
+from tescmd.api.errors import ConfigError
+
+# ---------------------------------------------------------------------------
+# Field enum → human-readable name  (from vehicle_data.proto)
+# ---------------------------------------------------------------------------
+
+FIELD_NAMES: dict[int, str] = {
+    1: "DriveState",
+    2: "ChargeState",
+    3: "Soc",
+    4: "VehicleSpeed",
+    5: "Odometer",
+    6: "PackVoltage",
+    7: "PackCurrent",
+    8: "BatteryLevel",
+    9: "Location",
+    10: "Gear",
+    11: "EstBatteryRange",
+    12: "IdealBatteryRange",
+    13: "RatedBatteryRange",
+    14: "ACChargingEnergyIn",
+    15: "ACChargingPower",
+    16: "DCChargingEnergyIn",
+    17: "DCChargingPower",
+    18: "ChargeCurrentRequest",
+    19: "ChargeCurrentRequestMax",
+    20: "ChargeLimitSoc",
+    21: "ChargePortDoorOpen",
+    22: "ChargePortLatch",
+    23: "ChargerActualCurrent",
+    24: "ChargerPhases",
+    25: "ChargerPilotCurrent",
+    26: "ChargerVoltage",
+    27: "FastChargerPresent",
+    28: "ScheduledChargingMode",
+    29: "ScheduledChargingPending",
+    30: "ScheduledChargingStartTime",
+    31: "ScheduledDepartureTime",
+    32: "TimeToFullCharge",
+    33: "InsideTemp",
+    34: "OutsideTemp",
+    35: "DriverTempSetting",
+    36: "PassengerTempSetting",
+    37: "IsClimateOn",
+    38: "FanStatus",
+    39: "LeftTempDirection",
+    40: "RightTempDirection",
+    41: "SeatHeaterLeft",
+    42: "SeatHeaterRight",
+    43: "SeatHeaterRearLeft",
+    44: "SeatHeaterRearCenter",
+    45: "SeatHeaterRearRight",
+    46: "SteeringWheelHeater",
+    47: "AutoSeatClimateLeft",
+    48: "AutoSeatClimateRight",
+    49: "CabinOverheatProtection",
+    50: "DefrostMode",
+    51: "Locked",
+    52: "SentryMode",
+    53: "CenterDisplay",
+    54: "ValetMode",
+    55: "RemoteStart",
+    56: "DoorState",
+    57: "WindowState",
+    58: "TrunkOpen",
+    59: "FrunkOpen",
+    60: "SoftwareVersion",
+    61: "TpmsPressureFl",
+    62: "TpmsPressureFr",
+    63: "TpmsPressureRl",
+    64: "TpmsPressureRr",
+    65: "DetailedChargeState",
+    66: "HomeLink",
+    67: "UserPresent",
+    68: "DashcamState",
+    69: "RearSeatHeaters",
+    70: "BatteryHeaterOn",
+    71: "NotEnoughPowerToHeat",
+    72: "BmsFullchargecomplete",
+    73: "ChargeEnablerequest",
+    74: "ChargerPhases2",
+    75: "EnergyRemaining",
+    76: "LifetimeEnergyUsed",
+    77: "LifetimeEnergyUsedDrive",
+    78: "BMSState",
+    79: "GuestModeEnabled",
+    80: "PreconditioningEnabled",
+    81: "ScheduledChargingStartTimeApp",
+    82: "TripCharging",
+    83: "ChargingCableType",
+    84: "RouteLastUpdated",
+    85: "RouteLine",
+    86: "MilesToArrival",
+    87: "MinutesToArrival",
+    88: "TrafficMinutesDelay",
+    89: "Elevation",
+    90: "Heading",
+    91: "PowerState",
+    92: "RatedRange",
+    93: "CruiseState",
+    94: "CruiseSetSpeed",
+    95: "LaneAssistLevel",
+    96: "AutopilotState",
+    97: "AutopilotHandsOnState",
+    98: "SpeedLimitMode",
+    99: "SpeedLimitWarning",
+    100: "MaxSpeedLimit",
+    101: "SunRoofPercentOpen",
+    102: "SunRoofState",
+    103: "TonneauPosition",
+    104: "TonneauState",
+    105: "WiperHeatEnabled",
+    106: "BrakePedalPos",
+    107: "PedalPosition",
+    108: "DriveRailAmps12v",
+    109: "BrickVoltageMax",
+    110: "BrickVoltageMin",
+    111: "ModuleTempMax",
+    112: "ModuleTempMin",
+    113: "NumBrickVoltageMax",
+    114: "NumBrickVoltageMin",
+    115: "NumModuleTempMax",
+    116: "NumModuleTempMin",
+    117: "ChargeAmps",
+    118: "FastChargerType",
+    119: "ConnChargeCable",
+    120: "Supercharger",
+}
+
+# ---------------------------------------------------------------------------
+# Preset field configurations
+# ---------------------------------------------------------------------------
+
+DEFAULT_FIELDS: dict[str, dict[str, int]] = {
+    "Soc": {"interval_seconds": 10},
+    "VehicleSpeed": {"interval_seconds": 1},
+    "Location": {"interval_seconds": 5},
+    "ChargeState": {"interval_seconds": 10},
+    "InsideTemp": {"interval_seconds": 30},
+    "OutsideTemp": {"interval_seconds": 60},
+    "Odometer": {"interval_seconds": 60},
+    "BatteryLevel": {"interval_seconds": 10},
+    "Gear": {"interval_seconds": 1},
+    "PackVoltage": {"interval_seconds": 10},
+    "PackCurrent": {"interval_seconds": 10},
+}
+
+PRESETS: dict[str, dict[str, dict[str, int]]] = {
+    "default": DEFAULT_FIELDS,
+    "driving": {
+        "VehicleSpeed": {"interval_seconds": 1},
+        "Location": {"interval_seconds": 1},
+        "Gear": {"interval_seconds": 1},
+        "Heading": {"interval_seconds": 1},
+        "Odometer": {"interval_seconds": 10},
+        "Elevation": {"interval_seconds": 5},
+        "BatteryLevel": {"interval_seconds": 10},
+        "Soc": {"interval_seconds": 10},
+        "PackCurrent": {"interval_seconds": 5},
+        "PackVoltage": {"interval_seconds": 5},
+        "CruiseState": {"interval_seconds": 5},
+        "CruiseSetSpeed": {"interval_seconds": 5},
+        "PowerState": {"interval_seconds": 10},
+    },
+    "charging": {
+        "Soc": {"interval_seconds": 5},
+        "BatteryLevel": {"interval_seconds": 5},
+        "PackVoltage": {"interval_seconds": 5},
+        "PackCurrent": {"interval_seconds": 5},
+        "ChargeState": {"interval_seconds": 5},
+        "ChargerActualCurrent": {"interval_seconds": 5},
+        "ChargerVoltage": {"interval_seconds": 5},
+        "ChargerPhases": {"interval_seconds": 30},
+        "ACChargingPower": {"interval_seconds": 5},
+        "DCChargingPower": {"interval_seconds": 5},
+        "TimeToFullCharge": {"interval_seconds": 30},
+        "ChargeLimitSoc": {"interval_seconds": 60},
+        "ChargePortDoorOpen": {"interval_seconds": 60},
+        "BatteryHeaterOn": {"interval_seconds": 30},
+        "InsideTemp": {"interval_seconds": 60},
+    },
+    "climate": {
+        "InsideTemp": {"interval_seconds": 10},
+        "OutsideTemp": {"interval_seconds": 30},
+        "DriverTempSetting": {"interval_seconds": 30},
+        "PassengerTempSetting": {"interval_seconds": 30},
+        "IsClimateOn": {"interval_seconds": 10},
+        "FanStatus": {"interval_seconds": 10},
+        "SeatHeaterLeft": {"interval_seconds": 30},
+        "SeatHeaterRight": {"interval_seconds": 30},
+        "SteeringWheelHeater": {"interval_seconds": 30},
+        "CabinOverheatProtection": {"interval_seconds": 60},
+        "DefrostMode": {"interval_seconds": 30},
+        "PreconditioningEnabled": {"interval_seconds": 30},
+    },
+    "all": {name: {"interval_seconds": 30} for name in FIELD_NAMES.values()},
+}
+
+# Reverse lookup: name → ID
+_NAME_TO_ID: dict[str, int] = {v: k for k, v in FIELD_NAMES.items()}
+
+
+def resolve_fields(
+    spec: str,
+    interval_override: int | None = None,
+) -> dict[str, dict[str, int]]:
+    """Resolve a ``--fields`` argument to a field configuration dict.
+
+    Args:
+        spec: A preset name (e.g. ``"default"``, ``"charging"``) or a
+            comma-separated list of field names (e.g. ``"Soc,VehicleSpeed"``).
+        interval_override: If set, overrides ``interval_seconds`` for all fields.
+
+    Returns:
+        A dict mapping field names to ``{"interval_seconds": N}``.
+
+    Raises:
+        ConfigError: If a field name or preset is unrecognized.
+    """
+    if spec in PRESETS:
+        fields = dict(PRESETS[spec])
+    else:
+        # Comma-separated field names
+        fields = {}
+        for name in spec.split(","):
+            name = name.strip()
+            if not name:
+                continue
+            if name not in _NAME_TO_ID:
+                raise ConfigError(
+                    f"Unknown telemetry field: '{name}'. "
+                    f"Available presets: {', '.join(sorted(PRESETS.keys()))}"
+                )
+            fields[name] = {"interval_seconds": 10}  # reasonable default
+
+    if interval_override is not None:
+        fields = {name: {"interval_seconds": interval_override} for name in fields}
+
+    return fields

tescmd/telemetry/flatbuf.py

@@ -0,0 +1,162 @@
+"""Minimal Flatbuffers reader for Tesla Fleet Telemetry envelopes.
+
+Tesla vehicles send telemetry data wrapped in a Flatbuffers envelope:
+
+    WebSocket binary frame
+      └─ FlatbuffersEnvelope
+           ├── txid          (bytes)
+           ├── topic         (bytes)  — "V", "alerts", "errors", "connectivity"
+           ├── messageType   (uint8)
+           ├── messageId     (bytes)
+           └── FlatbuffersStream (union)
+                  ├── createdAt  (uint32)  — epoch seconds
+                  ├── payload    (bytes)   — protobuf content
+                  ├── deviceId   (bytes)   — VIN
+                  └── ...
+
+This module provides a zero-dependency reader for these two tables.
+The protobuf payload inside ``FlatbuffersStream.payload`` is decoded
+separately by :mod:`tescmd.telemetry.decoder`.
+
+Schema source:
+  https://github.com/teslamotors/fleet-telemetry/tree/main/messages/tesla
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class StreamMessage:
+    """Unwrapped Fleet Telemetry envelope."""
+
+    topic: bytes
+    device_id: bytes  # VIN
+    created_at: int  # epoch seconds
+    payload: bytes  # protobuf content
+    txid: bytes = b""
+    message_id: bytes = b""
+
+
+def parse_envelope(buf: bytes) -> StreamMessage:
+    """Parse a FlatbuffersEnvelope from raw WebSocket bytes.
+
+    Raises:
+        ValueError: If the buffer is too small or structurally invalid.
+    """
+    if len(buf) < 8:
+        raise ValueError(f"Buffer too small for Flatbuffers envelope ({len(buf)} bytes)")
+
+    # Root table offset (uint32 LE at byte 0)
+    root_pos = _read_u32(buf, 0)
+    if root_pos >= len(buf):
+        raise ValueError(f"Root offset {root_pos} exceeds buffer size {len(buf)}")
+
+    # Envelope vtable
+    vtable_pos = _vtable_pos(buf, root_pos)
+
+    # Envelope fields (vtable offsets: txid=4, topic=6, messageType=8, message=10, messageId=12)
+    txid = _read_vector(buf, root_pos, vtable_pos, vtable_offset=4)
+    topic = _read_vector(buf, root_pos, vtable_pos, vtable_offset=6)
+    message_id = _read_vector(buf, root_pos, vtable_pos, vtable_offset=12)
+
+    # Navigate to FlatbuffersStream (union at vtable_offset=10)
+    stream_pos = _read_indirect(buf, root_pos, vtable_pos, vtable_offset=10)
+    if stream_pos is None:
+        raise ValueError("FlatbuffersEnvelope has no message field")
+
+    # Stream vtable
+    stream_vtable = _vtable_pos(buf, stream_pos)
+
+    # Stream fields (vtable offsets: createdAt=4, senderId=6, payload=8,
+    #                deviceType=10, deviceId=12, deliveredAtEpochMs=14)
+    created_at = _read_u32_field(buf, stream_pos, stream_vtable, vtable_offset=4)
+    payload = _read_vector(buf, stream_pos, stream_vtable, vtable_offset=8)
+    device_id = _read_vector(buf, stream_pos, stream_vtable, vtable_offset=12)
+
+    return StreamMessage(
+        topic=topic,
+        device_id=device_id,
+        created_at=created_at,
+        payload=payload,
+        txid=txid,
+        message_id=message_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Low-level Flatbuffers primitives
+# ---------------------------------------------------------------------------
+
+
+def _read_u16(buf: bytes, pos: int) -> int:
+    result: int = struct.unpack_from("<H", buf, pos)[0]
+    return result
+
+
+def _read_u32(buf: bytes, pos: int) -> int:
+    result: int = struct.unpack_from("<I", buf, pos)[0]
+    return result
+
+
+def _read_i32(buf: bytes, pos: int) -> int:
+    result: int = struct.unpack_from("<i", buf, pos)[0]
+    return result
+
+
+def _vtable_pos(buf: bytes, table_pos: int) -> int:
+    """Compute vtable position from a table position.
+
+    The first 4 bytes of a Flatbuffers table are a signed offset (soffset32)
+    pointing back to its vtable.
+    """
+    soffset = _read_i32(buf, table_pos)
+    return table_pos - soffset
+
+
+def _field_offset(buf: bytes, vtable_pos: int, vtable_offset: int) -> int:
+    """Read a field's offset from the vtable.
+
+    Returns 0 if the field is absent (vtable_offset beyond vtable size
+    or stored offset is 0).
+    """
+    vtable_size = _read_u16(buf, vtable_pos)
+    if vtable_offset >= vtable_size:
+        return 0
+    return _read_u16(buf, vtable_pos + vtable_offset)
+
+
+def _read_vector(buf: bytes, table_pos: int, vtable_pos: int, *, vtable_offset: int) -> bytes:
+    """Read a byte-vector field from a Flatbuffers table."""
+    voff = _field_offset(buf, vtable_pos, vtable_offset)
+    if voff == 0:
+        return b""
+    # Follow indirect offset to vector
+    field_pos = table_pos + voff
+    vec_pos = field_pos + _read_u32(buf, field_pos)
+    length = _read_u32(buf, vec_pos)
+    return bytes(buf[vec_pos + 4 : vec_pos + 4 + length])
+
+
+def _read_u32_field(buf: bytes, table_pos: int, vtable_pos: int, *, vtable_offset: int) -> int:
+    """Read a uint32 scalar field from a Flatbuffers table."""
+    voff = _field_offset(buf, vtable_pos, vtable_offset)
+    if voff == 0:
+        return 0
+    return _read_u32(buf, table_pos + voff)
+
+
+def _read_indirect(
+    buf: bytes, table_pos: int, vtable_pos: int, *, vtable_offset: int
+) -> int | None:
+    """Follow an offset field to a child table (used for unions).
+
+    Returns the child table position, or ``None`` if absent.
+    """
+    voff = _field_offset(buf, vtable_pos, vtable_offset)
+    if voff == 0:
+        return None
+    field_pos = table_pos + voff
+    return field_pos + _read_u32(buf, field_pos)

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
+"""