energy_device: field-level extraction of TEG/WC/PVI/Neurio/LocalAuth/EnergySiteNet/IntraSite/FileStore/GraphQL APIs

.changeset/energy-device-v1-field-level-expansion.md

@@ -0,0 +1,5 @@
+---
+"@teslemetry/tesla-protocol": minor
+---
+
+Model field-level definitions for the `energy_device.v1` local-Powerwall/Wall-Connector/PV-inverter API - Wall Connector (`WCAPI`), TEG/Powerwall (`TEGAPI`, controllable-device-program scheduling, OCPP/CSMS config), PV inverter (`PVIAPI`, new `pvi_api.proto`), CT metering (`NeurioMeterAPI`, new `neurio_meter_api.proto`), local login (`LocalAuthAPI`, new `local_auth_api.proto`), site device pairing (`EnergySiteNetAPI`, `IntraSiteAPI`, new `intra_site_api.proto`), on-gateway file storage (`FileStoreAPI`, new `filestore_api.proto`), and the GraphQL-over-protobuf sub-channel (`GraphQLAPI`, new `graphql_api.proto`) - completing each service's request/response bodies and its `*Messages` oneof envelope, based on our own observations and contributions from the community.

AGENTS.md

@@ -12,6 +12,8 @@ This file is the project's committed home for project-intrinsic agent knowledge:
 - 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.
+- `proto/energy_device/`'s field-level content (as opposed to the bare message/service names) comes from the app's compiled Hermes JS bundle (ts-proto/protobuf.js output), not the DEX - a DEX-only pass sees only the routing enum, not the payload types. Each service's top-level oneof envelope (e.g. `TEGMessages`, `WCMessages`) carries the authoritative field-number-to-message map for that service and is the fastest way to cross-check a field's real tag before trusting a `.proto` guess. Some `energy_device.v1` services (`SMAPI`, `WMSAAPI`) appear only as bare names in the bundle with no reachable field-level code - their request/response bodies aren't recoverable from this artifact. A few `energy_device.v1` messages (the `CommonAPI`/`TEGAPI` register and site-uuid/suggestion flows) carry a field whose type lives in a sibling, not-yet-published package (`energy_registration.v1`) - left unmodeled with a short inline comment rather than guessed at or vendored in.
+- `buf breaking`'s tag-renumbering forbidding (see `.changeset/README.md`) is a hard CI gate, not a guideline: it fires even when you have hard evidence an already-published field's tag is wrong. Don't renumber a published tag to fix it, no matter how confident the evidence - revert and flag it for a maintainer decision instead.
 
 ## Maintaining this file
 

packages/python/tesla_protocol/energy_device/__init__.pyi

@@ -5,7 +5,13 @@ from . import device_pb2
 from . import energy_pb2
 from . import energy_site_net_pb2
 from . import error_pb2
+from . import filestore_api_pb2
+from . import graphql_api_pb2
+from . import intra_site_api_pb2
+from . import local_auth_api_pb2
 from . import networking_pb2
+from . import neurio_meter_api_pb2
+from . import pvi_api_pb2
 from . import teg_api_pb2
 from . import transport_pb2
 from . import update_pb2

packages/python/tesla_protocol/energy_device/device_pb2.py

