proto: model DashcamSei.SeiMetadata (TeslaCam/Sentry video SEI telemetry)

.changeset/model-dashcam-sei-metadata.md

@@ -0,0 +1,5 @@
+---
+"@teslemetry/tesla-protocol": minor
+---
+
+Model `DashcamSei.SeiMetadata`, the per-frame vehicle telemetry (speed, gear, steering, GPS, heading, linear acceleration, autopilot state, blinkers, brake) carried in the SEI payload embedded in TeslaCam/Sentry/live-camera video - based on our own observations and contributions from the community.

AGENTS.md

@@ -11,6 +11,7 @@ This file is the project's committed home for project-intrinsic agent knowledge:
 - Un-reserving a field to model it (as field 12 above did) trips buf's `RESERVED_MESSAGE_NO_DELETE` breaking check even though it's a wire-compatible addition; `buf.yaml` excepts that rule repo-wide for this reason, so the same move for fields 17/19 later won't need a fresh exception.
 - The committed `proto/command/` baseline already reflects one specific Tesla app build reconstructed via cross-version protobuf diffing (`app-4.58.6`, see `TESLEMETRY-EXT` markers). A later app-version-diff pass will find most candidate fields already modelled here - check the current `.proto` files for the exact field/tag before assuming it needs adding, and only model the genuine delta.
 - `proto/charging/` is a documented exception to the "app-only namespaces are not published" policy (`PROVENANCE.md`): it has no BLE or Fleet API wire path today, but was published because it describes the vehicle-charging product domain. Any future app-only module wanting the same exception should be argued explicitly, not assumed from this precedent.
+- Adding a wholly new proto directory (a source with no upstream) needs registering in three places: the `buf.yaml` module list, `GROUPS_LIST` in `scripts/generate.sh`, and the layout table + provenance table in `README.md`/`PROVENANCE.md`. TypeScript/Python package exports are wildcarded, so no per-group registration is needed there.
 
 ## Maintaining this file
 

PROVENANCE.md

@@ -15,6 +15,7 @@ directories no public upstream exists and this repo is the source of record.
 | `proto/energy_device/`, `proto/energy_command/` | Teslemetry source-of-record | no upstream (TEG gateway local API, from our own observations and contributions from the community) |
 | `proto/teslapower/` | Teslemetry source-of-record | no upstream (Powerwall local API, from our own observations and contributions from the community, credit @brianhealey) |
 | `proto/charging/` | Teslemetry source-of-record | no upstream (EV charge-session energy metering / billing schema, from our own observations and contributions from the community) |
+| `proto/dashcam/` | Teslemetry source-of-record | no upstream (TeslaCam/Sentry video SEI metadata, from our own observations and contributions from the community) |
 
 ## How the boundary is kept visible
 

README.md

@@ -44,7 +44,8 @@ proto/                  source of truth (the only hand-edited artifacts)
 ├── energy_device/      TEG gateway local-API protos
 ├── energy_command/     energy command identifiers
 ├── teslapower/         Powerwall local-API proto
