Metadata-Version: 2.5
Name: rivian-python-client
Version: 2.6.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
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.0.0
Requires-Dist: cryptography>=41.0.1
Requires-Dist: protobuf<8,>=6.31.1
Provides-Extra: ble
Requires-Dist: bleak>=0.21; extra == 'ble'
Requires-Dist: dbus-fast>=2.11.0; (sys_platform == 'linux') and extra == 'ble'
Description-Content-Type: text/markdown

# 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
```

### Commands

`send_parallax_command` sends a signed command, such as unlocking
(`parallax.UNLOCK_RVM` with `parallax.encode_unlock()`; `LOCK_RVM` and
`encode_lock()` to lock), and `subscribe_for_parallax_command_state` follows it.
Subscribe first, then send:

```python
import uuid

from rivian import parallax


def on_state(data):
    if state := parallax.decode_command_state_message(data):
        print(state["progress"], state["status"], state["error"])


command_id = str(uuid.uuid4())
unsubscribe = await rivian.subscribe_for_parallax_command_state(
    vehicle_id, command_id, on_state
)
if unsubscribe:
    await rivian.send_parallax_command(
        vehicle_id,
        parallax.UNLOCK_RVM,
        parallax.encode_unlock(),
        identity_id=identity_id,
        vehicle_key=vehicle_key,
        private_key=private_key,
        command_id=command_id,
    )
    ...  # wait for the progress "complete", or give up
    await unsubscribe()
```

The keys are those of `send_vehicle_command`. The command is done when the progress
is `complete`, the status `success` and there is no `error`. If you never see that,
check the vehicle before sending it again. This unlocks a real vehicle, so keep the
keys secret.
