rivian-python-client 2.1.0__tar.gz → 2.2.0__tar.gz

{rivian_python_client-2.1.0 → rivian_python_client-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rivian-python-client
-Version: 2.1.0
+Version: 2.2.0
 Summary: Rivian API Client (Unofficial)
 Author-email: Brian Retterer <bretterer@gmail.com>, "J.R. Gutierrez" <jrgutier@gmail.com>, Nathan Spencer <natekspencer@gmail.com>, Trevor Mack <drummer8001@gmail.com>
 License-Expression: MIT
@@ -8,6 +8,7 @@ Requires-Python: >=3.10
 Requires-Dist: aiohttp>=3.0.0
 Requires-Dist: backports-strenum>=1.2.4; python_version < '3.11'
 Requires-Dist: cryptography>=41.0.1
+Requires-Dist: protobuf<8,>=6.31.1
 Requires-Dist: typing-extensions>=4.14.1; python_version < '3.11'
 Provides-Extra: ble
 Requires-Dist: bleak>=0.21; extra == 'ble'
@@ -40,3 +41,29 @@ pre-commit install
 ```
 uv run pytest
 ```
+
+## Parallax
+
+`subscribe_for_parallax_messages` streams the vehicle's Parallax RVM topics,
+whose payloads are protobuf. `rivian.parallax` decodes them into dicts keyed
+like the GraphQL vehicle state where a matching property exists:
+
+```python
+from rivian import parallax
+
+
+def on_message(data):
+    if decoded := parallax.decode_parallax_subscription_message(data):
+        print(decoded)
+```
+
+`parallax.PARALLAX_RVMS` lists every topic with a decoder, and
+`parallax.CHARGING_RVMS` the ones relevant to a charging session.
+
+The schemas in `src/rivian/parallax/proto/*.proto` are reverse-engineered. After
+editing one, regenerate its `*_pb2` modules (don't edit those by hand):
+
+```
+uv run python -m grpc_tools.protoc --proto_path=src --python_out=src \
+    --pyi_out=src src/rivian/parallax/proto/*.proto
+```

rivian_python_client-2.2.0/README.md

@@ -0,0 +1,52 @@
+# Python: Rivian API Client
+
+Currently a Work In Progress
+
+## Dependencies
+
+[uv](https://docs.astral.sh/uv/)
+
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## Setup
+
+Install project dependencies into the uv virtual environment and run pre-commit
+
+```
+uv sync --all-extras
+pre-commit install
+```
+
+## Run Tests
+
+```
+uv run pytest
+```
+
+## Parallax
+
+`subscribe_for_parallax_messages` streams the vehicle's Parallax RVM topics,
+whose payloads are protobuf. `rivian.parallax` decodes them into dicts keyed
+like the GraphQL vehicle state where a matching property exists:
+
+```python
+from rivian import parallax
+
+
+def on_message(data):
+    if decoded := parallax.decode_parallax_subscription_message(data):
+        print(decoded)
+```
+
+`parallax.PARALLAX_RVMS` lists every topic with a decoder, and
+`parallax.CHARGING_RVMS` the ones relevant to a charging session.
+
+The schemas in `src/rivian/parallax/proto/*.proto` are reverse-engineered. After
+editing one, regenerate its `*_pb2` modules (don't edit those by hand):
+
+```
+uv run python -m grpc_tools.protoc --proto_path=src --python_out=src \
+    --pyi_out=src src/rivian/parallax/proto/*.proto
+```

{rivian_python_client-2.1.0 → rivian_python_client-2.2.0}/pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
     "cryptography (>=41.0.1)",
     "backports-strenum (>=1.2.4) ; python_version < '3.11'",
     "typing_extensions (>=4.14.1) ; python_version < '3.11'",
+    "protobuf>=6.31.1,<8",
 ]
 dynamic = ["version"]
 
@@ -33,8 +34,18 @@ dev = [
     "mypy>=1.7,<3.0",
     "ruff>=0.16,<0.17",
     "pre-commit>=4.6.1,<5",
+    "types-protobuf>=6.32.1.20260221",
+    "grpcio-tools==1.80.0",
+    "pytest-cov>=7.0,<8",
 ]
 
+[tool.coverage.run]
+source = ["rivian"]
+omit = ["*_pb2.py"]
+
+[tool.coverage.report]
+exclude_also = ["if TYPE_CHECKING:"]
+
 [tool.hatch.build.hooks.version]
 path = "src/rivian/__version__.py"
 
@@ -57,10 +68,13 @@ cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true
 [tool.uv-dynamic-versioning]
 pattern = "default-unprefixed"
 
+[tool.ruff]
+extend-exclude = ["*_pb2.py", "*_pb2.pyi"]
+
 [tool.ruff.lint.isort]
 combine-as-imports = true
 split-on-trailing-comma = false
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]
-build-backend = "hatchling.build"
+build-backend = "hatchling.build"

{rivian_python_client-2.1.0 → rivian_python_client-2.2.0}/src/rivian/__version__.py

@@ -1,4 +1,4 @@
 # This file is auto-generated by Hatchling. As such, do not:
 #   - modify
 #   - track in version control e.g. be sure to add to .gitignore
-__version__ = VERSION = '2.1.0'
+__version__ = VERSION = '2.2.0'

rivian_python_client-2.2.0/src/rivian/parallax/__init__.py

@@ -0,0 +1,70 @@
+"""Decoders for Rivian Parallax protobuf payloads.
+
+Public API:
+    decode_parallax_message(rvm, payload, timestamp=None, **kwargs) -> dict | None
+        Adds `timestamp` (epoch milliseconds) as a UTC datetime if given.
+    decode_parallax_subscription_message(data) -> dict | None
+        Same, for a raw `subscribe_for_parallax_messages` message.
+    PARALLAX_RVMS: list[str]  — every RVM with a registered decoder
+    CHARGING_RVMS: list[str]  — the subset relevant to a charging session
+
+Layout:
+    core.py  - registry, payload parsing and shared helpers
+    proto/   - .proto schemas and their generated *_pb2 modules
+    <topic prefix>.py - one module per RVM topic prefix (body.*, etc.)
+
+To add a decoder, decorate it with
+`@RVMDecoder.register("the.rvm.topic", some_pb2.Message)` in its prefix's
+module; a new module also needs adding to the import list below.
+"""
+
+from __future__ import annotations
+
+from . import (  # noqa: F401  (imported to register their decoders)
+    body,
+    charging,
+    comfort,
+    departure,
+    device_table,
+    dynamics,
+    energy,
+    energy_edge_compute,
+    gearguard_streaming,
+    geofence,
+    holiday_celebration,
+    navigation,
+    ota,
+    parallax,
+    secure_file_transfer,
+    security,
+    user_passcodes,
+    vehicle,
+    vehicle_access,
+)
+from .core import (
+    RVMDecoder,
+    decode_parallax_message,
+    decode_parallax_subscription_message,
+)
+
+PARALLAX_RVMS: list[str] = list(RVMDecoder.decoders)
+
+CHARGING_RVMS: list[str] = [
+    "charging.energy.state",
+    "charging.session.notification",
+    "charging.session.power",
+    "charging.session.remote_command",
+    "charging.session.soc_slider",
+    "charging.session.status",
+    "charging.session.time_estimation",
+    "energy.high_voltage.battery_state",
+    "energy_edge_compute.graphs.charge_session_breakdown",
+    "energy_edge_compute.graphs.charging_graph_global",
+]
+
+__all__ = [
+    "CHARGING_RVMS",
+    "PARALLAX_RVMS",
+    "decode_parallax_message",
+    "decode_parallax_subscription_message",
+]

rivian_python_client-2.2.0/src/rivian/parallax/body.py

@@ -0,0 +1,260 @@
+"""Decoders for `body.*` RVM topics: closures, locks, trailer."""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from .core import _LOGGER, RVMDecoder, _enum, _present
+from .proto import body_pb2
+
+_CLOSURE_MAP: Final[dict[int, str]] = {
+    body_pb2.DOOR_FRONT_LEFT: "doorFrontLeftClosed",
+    body_pb2.DOOR_FRONT_RIGHT: "doorFrontRightClosed",
+    body_pb2.DOOR_REAR_LEFT: "doorRearLeftClosed",
+    body_pb2.DOOR_REAR_RIGHT: "doorRearRightClosed",
+    body_pb2.FRUNK: "closureFrunkClosed",
+    body_pb2.TAILGATE: "closureTailgateClosed",
+    body_pb2.LIFTGATE: "closureLiftgateClosed",
+    body_pb2.SIDE_BIN_LEFT: "closureSideBinLeftClosed",
+    body_pb2.SIDE_BIN_RIGHT: "closureSideBinRightClosed",
+    body_pb2.CHARGE_PORT: "chargePortState",
+    body_pb2.TONNEAU: "closureTonneauClosed",
+    body_pb2.WINDOW_FRONT_LEFT: "windowFrontLeftClosed",
+    body_pb2.WINDOW_FRONT_RIGHT: "windowFrontRightClosed",
+    body_pb2.WINDOW_REAR_LEFT: "windowRearLeftClosed",
+    body_pb2.WINDOW_REAR_RIGHT: "windowRearRightClosed",
+    body_pb2.WINDOW_REAR: "windowRearClosed",
+}
+
+_CLOSURE_STATE_MAP: Final[dict[int, str]] = {
+    body_pb2.CLOSURE_STATE_OPEN: "open",
+    body_pb2.CLOSURE_STATE_CLOSED: "closed",
+    body_pb2.CLOSURE_STATE_AJAR: "ajar",
+    body_pb2.CLOSURE_STATE_OPENING: "opening",
+    body_pb2.CLOSURE_STATE_CLOSING: "closing",
+}
+
+
+def _enum_names(enum: Any, prefix: str) -> dict[int, str]:
+    """Map an enum's numbers to its lowercased names, minus `prefix`."""
+    return {
+        value.number: value.name.removeprefix(prefix).lower()
+        for value in enum.DESCRIPTOR.values
+    }
+
+
+_SIDE_BIN_NEXT_ACTIONS: Final = _enum_names(body_pb2.SideBinNextAction, "SIDE_BIN_")
+
+# Closure id -> (next-action field, result key, value names).
+_NEXT_ACTIONS: Final[dict[int, tuple[str, str, dict[int, str]]]] = {
+    body_pb2.FRUNK: (
+        "frunk_next_action",
+        "closureFrunkNextAction",
+        _enum_names(body_pb2.FrunkNextAction, "FRUNK_"),
+    ),
+    body_pb2.LIFTGATE: (
+        "liftgate_next_action",
+        "closureLiftgateNextAction",
+        _enum_names(body_pb2.LiftgateNextAction, "LIFTGATE_"),
+    ),
+    body_pb2.SIDE_BIN_LEFT: (
+        "side_bin_next_action",
+        "closureSideBinLeftNextAction",
+        _SIDE_BIN_NEXT_ACTIONS,
+    ),
+    body_pb2.SIDE_BIN_RIGHT: (
+        "side_bin_next_action",
+        "closureSideBinRightNextAction",
+        _SIDE_BIN_NEXT_ACTIONS,
+    ),
+    body_pb2.TAILGATE: (
+        "tailgate_next_action",
+        "closureTailgateNextAction",
+        _enum_names(body_pb2.TailgateNextAction, "TAILGATE_"),
+    ),
+    body_pb2.CHARGE_PORT: (
+        "charge_port_door_next_action",
+        "closureChargePortDoorNextAction",
+        _enum_names(body_pb2.ChargePortDoorNextAction, "CHARGE_PORT_DOOR_"),
+    ),
+    body_pb2.GROUP_WINDOWS: (
+        "windows_next_action",
+        "windowsNextAction",
+        _enum_names(body_pb2.WindowsNextAction, "WINDOWS_"),
+    ),
+}
+
+_LOCK_MAP: Final[dict[int, str]] = {
+    body_pb2.LOCK_DOOR_FRONT_LEFT: "doorFrontLeftLocked",
+    body_pb2.LOCK_DOOR_FRONT_RIGHT: "doorFrontRightLocked",
+    body_pb2.LOCK_DOOR_REAR_LEFT: "doorRearLeftLocked",
+    body_pb2.LOCK_DOOR_REAR_RIGHT: "doorRearRightLocked",
+    body_pb2.LOCK_FRUNK: "closureFrunkLocked",
+    body_pb2.LOCK_TAILGATE: "closureTailgateLocked",
+    body_pb2.LOCK_LIFTGATE: "closureLiftgateLocked",
+    body_pb2.LOCK_SIDE_BIN_LEFT: "closureSideBinLeftLocked",
+    body_pb2.LOCK_SIDE_BIN_RIGHT: "closureSideBinRightLocked",
+    body_pb2.LOCK_CHARGE_PORT: "closureChargePortLocked",
+    body_pb2.LOCK_TRUNK_SECURITY: "closureTrunkSecurityLocked",
+    body_pb2.LOCK_CENTER_CONSOLE: "closureCenterConsoleLocked",
+    body_pb2.LOCK_GLOVE_BOX: "closureGloveBoxLocked",
+    body_pb2.LOCK_GEAR_GUARD: "gearGuardLocked",
+    body_pb2.LOCK_TONNEAU: "closureTonneauLocked",
+}
+
+_LOCK_STATE_MAP: Final[dict[int, str]] = {
+    body_pb2.LOCK_STATE_LOCKED: "locked",
+    body_pb2.LOCK_STATE_UNLOCKED: "unlocked",
+    body_pb2.LOCK_STATE_PARTIALLY_UNLOCKED: "partially_unlocked",
+}
+
+_REAR_HITCH_STATUS_MAP: Final[dict[int, str]] = {
+    body_pb2.REAR_HITCH_STATUS_NOT_PRESENT: "not_present",
+    body_pb2.REAR_HITCH_STATUS_ACCESSORY: "accessory",
+    body_pb2.REAR_HITCH_STATUS_TRAILER1: "trailer1",
+    body_pb2.REAR_HITCH_STATUS_TRAILER2: "trailer2",
+    body_pb2.REAR_HITCH_STATUS_TRAILER3: "trailer3",
+}
+
+_WINDOW_MAP: Final[dict[int, str]] = {
+    body_pb2.WINDOW_INSTANCE_FRONT_LEFT: "windowFrontLeftCalibrated",
+    body_pb2.WINDOW_INSTANCE_FRONT_RIGHT: "windowFrontRightCalibrated",
+    body_pb2.WINDOW_INSTANCE_REAR_LEFT: "windowRearLeftCalibrated",
+    body_pb2.WINDOW_INSTANCE_REAR_RIGHT: "windowRearRightCalibrated",
+    body_pb2.WINDOW_INSTANCE_REAR: "windowRearCalibrated",
+}
+
+# GraphQL's windowXCalibrated values.
+_CALIBRATION_MAP: Final[dict[int, str]] = {
+    body_pb2.CALIBRATION_STATUS_CALIBRATED: "calibrated",
+    body_pb2.CALIBRATION_STATUS_NOT_CALIBRATED: "not_calibrated",
+}
+
+_TRAILER_PRESENCE_MAP: Final[dict[int, str]] = {
+    body_pb2.TRAILER_NOT_PRESENT: "trailer_not_present",
+    body_pb2.TRAILER_PRESENT: "trailer_present",
+    body_pb2.TRAILER_PRESENT_WITH_BRAKES: "trailer_present_with_brakes",
+    body_pb2.TRAILER_INVALID: "trailer_invalid",
+}
+
+
+@RVMDecoder.register("body.closures.states", body_pb2.ClosuresState)
+def decode_closures(m: body_pb2.ClosuresState) -> dict[str, Any]:
+    """body.closures.states — state of every door, window and closure.
+
+    Fields:
+        doorFrontLeftClosed, closureFrunkClosed, etc.: str
+            ("open" | "closed" | "ajar" | "opening" | "closing")
+        closureFrunkNextAction, closureLiftgateNextAction,
+        closureTailgateNextAction, closureSideBinLeftNextAction,
+        closureSideBinRightNextAction, closureChargePortDoorNextAction,
+        windowsNextAction: str — e.g. "open_allowed" (shut),
+            "close_allowed" (open); for the charge port,
+            "close_not_available" means plugged in
+
+    `chargePortState` can lag the door (e.g. "opening" until plugged in),
+    so prefer its next action. After an app command, next actions briefly
+    drop to "sna" / "open_not_available".
+    """
+    result: dict[str, Any] = {}
+    for s in m.closure:
+        cid = s.id
+        state_val = _present(s, "state")
+        if cid in _CLOSURE_MAP:
+            result[_CLOSURE_MAP[cid]] = _enum(
+                _CLOSURE_STATE_MAP, state_val, what="closure state"
+            )
+        elif cid != body_pb2.GROUP_WINDOWS:
+            _LOGGER.debug("Unknown closure id %s (state %s)", cid, state_val)
+        if cid in _NEXT_ACTIONS:
+            field, key, names = _NEXT_ACTIONS[cid]
+            if (next_action := _present(s, field)) is not None:
+                result[key] = _enum(names, next_action, what=f"{key} value")
+    return result
+
+
+@RVMDecoder.register("body.locks.states", body_pb2.LocksState)
+def decode_locks(m: body_pb2.LocksState) -> dict[str, Any]:
+    """body.locks.states — lock state of every lock.
+
+    Fields:
+        doorFrontLeftLocked, closureFrunkLocked, gearGuardLocked (the Gear
+            Guard cable), etc.: str ("locked" | "unlocked" |
+            "partially_unlocked")
+    """
+    result: dict[str, Any] = {}
+    for s in m.lock:
+        lid = s.id
+        state_val = _present(s, "state")
+        if state_val is None:
+            continue
+        if lid in _LOCK_MAP:
+            result[_LOCK_MAP[lid]] = _enum(
+                _LOCK_STATE_MAP, state_val, what="lock state"
+            )
+        else:
+            _LOGGER.debug("Unknown lock id %s (state %s)", lid, state_val)
+    return result
+
+
+@RVMDecoder.register("body.windows.states", body_pb2.WindowsState)
+def decode_windows(m: body_pb2.WindowsState) -> dict[str, Any]:
+    """body.windows.states — window calibration.
+
+    Fields:
+        windowFrontLeftCalibrated, windowFrontRightCalibrated,
+        windowRearLeftCalibrated, windowRearRightCalibrated,
+        windowRearCalibrated: str ("calibrated" | "not_calibrated")
+    """
+    return {
+        _WINDOW_MAP[w.instance]: _enum(
+            _CALIBRATION_MAP, w.calibration_status or None, what="window calibration"
+        )
+        for w in m.window
+        if w.instance in _WINDOW_MAP
+    }
+
+
+@RVMDecoder.register("body.trailer.state", body_pb2.TrailerState)
+def decode_trailer_state(m: body_pb2.TrailerState) -> dict[str, Any]:
+    """body.trailer.state — trailer presence and rear hitch status.
+
+    Fields:
+        trailerStatus: str
+        rearHitchStatus: str | None ("not_present" | "accessory" |
+            "trailer1" | "trailer2" | "trailer3")
+    """
+    result: dict[str, Any] = {
+        "rearHitchStatus": _enum(
+            _REAR_HITCH_STATUS_MAP, m.rear_hitch_status or None, what="rear hitch"
+        )
+    }
+    presence = _enum(
+        _TRAILER_PRESENCE_MAP, _present(m, "presence"), what="trailer presence"
+    )
+    if presence is not None:
+        result["trailerStatus"] = presence
+    return result
+
+
+@RVMDecoder.register("body.wipers.fluid_level", body_pb2.WiperFluidLevel)
+def decode_wiper_fluid_level(m: body_pb2.WiperFluidLevel) -> dict[str, Any]:
+    """body.wipers.fluid_level — washer fluid level.
+
+    The value numbering is a best guess.
+
+    Fields:
+        wiperFluidState: str | None ("normal" | "low" | "empty")
+    """
+    return {
+        "wiperFluidState": _enum(
+            _WIPER_FLUID_STATE_MAP, m.state or None, what="wiper fluid state"
+        )
+    }
+
+
+_WIPER_FLUID_STATE_MAP: Final[dict[int, str]] = {
+    body_pb2.WIPER_FLUID_STATE_NORMAL: "normal",
+    body_pb2.WIPER_FLUID_STATE_LOW: "low",
+    body_pb2.WIPER_FLUID_STATE_EMPTY: "empty",
+}