-└── charging/           EV charge-session metering/billing ("STEM") protos
+├── charging/           EV charge-session metering/billing ("STEM") protos
+└── dashcam/            TeslaCam/Sentry video SEI metadata proto
 packages/typescript/    @teslemetry/tesla-protocol (generated, committed)
 packages/python/        tesla-protocol (generated, committed)
 ```

buf.yaml

@@ -6,6 +6,7 @@ modules:
   - path: proto/energy_command
   - path: proto/teslapower
   - path: proto/charging
+  - path: proto/dashcam
 lint:
   # Tesla's upstream style (package CarServer, enum value SpeedLimit, file-level
   # layout) violates buf's naming rules; we inherit their style, we don't fix it.

packages/python/tesla_protocol/dashcam/__init__.pyi

@@ -0,0 +1 @@
+from . import dashcam_sei_pb2

packages/python/tesla_protocol/dashcam/dashcam_sei_pb2.py

@@ -0,0 +1,20 @@
+"""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, '', 'dashcam_sei.proto')
+_sym_db = _symbol_database.Default()
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x11dashcam_sei.proto\x12\nDashcamSei"\xf3\x04\n\x0bSeiMetadata\x12\x0f\n\x07field_1\x18\x01 \x01(\r\x12/\n\tgearState\x18\x02 \x01(\x0e2\x1c.DashcamSei.SeiMetadata.Gear\x12\x12\n\nframeSeqNo\x18\x03 \x01(\x04\x12\x17\n\x0fvehicleSpeedMps\x18\x04 \x01(\x02\x12 \n\x18acceleratorPedalPosition\x18\x05 \x01(\x02\x12\x1a\n\x12steeringWheelAngle\x18\x06 \x01(\x02\x12\x15\n\rblinkerOnLeft\x18\x07 \x01(\x08\x12\x16\n\x0eblinkerOnRight\x18\x08 \x01(\x08\x12\x14\n\x0cbrakeApplied\x18\t \x01(\x08\x12>\n\x0eautopilotState\x18\n \x01(\x0e2&.DashcamSei.SeiMetadata.AutopilotState\x12\x13\n\x0blatitudeDeg\x18\x0b \x01(\x01\x12\x14\n\x0clongitudeDeg\x18\x0c \x01(\x01\x12\x12\n\nheadingDeg\x18\r \x01(\x01\x12\x1f\n\x17linearAccelerationMps2X\x18\x0e \x01(\x01\x12\x1f\n\x17linearAccelerationMps2Y\x18\x0f \x01(\x01\x12\x1f\n\x17linearAccelerationMps2Z\x18\x10 \x01(\x01"I\n\x04Gear\x12\r\n\tGEAR_PARK\x10\x00\x12\x0e\n\nGEAR_DRIVE\x10\x01\x12\x10\n\x0cGEAR_REVERSE\x10\x02\x12\x10\n\x0cGEAR_NEUTRAL\x10\x03"E\n\x0eAutopilotState\x12\x08\n\x04NONE\x10\x00\x12\x10\n\x0cSELF_DRIVING\x10\x01\x12\r\n\tAUTOSTEER\x10\x02\x12\x08\n\x04TACC\x10\x03b\x06proto3')
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'dashcam_sei_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+    DESCRIPTOR._loaded_options = None
+    _globals['_SEIMETADATA']._serialized_start = 34
+    _globals['_SEIMETADATA']._serialized_end = 661
+    _globals['_SEIMETADATA_GEAR']._serialized_start = 517
+    _globals['_SEIMETADATA_GEAR']._serialized_end = 590
+    _globals['_SEIMETADATA_AUTOPILOTSTATE']._serialized_start = 592
+    _globals['_SEIMETADATA_AUTOPILOTSTATE']._serialized_end = 661

packages/python/tesla_protocol/dashcam/dashcam_sei_pb2.pyi

@@ -0,0 +1,65 @@
+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 typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class SeiMetadata(_message.Message):
+    __slots__ = ('field_1', 'gearState', 'frameSeqNo', 'vehicleSpeedMps', 'acceleratorPedalPosition', 'steeringWheelAngle', 'blinkerOnLeft', 'blinkerOnRight', 'brakeApplied', 'autopilotState', 'latitudeDeg', 'longitudeDeg', 'headingDeg', 'linearAccelerationMps2X', 'linearAccelerationMps2Y', 'linearAccelerationMps2Z')
+
+    class Gear(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = ()
+        GEAR_PARK: _ClassVar[SeiMetadata.Gear]
+        GEAR_DRIVE: _ClassVar[SeiMetadata.Gear]
+        GEAR_REVERSE: _ClassVar[SeiMetadata.Gear]
+        GEAR_NEUTRAL: _ClassVar[SeiMetadata.Gear]
+    GEAR_PARK: SeiMetadata.Gear
+    GEAR_DRIVE: SeiMetadata.Gear
+    GEAR_REVERSE: SeiMetadata.Gear
+    GEAR_NEUTRAL: SeiMetadata.Gear
+
+    class AutopilotState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = ()
+        NONE: _ClassVar[SeiMetadata.AutopilotState]
+        SELF_DRIVING: _ClassVar[SeiMetadata.AutopilotState]
+        AUTOSTEER: _ClassVar[SeiMetadata.AutopilotState]
+        TACC: _ClassVar[SeiMetadata.AutopilotState]
+    NONE: SeiMetadata.AutopilotState
+    SELF_DRIVING: SeiMetadata.AutopilotState
+    AUTOSTEER: SeiMetadata.AutopilotState
+    TACC: SeiMetadata.AutopilotState
+    FIELD_1_FIELD_NUMBER: _ClassVar[int]
+    GEARSTATE_FIELD_NUMBER: _ClassVar[int]
+    FRAMESEQNO_FIELD_NUMBER: _ClassVar[int]
+    VEHICLESPEEDMPS_FIELD_NUMBER: _ClassVar[int]
+    ACCELERATORPEDALPOSITION_FIELD_NUMBER: _ClassVar[int]
+    STEERINGWHEELANGLE_FIELD_NUMBER: _ClassVar[int]
+    BLINKERONLEFT_FIELD_NUMBER: _ClassVar[int]
+    BLINKERONRIGHT_FIELD_NUMBER: _ClassVar[int]
+    BRAKEAPPLIED_FIELD_NUMBER: _ClassVar[int]
+    AUTOPILOTSTATE_FIELD_NUMBER: _ClassVar[int]
+    LATITUDEDEG_FIELD_NUMBER: _ClassVar[int]
+    LONGITUDEDEG_FIELD_NUMBER: _ClassVar[int]
+    HEADINGDEG_FIELD_NUMBER: _ClassVar[int]
+    LINEARACCELERATIONMPS2X_FIELD_NUMBER: _ClassVar[int]
+    LINEARACCELERATIONMPS2Y_FIELD_NUMBER: _ClassVar[int]
+    LINEARACCELERATIONMPS2Z_FIELD_NUMBER: _ClassVar[int]
+    field_1: int
+    gearState: SeiMetadata.Gear
+    frameSeqNo: int
+    vehicleSpeedMps: float
+    acceleratorPedalPosition: float
+    steeringWheelAngle: float
+    blinkerOnLeft: bool
+    blinkerOnRight: bool
+    brakeApplied: bool
+    autopilotState: SeiMetadata.AutopilotState
+    latitudeDeg: float
+    longitudeDeg: float
+    headingDeg: float
+    linearAccelerationMps2X: float
+    linearAccelerationMps2Y: float
+    linearAccelerationMps2Z: float
+
+    def __init__(self, field_1: _Optional[int]=..., gearState: _Optional[_Union[SeiMetadata.Gear, str]]=..., frameSeqNo: _Optional[int]=..., vehicleSpeedMps: _Optional[float]=..., acceleratorPedalPosition: _Optional[float]=..., steeringWheelAngle: _Optional[float]=..., blinkerOnLeft: bool=..., blinkerOnRight: bool=..., brakeApplied: bool=..., autopilotState: _Optional[_Union[SeiMetadata.AutopilotState, str]]=..., latitudeDeg: _Optional[float]=..., longitudeDeg: _Optional[float]=..., headingDeg: _Optional[float]=..., linearAccelerationMps2X: _Optional[float]=..., linearAccelerationMps2Y: _Optional[float]=..., linearAccelerationMps2Z: _Optional[float]=...) -> None:
+        ...