@@ -6,30 +6,36 @@
 from google.protobuf.internal import builder as _builder
 _runtime_version.ValidateProtobufRuntimeVersion(_runtime_version.Domain.PUBLIC, 6, 31, 1, '', 'device.proto')
 _sym_db = _symbol_database.Default()
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0cdevice.proto\x12\x1ctesla.proto.energy_device.v1"\x14\n\x03Din\x12\r\n\x05value\x18\x01 \x01(\t"3\n\x05EcuId\x12\x13\n\x0bpart_number\x18\x01 \x01(\t\x12\x15\n\rserial_number\x18\x02 \x01(\t"\xec\x01\n\x13DeviceSignedPayload\x12\x0f\n\x07payload\x18\x01 \x01(\x0c\x12P\n\x15device_signature_type\x18\x02 \x01(\x0e21.tesla.proto.energy_device.v1.DeviceSignatureType\x12\x11\n\tsignature\x18\x03 \x01(\x0c\x12J\n\x12device_cert_format\x18\x04 \x01(\x0e2..tesla.proto.energy_device.v1.DeviceCertFormat\x12\x13\n\x0bdevice_cert\x18\x05 \x01(\x0c"]\n\x10EncryptedMessage\x124\n\x06cipher\x18\x01 \x01(\x0e2$.tesla.proto.energy_device.v1.Cipher\x12\x13\n\x0bcipher_text\x18\x02 \x01(\x0c*\xb9\x01\n\nDeviceType\x12\x17\n\x13DEVICE_TYPE_INVALID\x10\x00\x12\x16\n\x12DEVICE_TYPE_GEN3WC\x10\x01\x12\x15\n\x11DEVICE_TYPE_PVCOM\x10\x02\x12\x13\n\x0fDEVICE_TYPE_MSA\x10\x03\x12\x1e\n\x1aDEVICE_TYPE_SITECONTROLLER\x10\x04\x12\x19\n\x15DEVICE_TYPE_MEGAPUTER\x10\x05\x12\x13\n\x0fDEVICE_TYPE_IPM\x10\x06*j\n\x10DeviceCertFormat\x12\x1e\n\x1aDEVICE_CERT_FORMAT_INVALID\x10\x00\x12\x1a\n\x16DEVICE_CERT_FORMAT_DER\x10\x01\x12\x1a\n\x16DEVICE_CERT_FORMAT_PEM\x10\x02*e\n\x13DeviceSignatureType\x12!\n\x1dDEVICE_SIGNATURE_TYPE_INVALID\x10\x00\x12+\n\'DEVICE_SIGNATURE_TYPE_SHA256_ECDSA_ASN1\x10\x01*8\n\x06Cipher\x12\x12\n\x0eCIPHER_INVALID\x10\x00\x12\x1a\n\x16CIPHER_RSA_OAEP_SHA256\x10\x02*\xfb\x02\n\rTEGDeviceType\x12\x1b\n\x17TEG_DEVICE_TYPE_INVALID\x10\x00\x12\x17\n\x13TEG_DEVICE_TYPE_SMC\x10\x01\x12 \n\x1cTEG_DEVICE_TYPE_HEC_GATEWAY1\x10\x02\x12 \n\x1cTEG_DEVICE_TYPE_TEG_GATEWAY2\x10\x03\x12%\n!TEG_DEVICE_TYPE_TEG_POWERWALLPLUS\x10\x04\x12\x1b\n\x17TEG_DEVICE_TYPE_TEG_MP1\x10\x05\x12$\n TEG_DEVICE_TYPE_TEG_SUPERCHARGER\x10\x06\x12#\n\x1fTEG_DEVICE_TYPE_TACO_POWERWALL3\x10\x07\x12\x1b\n\x17TEG_DEVICE_TYPE_TEG_PVI\x10\x08\x12"\n\x1eTEG_DEVICE_TYPE_TACO_GATEWAY3V\x10\t\x12 \n\x1cTEG_DEVICE_TYPE_TACO_WALLBOX\x10\n*o\n\riPMDeviceType\x12\x1b\n\x17IPM_DEVICE_TYPE_INVALID\x10\x00\x12\x1e\n\x1aIPM_DEVICE_TYPE_POWERPACK3\x10\x01\x12!\n\x1dIPM_DEVICE_TYPE_SUPERCHARGER4\x10\x02Bz\n$com.tesla.generated.energy_device.v1B\x06DeviceZJgithub.com/teslamotors/energy_device/pkg/protocol/protobuf/energydevice/v1b\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0cdevice.proto\x12\x1ctesla.proto.energy_device.v1"\x14\n\x03Din\x12\r\n\x05value\x18\x01 \x01(\t"3\n\x05EcuId\x12\x13\n\x0bpart_number\x18\x01 \x01(\t\x12\x15\n\rserial_number\x18\x02 \x01(\t"\x14\n\x03VIN\x12\r\n\x05value\x18\x01 \x01(\t"\x1c\n\x0bUUIDv4Bytes\x12\r\n\x05value\x18\x01 \x01(\x0c"\x16\n\x06UUIDv4\x12\x0c\n\x04text\x18\x01 \x01(\t"\xec\x01\n\x13DeviceSignedPayload\x12\x0f\n\x07payload\x18\x01 \x01(\x0c\x12P\n\x15device_signature_type\x18\x02 \x01(\x0e21.tesla.proto.energy_device.v1.DeviceSignatureType\x12\x11\n\tsignature\x18\x03 \x01(\x0c\x12J\n\x12device_cert_format\x18\x04 \x01(\x0e2..tesla.proto.energy_device.v1.DeviceCertFormat\x12\x13\n\x0bdevice_cert\x18\x05 \x01(\x0c"]\n\x10EncryptedMessage\x124\n\x06cipher\x18\x01 \x01(\x0e2$.tesla.proto.energy_device.v1.Cipher\x12\x13\n\x0bcipher_text\x18\x02 \x01(\x0c*\xb9\x01\n\nDeviceType\x12\x17\n\x13DEVICE_TYPE_INVALID\x10\x00\x12\x16\n\x12DEVICE_TYPE_GEN3WC\x10\x01\x12\x15\n\x11DEVICE_TYPE_PVCOM\x10\x02\x12\x13\n\x0fDEVICE_TYPE_MSA\x10\x03\x12\x1e\n\x1aDEVICE_TYPE_SITECONTROLLER\x10\x04\x12\x19\n\x15DEVICE_TYPE_MEGAPUTER\x10\x05\x12\x13\n\x0fDEVICE_TYPE_IPM\x10\x06*j\n\x10DeviceCertFormat\x12\x1e\n\x1aDEVICE_CERT_FORMAT_INVALID\x10\x00\x12\x1a\n\x16DEVICE_CERT_FORMAT_DER\x10\x01\x12\x1a\n\x16DEVICE_CERT_FORMAT_PEM\x10\x02*e\n\x13DeviceSignatureType\x12!\n\x1dDEVICE_SIGNATURE_TYPE_INVALID\x10\x00\x12+\n\'DEVICE_SIGNATURE_TYPE_SHA256_ECDSA_ASN1\x10\x01*8\n\x06Cipher\x12\x12\n\x0eCIPHER_INVALID\x10\x00\x12\x1a\n\x16CIPHER_RSA_OAEP_SHA256\x10\x02*\xfb\x02\n\rTEGDeviceType\x12\x1b\n\x17TEG_DEVICE_TYPE_INVALID\x10\x00\x12\x17\n\x13TEG_DEVICE_TYPE_SMC\x10\x01\x12 \n\x1cTEG_DEVICE_TYPE_HEC_GATEWAY1\x10\x02\x12 \n\x1cTEG_DEVICE_TYPE_TEG_GATEWAY2\x10\x03\x12%\n!TEG_DEVICE_TYPE_TEG_POWERWALLPLUS\x10\x04\x12\x1b\n\x17TEG_DEVICE_TYPE_TEG_MP1\x10\x05\x12$\n TEG_DEVICE_TYPE_TEG_SUPERCHARGER\x10\x06\x12#\n\x1fTEG_DEVICE_TYPE_TACO_POWERWALL3\x10\x07\x12\x1b\n\x17TEG_DEVICE_TYPE_TEG_PVI\x10\x08\x12"\n\x1eTEG_DEVICE_TYPE_TACO_GATEWAY3V\x10\t\x12 \n\x1cTEG_DEVICE_TYPE_TACO_WALLBOX\x10\n*o\n\riPMDeviceType\x12\x1b\n\x17IPM_DEVICE_TYPE_INVALID\x10\x00\x12\x1e\n\x1aIPM_DEVICE_TYPE_POWERPACK3\x10\x01\x12!\n\x1dIPM_DEVICE_TYPE_SUPERCHARGER4\x10\x02Bz\n$com.tesla.generated.energy_device.v1B\x06DeviceZJgithub.com/teslamotors/energy_device/pkg/protocol/protobuf/energydevice/v1b\x06proto3')
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
 _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'device_pb2', _globals)
 if not _descriptor._USE_C_DESCRIPTORS:
     _globals['DESCRIPTOR']._loaded_options = None
     _globals['DESCRIPTOR']._serialized_options = b'\n$com.tesla.generated.energy_device.v1B\x06DeviceZJgithub.com/teslamotors/energy_device/pkg/protocol/protobuf/energydevice/v1'
-    _globals['_DEVICETYPE']._serialized_start = 456
-    _globals['_DEVICETYPE']._serialized_end = 641
-    _globals['_DEVICECERTFORMAT']._serialized_start = 643
-    _globals['_DEVICECERTFORMAT']._serialized_end = 749
-    _globals['_DEVICESIGNATURETYPE']._serialized_start = 751
-    _globals['_DEVICESIGNATURETYPE']._serialized_end = 852
-    _globals['_CIPHER']._serialized_start = 854
-    _globals['_CIPHER']._serialized_end = 910
-    _globals['_TEGDEVICETYPE']._serialized_start = 913
-    _globals['_TEGDEVICETYPE']._serialized_end = 1292
-    _globals['_IPMDEVICETYPE']._serialized_start = 1294
-    _globals['_IPMDEVICETYPE']._serialized_end = 1405
+    _globals['_DEVICETYPE']._serialized_start = 532
+    _globals['_DEVICETYPE']._serialized_end = 717
+    _globals['_DEVICECERTFORMAT']._serialized_start = 719
+    _globals['_DEVICECERTFORMAT']._serialized_end = 825
+    _globals['_DEVICESIGNATURETYPE']._serialized_start = 827
+    _globals['_DEVICESIGNATURETYPE']._serialized_end = 928
+    _globals['_CIPHER']._serialized_start = 930
+    _globals['_CIPHER']._serialized_end = 986
+    _globals['_TEGDEVICETYPE']._serialized_start = 989
+    _globals['_TEGDEVICETYPE']._serialized_end = 1368
+    _globals['_IPMDEVICETYPE']._serialized_start = 1370
+    _globals['_IPMDEVICETYPE']._serialized_end = 1481
     _globals['_DIN']._serialized_start = 46
     _globals['_DIN']._serialized_end = 66
     _globals['_ECUID']._serialized_start = 68
     _globals['_ECUID']._serialized_end = 119
-    _globals['_DEVICESIGNEDPAYLOAD']._serialized_start = 122
-    _globals['_DEVICESIGNEDPAYLOAD']._serialized_end = 358
-    _globals['_ENCRYPTEDMESSAGE']._serialized_start = 360
-    _globals['_ENCRYPTEDMESSAGE']._serialized_end = 453
+    _globals['_VIN']._serialized_start = 121
+    _globals['_VIN']._serialized_end = 141
+    _globals['_UUIDV4BYTES']._serialized_start = 143
+    _globals['_UUIDV4BYTES']._serialized_end = 171
+    _globals['_UUIDV4']._serialized_start = 173
+    _globals['_UUIDV4']._serialized_end = 195
+    _globals['_DEVICESIGNEDPAYLOAD']._serialized_start = 198
+    _globals['_DEVICESIGNEDPAYLOAD']._serialized_end = 434
+    _globals['_ENCRYPTEDMESSAGE']._serialized_start = 436
+    _globals['_ENCRYPTEDMESSAGE']._serialized_end = 529

packages/python/tesla_protocol/energy_device/device_pb2.pyi

@@ -96,6 +96,30 @@ class EcuId(_message.Message):
     def __init__(self, part_number: _Optional[str]=..., serial_number: _Optional[str]=...) -> None:
         ...
 
+class VIN(_message.Message):
+    __slots__ = ('value',)
+    VALUE_FIELD_NUMBER: _ClassVar[int]
+    value: str
+
+    def __init__(self, value: _Optional[str]=...) -> None:
+        ...
+
+class UUIDv4Bytes(_message.Message):
+    __slots__ = ('value',)
+    VALUE_FIELD_NUMBER: _ClassVar[int]
+    value: bytes
+
+    def __init__(self, value: _Optional[bytes]=...) -> None:
+        ...
+
+class UUIDv4(_message.Message):
+    __slots__ = ('text',)
+    TEXT_FIELD_NUMBER: _ClassVar[int]
+    text: str
+
+    def __init__(self, text: _Optional[str]=...) -> None:
+        ...
+
 class DeviceSignedPayload(_message.Message):
     __slots__ = ('payload', 'device_signature_type', 'signature', 'device_cert_format', 'device_cert')
     PAYLOAD_FIELD_NUMBER: _ClassVar[int]