py-uconnect

Async Python client for the FCA/Stellantis Uconnect cloud API, used by the official apps of Fiat, Jeep, Alfa Romeo, Maserati, Chrysler, Dodge and Ram to show the vehicle state and send remote commands.

It powers the Uconnect Home Assistant integration. Version 1.0 is an async rewrite. If you are upgrading from 0.x, see the migration guide in CHANGELOG.md.

Installation

pip install py-uconnect

Python 3.11 or newer is required. The only dependency is aiohttp.

Quick start

import asyncio

from py_uconnect import Client
from py_uconnect.brands import FIAT_EU


async def main() -> None:
    async with Client(
        "foo@bar.com", "very_secret", pin="1234", brand=FIAT_EU
    ) as client:
        vehicles = await client.refresh()

        for vehicle in vehicles.values():
            print(vehicle.to_json(indent=2))


asyncio.run(main())

Client logs in on the first request and renews the credentials before they expire. The PIN is only needed for remote commands and settings changes and can be None otherwise.

To reuse an existing aiohttp.ClientSession, such as Home Assistant's shared session, pass it as session=. A session passed in is not closed by the client:

client = Client(email, password, pin, FIAT_EU, session=session)

Brands

Pick the configuration matching the brand of the app you use and the region of your account from py_uconnect.brands (or BRANDS by name):

Vehicle data

Client.refresh() loads the vehicles of the account into client.vehicles (a dict keyed by VIN) and returns it. Each Vehicle combines the vehicle list, the detailed status, the remote status and the last known location. Fields are None when the vehicle does not report them:

The raw responses are kept in raw_list_item, raw_info, raw_remote_status and raw_location, in case you need a value that is not parsed. to_dict(raw=True) and to_json(raw=True) include them.

Not every vehicle supports every endpoint. If an endpoint fails with an API error, the vehicle is kept with the data that is available, including the status snapshot some vehicles have in the vehicle list. Authentication and connection errors are raised.

Remote commands

from py_uconnect.command import COMMAND_DOORS_LOCK

vehicle = client.vehicles[vin]
if vehicle.supports(COMMAND_DOORS_LOCK):
    # Send the command and wait for the result reported by the vehicle
    ok = await client.command_verify(vin, COMMAND_DOORS_LOCK)

    # Or just send it, and wait later if needed
    correlation_id = await client.command(vin, COMMAND_DOORS_LOCK)
    ok = await client.wait_for_operation(vin, correlation_id, timeout=60)

command_verify() and wait_for_operation() return True if the vehicle reports success and False if it reports failure. If there is no result within timeout seconds they raise CommandTimeoutError. The result is polled from the remote operation status endpoint and, because that endpoint is not available in every region, from the vehicle notifications.

Client.command() sends the variant of a command that fits the vehicle, like the official apps: START_CHARGE instead of CNOW for vehicles with the CNOW2 service, the v2 deep refresh for vehicles with DEEPREFRESH2, and preconditioning instead of engine start/stop for vehicles that only support that. If the API rejects a command with HTTP 400, 403 or 404 and it has a newer variant, the variant is tried as well.

Vehicles with the ROHVACTMP service accept a target temperature for the climate control:

from py_uconnect import TemperatureUnit, hvac_params
from py_uconnect.command import COMMAND_HVAC_ON

await client.command_verify(vin, COMMAND_HVAC_ON, hvac_params(21.5))
await client.command_verify(
    vin, COMMAND_HVAC_ON, hvac_params(70, TemperatureUnit.FAHRENHEIT)
)

EV charging

from py_uconnect import ChargingLevel

await client.set_charging_level_verify(vin, ChargingLevel.LEVEL_THREE)

# Disable the first schedule
schedules = client.vehicles[vin].charge_schedules
schedules[0]["enableScheduleType"] = False
await client.set_charge_schedules_verify(vin, schedules)

max_soc is only supported by vehicles with the CSETTING2 service. The schedule format depends on the vehicle's schedule service, see docs/API.md; the client picks the right endpoint.

Other endpoints

client.api is the low-level API client: one method per endpoint, returning the decoded JSON as-is. For example:

report = await client.api.get_vehicle_health_report(vin)
recalls = await client.api.get_recalls(vin)
trip = await client.api.get_last_trip(vin)
alerts = await client.api.get_drive_alerts(vin)
await client.api.send_destination(vin, 45.0703, 7.6869, "Office")

Methods that change something require the PIN and return the correlation ID of the operation, which can be passed to client.wait_for_operation().

See docs/API.md for the endpoints behind them. Endpoints without a method can be called with client.api.request(). {uid} in the path is replaced with the account UID:

r = await client.api.request("GET", f"/v1/accounts/{{uid}}/vehicles/{vin}/vhr/")

Errors

All errors derive from py_uconnect.UconnectError:

Logging

The library logs to the py_uconnect logger. At DEBUG level it logs the API responses, which include vehicle data and location.

logging.getLogger("py_uconnect").setLevel(logging.DEBUG)

Command line

export UCONNECT_BRAND=FIAT_EU UCONNECT_EMAIL=foo@bar.com UCONNECT_PASSWORD=very_secret

uconnect vehicles                       # vehicles and their state as JSON
uconnect get get_vehicle_health_report VIN
uconnect --pin 1234 command VIN RDL     # lock the doors and wait for the result
uconnect raw GET '/v1/accounts/{uid}/vehicles/VIN/vhr/'

python -m py_uconnect works the same. Run uconnect --help for all options.

Service delivery platform

North American vehicles report an sdp field naming the connected services provider: SXM (SiriusXM Guardian) or SPRINT (Uconnect Access). It is None in the other regions. The provider does not change the API: all vehicles of a region use the same endpoints.

PIN authentication depends on the provider: the library uses the sdp of the vehicle, as the apps do, so call refresh() (or api.list_vehicles()) before sending commands.

If a SiriusXM Guardian vehicle does not show up, the account may still be a legacy Mopar account. Log in once with the official app for your brand and complete the account migration if it asks you to, then use the same credentials with this library.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy && pytest

The tests use a fake HTTP session and don't need network access. To run a read-only smoke test against your own account:

UCONNECT_EMAIL=... UCONNECT_PASSWORD=... UCONNECT_BRAND=FIAT_EU pytest tests/live -v