PyCupra

https://github.com/wulfgarw/pycupra
Admin
A Python library to read and send vehicle data via Cupra/Seat portal using the same API calls as the...
Tokens:12,081
Snippets:74
Trust Score:7.1
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete PyCupra Integration Example

Source: https://context7.com/wulfgarw/pycupra/llms.txt

This script demonstrates how to use PyCupra to log in, retrieve vehicle details, and interact with vehicle features. It requires credentials from 'pycupra_credentials.json' and a 'token.json' file for authentication. The 'anonymise' flag is set to True for privacy in logs.

```python
import asyncio
import json
from aiohttp import ClientSession
from pycupra import Connection

async def full_example():
    with open('./pycupra_credentials.json') as f:
        creds = json.load(f)

    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(
            session, creds['brand'], creds['username'], creds['password'],
            nightlyUpdateReduction=True, anonymise=True
        )

        if not await conn.doLogin(tokenFile='./token.json'):
            print("Login failed"); return

        await conn.get_vehicles()

        for v in conn.vehicles:
            print(f"\n=== {v.model} ({v.vin[-4:]}) ===")
            print(f"Online: {v.vehicle_online}")

            # Battery / charging
            if v.is_battery_level_supported:
                print(f"Battery: {v.battery_level}%  |  Range: {v.electric_range} km")
            if v.is_charging_supported:
                print(f"Charging: {v.charging_state}  |  Mode: {v.charging_mode}")

            # Doors
            print(f"Locked: {v.doors_locked}  |  Windows closed: {v.windows_closed}")

            # Climatisation
            if v.is_climatisation_supported:
                print(f"Climatisation: {v.electric_climatisation}  |  Temp: {v.climatisation_target_temperature}°C")

            # Example action: start charging if battery < 30%
            if v.is_battery_level_supported and v.battery_level < 30:
                if v.is_charging_cable_connected_supported and v.charging_cable_connected:
                    await v.set_charger('start')
                    print("Auto-started charging (low battery)")

        await conn.terminate()

asyncio.run(full_example())

```

--------------------------------

### Control vehicle charging process

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Manages charging by starting, stopping, setting current limits, target state of charge, and battery care mode. Handles potential exceptions like requests already in progress or invalid requests.

```python
from pycupra.exceptions import PyCupraInvalidRequestException, PyCupraRequestInProgressException

async def manage_charging(v):
    try:
        # Start charging
        if await v.set_charger('start'):
            print("Charging started")

        # Stop charging
        if await v.set_charger('stop'):
            print("Charging stopped")

        # Set max current to reduced (slow charge)
        if await v.set_charger_current('reduced'):
            print("Charge current set to reduced")

        # Set target state of charge to 80%
        if await v.set_charger_target_soc(80):
            print("Target SoC set to 80%")

        # Enable battery care mode
        if await v.set_battery_care(True):
            print("Battery care enabled")

    except PyCupraRequestInProgressException:
        print("Another charging action is already in progress")
    except PyCupraInvalidRequestException as e:
        print(f"Invalid request: {e}")
```

--------------------------------

### Vehicle.set_charger

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Controls charging by starting, stopping, or configuring charging settings such as charge current, target SoC, and battery care mode.

```APIDOC
### `Vehicle.set_charger` — Start / stop / configure charging

Controls charging: starts or stops the charging process, or changes settings (charge current, target SoC, battery care mode).

```python
from pycupra.exceptions import PyCupraInvalidRequestException, PyCupraRequestInProgressException

async def manage_charging(v):
    try:
        # Start charging
        if await v.set_charger('start'):
            print("Charging started")

        # Stop charging
        if await v.set_charger('stop'):
            print("Charging stopped")

        # Set max current to reduced (slow charge)
        if await v.set_charger_current('reduced'):
            print("Charge current set to reduced")

        # Set target state of charge to 80%
        if await v.set_charger_target_soc(80):
            print("Target SoC set to 80%")

        # Enable battery care mode
        if await v.set_battery_care(True):
            print("Battery care enabled")

    except PyCupraRequestInProgressException:
        print("Another charging action is already in progress")
    except PyCupraInvalidRequestException as e:
        print(f"Invalid request: {e}")
```
```

--------------------------------

### Manage Vehicle Climatisation

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Starts, stops, or modifies electric or auxiliary climatisation. Use 'start' or 'auxiliary_start' with an optional temperature and SPIN. Use 'stop' to disable. Individual settings can be changed with `set_climatisation_one_setting`.

```python
async def manage_climate(v, spin='1234'):
    # Start electric climatisation at 21 °C
    await v.set_climatisation('start', temp=21.0)

    # Start auxiliary heater (requires SPIN)
    await v.set_climatisation('auxiliary_start', temp=20.0, spin=spin)

    # Stop climatisation
    await v.set_climatisation('stop')

    # Change a single climatisation setting
    await v.set_climatisation_one_setting('targetTemperatureInCelsius', 22.0)
    await v.set_climatisation_one_setting('climatisationWithoutExternalPower', False)
    await v.set_climatisation_one_setting('zoneFrontRightEnabled', True)

    # Control window heater independently
    await v.set_window_heating('start')
    await v.set_window_heating('stop')
```

--------------------------------

### Vehicle.set_climatisation

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Starts or stops electric or auxiliary climatisation, optionally with a target temperature and SPIN.

```APIDOC
## Vehicle.set_climatisation

### Description
Starts or stops electric or auxiliary climatisation, optionally with a target temperature and SPIN (S-PIN for auxiliary heater).

### Method
Asynchronous function call within the Vehicle object.

### Parameters
- **action** (string) - Required - 'start', 'auxiliary_start', or 'stop'.
- **temp** (float) - Optional - Target temperature in Celsius.
- **spin** (string) - Optional - S-PIN for auxiliary heater.

### Request Example
```python
await v.set_climatisation('start', temp=21.0)
await v.set_climatisation('auxiliary_start', temp=20.0, spin='1234')
await v.set_climatisation('stop')
```

### Related Functions
- `set_climatisation_one_setting(setting_name, value)`: Changes a single climatisation setting.
- `set_window_heating(action)`: Controls window heating independently ('start' or 'stop').
```

--------------------------------

### Connection.__init__

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Initializes a new connection session to the Cupra/Seat cloud. Requires an existing aiohttp.ClientSession and credentials. Supports both Cupra and Seat brands via the `brand` parameter.

```APIDOC
## Connection.__init__ 

### Description
Initializes a new connection session to the Cupra/Seat cloud. Requires an existing `aiohttp.ClientSession` and credentials. Supports both Cupra and Seat brands via the `brand` parameter.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from aiohttp import ClientSession
from pycupra import Connection

async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        connection = Connection(
            session=session,
            brand='cupra',            # or 'seat'
            username='user@email.com',
            password='s3cret',
            fulldebug=False,
            nightlyUpdateReduction=False,  # Skip updates between 22:00-05:00
            anonymise=True,           # Mask PII in logs
            tripStatisticsStartDate='2024-01-01',  # YYYY-MM-DD or None
        )

asyncio.run(main())
```

### Response
None (initializes an object)

### Response Example
None
```

--------------------------------

### Initialize PyCupra Connection

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Creates a new connection session to the Cupra/Seat cloud. Requires an existing aiohttp.ClientSession and credentials. Supports both Cupra and Seat brands via the `brand` parameter.

```python
import asyncio
from aiohttp import ClientSession
from pycupra import Connection

async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        connection = Connection(
            session=session,
            brand='cupra',            # or 'seat'
            username='user@email.com',
            password='s3cret',
            fulldebug=False,
            nightlyUpdateReduction=False,  # Skip updates between 22:00-05:00
            anonymise=True,           # Mask PII in logs
            tripStatisticsStartDate='2024-01-01',  # YYYY-MM-DD or None
        )

asyncio.run(main())
```

--------------------------------

### Connection.doLogin

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Authenticates with the portal. Attempts to reuse and refresh tokens from a local JSON file first; falls back to full OAuth2 PKCE login with username and password if tokens are absent or expired.

```APIDOC
## Connection.doLogin 

### Description
Authenticates with the portal. Attempts to reuse and refresh tokens from a local JSON file first; falls back to full OAuth2 PKCE login with username and password if tokens are absent or expired.

### Method
POST (implied by login action)

### Endpoint
(Internal API call, not a direct HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from aiohttp import ClientSession
from pycupra import Connection
from pycupra.exceptions import (
    PyCupraAuthenticationException,
    PyCupraAccountLockedException,
    PyCupraEULAException,
)

async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        connection = Connection(session, 'cupra', 'user@email.com', 's3cret')
        try:
            ok = await connection.doLogin(
                tokenFile='./pycupra_token.json',   # optional: persist/reuse tokens
                apiKey='GOOGLE_MAPS_API_KEY',       # optional: enable address lookup
            )
            if ok:
                print("Login successful")
            else:
                print("Login failed")
        except PyCupraAuthenticationException:
            print("Wrong credentials")
        except PyCupraAccountLockedException as e:
            print(f"Account locked: {e}")
        except PyCupraEULAException:
            print("Must accept updated terms at cupraid.vwgroup.io")

asyncio.run(main())
```

### Response
#### Success Response (Boolean)
- **ok** (bool) - True if login was successful, False otherwise.

#### Response Example
(No explicit response example provided, but the code checks for `ok` being True or False)

### Error Handling
- `PyCupraAuthenticationException`: Raised for wrong credentials.
- `PyCupraAccountLockedException`: Raised if the account is locked.
- `PyCupraEULAException`: Raised if updated terms need to be accepted.
```

--------------------------------

### Authenticate with PyCupra Portal

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Attempts to reuse and refresh tokens from a local JSON file first; falls back to full OAuth2 PKCE login with username and password if tokens are absent or expired. Handles potential authentication and account-related exceptions.

```python
import asyncio
from aiohttp import ClientSession
from pycupra import Connection
from pycupra.exceptions import (
    PyCupraAuthenticationException,
    PyCupraAccountLockedException,
    PyCupraEULAException,
)

async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        connection = Connection(session, 'cupra', 'user@email.com', 's3cret')
        try:
            ok = await connection.doLogin(
                tokenFile='./pycupra_token.json',   # optional: persist/reuse tokens
                apiKey='GOOGLE_MAPS_API_KEY',       # optional: enable address lookup
            )
            if ok:
                print("Login successful")
            else:
                print("Login failed")
        except PyCupraAuthenticationException:
            print("Wrong credentials")
        except PyCupraAccountLockedException as e:
            print(f"Account locked: {e}")
        except PyCupraEULAException:
            print("Must accept updated terms at cupraid.vwgroup.io")

asyncio.run(main())
```

--------------------------------

### Fetch Vehicles and Populate State

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Fetches all vehicles registered to the account, queries their capabilities and connectivity status, creates `Vehicle` objects, and performs an initial full data update for each vehicle.

```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')

        vehicles = await conn.get_vehicles()

        for v in conn.vehicles:
            print(f"VIN: {v.vin}")
            print(f"Model: {v.model} ({v.model_year})")
            print(f"Online: {v.vehicle_online}")
            print(f"Battery: {v.battery_level}%")
            print(f"Range (electric): {v.electric_range} km")
```

--------------------------------

### Connection.get_vehicles

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Fetches all vehicles registered to the account, queries their capabilities and connectivity status, creates `Vehicle` objects, and performs an initial full data update for each vehicle.

```APIDOC
## Connection.get_vehicles 

### Description
Fetches all vehicles registered to the account, queries their capabilities and connectivity status, creates `Vehicle` objects, and performs an initial full data update for each vehicle.

### Method
GET (implied by fetching data)

### Endpoint
(Internal API call, not a direct HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')

        vehicles = await conn.get_vehicles()

        for v in conn.vehicles:
            print(f"VIN: {v.vin}")
            print(f"Model: {v.model} ({v.model_year})")
            print(f"Online: {v.vehicle_online}")
            print(f"Battery: {v.battery_level}%")
            print(f"Range (electric): {v.electric_range} km")
```

### Response
#### Success Response (List of Vehicle objects)
- The method populates `conn.vehicles` with `Vehicle` objects.
- Each `Vehicle` object has properties like `vin`, `model`, `model_year`, `vehicle_online`, `battery_level`, `electric_range`.

#### Response Example
(No explicit response example provided, but the code iterates through `conn.vehicles` and prints attributes.)
```

--------------------------------

### EUDAConnection.readTripStatisticsFile

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Loads cached local trip statistics data if available.

```APIDOC
## EUDAConnection.readTripStatisticsFile

### Description
Loads cached local trip statistics data if present. This is a synchronous method.

### Method
Synchronous function call within the EUDAConnection object.

### Parameters
None

### Response
None. This method primarily affects the internal state of the `EUDAConnection` object by loading data into memory.
```

--------------------------------

### Configure Departure Timers

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sets schedules for departure timers, supporting recurring or single events, off-peak charging, and climatisation. Timers can be activated or deactivated using `set_timer_active`. Also sets minimum SoC for charging.

```python
async def configure_timer(v):
    # Recurring weekly timer: Mon/Tue departure at 07:30
    await v.set_timer_schedule(
        id=1,
        schedule={
            "enabled": True,
            "recurring": True,
            "time": "07:30",
            "days": "yynnnnn",          # Mon=y, Tue=y, rest=n
            "nightRateActive": True,
            "nightRateStart": "22:00",
            "nightRateEnd": "06:00",
            "operationCharging": True,
            "operationClimatisation": True,
        }
    )

    # Single one-shot timer
    await v.set_timer_schedule(
        id=2,
        schedule={
            "enabled": True,
            "recurring": False,
            "date": "2025-12-24",
            "time": "08:00",
            "operationCharging": True,
            "operationClimatisation": False,
        }
    )

    # Activate / deactivate a timer without changing its schedule
    await v.set_timer_active(id=1, action='on')
    await v.set_timer_active(id=2, action='off')

    # Set minimum SoC for departure timer charging
    await v.set_charge_limit(30)   # 0, 10, 20, 30, 40, or 50 percent
```

--------------------------------

### Fetch User Account Profile

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Retrieves the authenticated user's profile information (name, nickname, email) from the portal. Assumes a successful login has already occurred.

```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')

        user = await conn.get_userData()
        print(f"Name: {user.get('name', 'N/A')}")
        print(f"Nickname: {user.get('nickname', 'N/A')}")
        print(f"Email: {user.get('email', 'N/A')}")
```

--------------------------------

### Vehicle.set_refresh

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sends a wake-up request to the vehicle, causing it to push fresh data to the cloud.

```APIDOC
## Vehicle.set_refresh

### Description
Sends a wake-up request to the vehicle, causing it to push fresh data to the cloud. Waits for confirmation that the `updatedAt` timestamp in the status report changes.

### Method
Asynchronous function call within the Vehicle object.

### Parameters
None

### Request Example
```python
await v.set_refresh()
```

### Response
- **Success Response**: Returns `True` if the vehicle data was refreshed successfully.

### Prerequisites
- `is_refresh_data_supported` must be `True` for this function to be available.

### Status Information
- `last_connected`: Timestamp of the last connection after refresh.
```

--------------------------------

### EUDAConnection.update

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Downloads new data files from the EUDA portal.

```APIDOC
## EUDAConnection.update

### Description
Downloads new data files from the EUDA portal. This method should be called after `getVehicles` to ensure the latest data is available.

### Method
Asynchronous function call within the EUDAConnection object.

### Parameters
None

### Response
- **updated** (bool) - True if new data was downloaded, False otherwise.
```

--------------------------------

### Connection.get_userData

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Retrieves the authenticated user's profile information (name, nickname, email) from the portal.

```APIDOC
## Connection.get_userData 

### Description
Retrieves the authenticated user's profile information (name, nickname, email) from the portal.

### Method
GET (implied by fetching data)

### Endpoint
(Internal API call, not a direct HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')

        user = await conn.get_userData()
        print(f"Name: {user.get('name', 'N/A')}")
        print(f"Nickname: {user.get('nickname', 'N/A')}")
        print(f"Email: {user.get('email', 'N/A')}")
```

### Response
#### Success Response (Dictionary)
- **user** (dict) - A dictionary containing user profile information.
  - **name** (str) - The user's name.
  - **nickname** (str) - The user's nickname.
  - **email** (str) - The user's email address.

#### Response Example
(No explicit response example provided, but the code accesses keys like 'name', 'nickname', 'email'.)
```

--------------------------------

### Force Vehicle Data Refresh

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sends a wake-up request to the vehicle to push fresh data to the cloud. Waits for confirmation that the `updatedAt` timestamp changes. Checks if remote wake-up is supported before attempting.

```python
async def force_update(v):
    if v.is_refresh_data_supported:
        if await v.set_refresh():
            print(f"Vehicle data refreshed. Last connected: {v.last_connected}")
    else:
        print("Remote wake-up not supported for this vehicle")
```

--------------------------------

### Update vehicle data (full or incremental)

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Updates vehicle state from the cloud. `updateType=0` is a small update (status + basic data), `updateType=1` is a full refresh of all endpoints, `updateType=2` is a small update bypassing nightly reduction. Use `updateType=1` for comprehensive data and `updateType=0` for quick status checks.

```python
async def main():
    # ... setup conn and get_vehicles() ...
    for v in conn.vehicles:
        # Full update (all endpoints)
        await v.update(updateType=1)

        # Small update (fast, only status and basic car data)
        await v.update(updateType=0)

        print(f"Last full update: {v.last_full_update}")
        print(f"Last connected: {v.last_connected}")
```

--------------------------------

### Configure Climatisation Timers

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sets schedules for dedicated climatisation timers, separate from departure timers. Supports recurring schedules and can be toggled on/off using `set_climatisation_timer_active`.

```python
async def configure_clima_timer(v):
    await v.set_climatisation_timer_schedule(
        id=1,
        schedule={
            "enabled": True,
            "recurring": True,
            "time": "06:45",
            "days": "yyyyyyn",   # Mon–Sat enabled
        }
    )

    # Toggle a climatisation timer on or off
    await v.set_climatisation_timer_active(id=1, action='on')
    await v.set_climatisation_timer_active(id=2, action='off')
```

--------------------------------

### Retrieve Vehicle Instrumentation Dashboard

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Fetches a Dashboard object containing all instrument readings, useful for integrations like Home Assistant. The dashboard can be made mutable if needed.

```python
from pycupra.dashboard import Dashboard

async def show_dashboard(v):
    dash = v.dashboard(mutable=True)

    for instrument in sorted(dash.instruments, key=lambda x: x.attr):
        print(f"[{instrument.component}] {instrument.full_name}: {instrument.str_state}")

    # Example output:
    # [sensor] Battery level: 78%
    # [binary_sensor] Charging cable connected: True
    # [sensor] Electric range: 245 km
    # [lock] Door lock: locked
    # [device_tracker] Position: 48.1374,11.5755
```

--------------------------------

### Access EU Data Act Portal and Download Vehicle Data

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Connects to the VW Group EUDA portal to log in, retrieve vehicle information, and download raw vehicle data files. Requires aiohttp for session management and asyncio for asynchronous operations.

```python
from pycupra import EUDAConnection
from aiohttp import ClientSession
import asyncio

async def fetch_euda_data():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        euda = EUDAConnection(
            session=session,
            brand='cupra',
            username='user@email.com',
            password='s3cret',
            fulldebug=False,
            anonymise=False,
        )
        ok = await euda.doLogin()
        if ok:
            await euda.getVehicles()
            euda.readTripStatisticsFile()   # Load cached local file if present
            updated = await euda.update()  # Download new data files from portal

            for v in euda.vehicles:
                # Access EUDA-specific properties
                if v.is_short_term_distance_supported:
                    print(f"Short-term trip distance: {v.short_term_distance} km")
                if v.is_long_term_average_speed_supported:
                    print(f"Long-term avg speed: {v.long_term_average_speed} km/h")
                if v.is_oil_level_supported:
                    print(f"Oil level: {v.oil_level}%")
                if v.is_outside_temperature_supported:
                    print(f"Outside temperature: {v.outside_temperature} °C")

asyncio.run(fetch_euda_data())
```

--------------------------------

### Vehicle.initialiseFirebase

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Registers for Firebase Cloud Messaging (FCM) push notifications for near real-time status updates.

```APIDOC
## Vehicle.initialiseFirebase

### Description
Registers for Firebase Cloud Messaging (FCM) push notifications so that charging and climatisation status changes are received in near-real-time instead of through periodic polling.

### Method
Asynchronous function call within the Vehicle object.

### Parameters
#### Request Body
- **firebaseCredentialsFileName** (str) - Required - The filename for Firebase credentials, typically including the vehicle's VIN.
- **updateCallback** (function) - Required - A callback function that receives the update type (1=full, 2=partial) and is called when a push notification is received.

### Request Example
```python
async def on_update(update_type):
    print(f"Push notification triggered update (type={update_type})")
    await v.update(updateType=update_type)

await v.initialiseFirebase(
    firebaseCredentialsFileName='./pycupra_firebase_{vin}.json',
    updateCallback=on_update,
)
```

### Response
- **status** (int) - The status of Firebase initialization: 1=activated, -1=failed, -2=not wanted, 0=not initialised.
```

--------------------------------

### Access vehicle state properties

Source: https://context7.com/wulfgarw/pycupra/llms.txt

The `Vehicle` class exposes numerous read-only properties to access vehicle state, such as battery level, charging status, range, location, and more. Use the companion `is_<name>_supported` properties to check capability before accessing a specific field.

```python
# Charging and battery
if v.is_battery_level_supported:
    print(f"Battery: {v.battery_level}%")
if v.is_charging_supported:
    print(f"Charging: {v.charging}, state: {v.charging_state}")
    print(f"Charging mode: {v.charging_mode}")
    print(f"Target SoC: {v.target_soc}%")
    print(f"Time left: {v.charging_time_left} min")
    print(f"Power: {v.charging_power} kW")
    print(f"Cable connected: {v.charging_cable_connected}")

# Range
print(f"Electric range: {v.electric_range} km")
print(f"Combustion range: {v.combustion_range} km")
if v.is_fuel_level_supported:
    print(f"Fuel level: {v.fuel_level}%")

# Location
if v.is_position_supported:
    pos = v.position
    print(f"Position: lat={pos['lat']}, lng={pos['lng']}")
    print(f"Parked since: {v.parking_time}")

# Doors and windows
print(f"Doors locked: {v.doors_locked}")
print(f"Windows closed: {v.windows_closed}")
print(f"Hood closed: {v.hood_closed}")
print(f"Trunk locked: {v.trunk_locked}")

# Climatisation
if v.is_climatisation_supported:
    print(f"Electric climatisation on: {v.electric_climatisation}")
    print(f"Target temperature: {v.climatisation_target_temperature} °C")

# Service
if v.is_distance_supported:
    print(f"Odometer: {v.distance} km")
if v.is_service_inspection_supported:
    print(f"Next inspection in: {v.service_inspection} days / {v.service_inspection_distance} km")

# Warnings
if v.is_warnings_supported:
    print(f"Active warnings: {v.warnings}")
```

--------------------------------

### EUDAConnection.doLogin

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Logs into the VW Group EUDA (EU Data Act) portal.

```APIDOC
## EUDAConnection.doLogin

### Description
Logs into the VW Group EUDA (EU Data Act) portal.

### Method
Asynchronous function call within the EUDAConnection object.

### Parameters
None

### Response
- **ok** (bool) - True if the login was successful, False otherwise.
```

--------------------------------

### Enable Push Notifications with Firebase

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Registers for Firebase Cloud Messaging (FCM) push notifications to receive real-time status updates. Requires a Firebase credentials file and defines a callback for handling updates.

```python
async def start_push_notifications(v):
    # updateCallback receives updateType: 1=full, 2=partial
    async def on_update(update_type):
        print(f"Push notification triggered update (type={update_type})")
        await v.update(updateType=update_type)

    status = await v.initialiseFirebase(
        firebaseCredentialsFileName='./pycupra_firebase_{vin}.json',
        updateCallback=on_update,
    )
    # status: 1=activated, -1=failed, -2=not wanted, 0=not initialised
    print(f"Firebase status: {status}")

    if status == 1:
        # Enter event loop to process notifications
        while True:
            await asyncio.sleep(30)
            print(f"Battery: {v.battery_level}%, Charging: {v.charging_state}")
```

--------------------------------

### Send Navigation Destination to Vehicle

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Use this function to send a navigation destination, including address and GPS coordinates, to the vehicle. Ensure the vehicle object is properly initialized.

```python
async def send_nav_destination(v):
    success = await v.send_destination(
        destination={
            "address": {
                "city": "Barcelona",
                "country": "Spain",
                "street": "Carrer de Pallars",
                "houseNumber": "193",
                "zipCode": "08005",
            },
            "poiProvider": "google",
            "geoCoordinate": {"latitude": 41.3989, "longitude": 2.1999},
            "destinationName": "CUPRA HQ Barcelona"
        }
    )
    print("Destination sent" if success else "Failed to send destination")
```

--------------------------------

### Vehicle.set_timer_schedule

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sets the schedule for one of up to three departure timers.

```APIDOC
## Vehicle.set_timer_schedule

### Description
Sets the schedule for one of up to three departure timers, including support for single or recurring schedules, off-peak charging windows, and climatisation control.

### Method
Asynchronous function call within the Vehicle object.

### Parameters
- **id** (integer) - Required - The ID of the timer to configure (1, 2, or 3).
- **schedule** (object) - Required - An object containing the timer schedule details.
  - **enabled** (boolean) - Required - Whether the timer is enabled.
  - **recurring** (boolean) - Required - Whether the schedule is recurring.
  - **time** (string) - Required - The desired time for the schedule (HH:MM).
  - **days** (string) - Optional (if recurring) - A string representing days of the week (e.g., 'yynnnnn' for Mon/Tue).
  - **date** (string) - Optional (if not recurring) - The specific date for the schedule (YYYY-MM-DD).
  - **nightRateActive** (boolean) - Optional - Whether off-peak charging is active.
  - **nightRateStart** (string) - Optional - Start time for off-peak charging (HH:MM).
  - **nightRateEnd** (string) - Optional - End time for off-peak charging (HH:MM).
  - **operationCharging** (boolean) - Optional - Whether to enable charging.
  - **operationClimatisation** (boolean) - Optional - Whether to enable climatisation.

### Request Example
```python
await v.set_timer_schedule(
    id=1,
    schedule={
        "enabled": True,
        "recurring": True,
        "time": "07:30",
        "days": "yynnnnn",
        "nightRateActive": True,
        "nightRateStart": "22:00",
        "nightRateEnd": "06:00",
        "operationCharging": True,
        "operationClimatisation": True,
    }
)
await v.set_timer_schedule(
    id=2,
    schedule={
        "enabled": True,
        "recurring": False,
        "date": "2025-12-24",
        "time": "08:00",
        "operationCharging": True,
        "operationClimatisation": False,
    }
)
```

### Related Functions
- `set_timer_active(id, action)`: Activates or deactivates a timer.
- `set_charge_limit(percentage)`: Sets the minimum SoC for departure timer charging.
```

--------------------------------

### Vehicle.set_honkandflash

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Activates the horn and/or flash lights to locate the vehicle. Requires parking position data.

```APIDOC
## Vehicle.set_honkandflash

### Description
Activates the horn and/or flash lights to locate the vehicle. Requires parking position data.

### Method
Asynchronous function call within the Vehicle object.

### Parameters
- **action** (string) - Required - 'flash', 'honk', or 'honkandflash'.

### Request Example
```python
await v.set_honkandflash('flash')
await v.set_honkandflash('honkandflash')
```

### Response
- **Success Response**: Returns `True` if the action was initiated successfully.

### Status Information
- `honkandflash_action_status`: Status of the last honk and flash action.
- `honkandflash_action_timestamp`: Timestamp of the last honk and flash action.
```

--------------------------------

### Vehicle.update

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Updates vehicle state from the cloud. `updateType=0` performs a small update (status + basic data), `updateType=1` performs a full refresh of all endpoints, and `updateType=2` performs a small update bypassing nightly reduction.

```APIDOC
## `Vehicle.update` — Incremental or full data refresh

Updates vehicle state from the cloud. `updateType=0` is a small update (status + basic data), `updateType=1` is a full refresh of all endpoints, `updateType=2` is a small update bypassing nightly reduction.

```python
async def main():
    # ... setup conn and get_vehicles() ...
    for v in conn.vehicles:
        # Full update (all endpoints)
        await v.update(updateType=1)

        # Small update (fast, only status and basic car data)
        await v.update(updateType=0)

        print(f"Last full update: {v.last_full_update}")
        print(f"Last connected: {v.last_connected}")
```
```

--------------------------------

### Connection.update_all

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Refreshes all vehicle data by calling `vehicle.update(updateType=1)` for every registered vehicle in parallel. This triggers a full data refresh across all API endpoints.

```APIDOC
## `Connection.update_all` — Refresh all vehicle data

Calls `vehicle.update(updateType=1)` for every registered vehicle in parallel using `asyncio.gather`, triggering a full data refresh across all API endpoints.

```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')
        await conn.get_vehicles()

        # ... wait some time ...
        success = await conn.update_all()
        if success:
            for v in conn.vehicles:
                print(f"{v.vin}: {v.battery_level}% battery, range {v.electric_range} km")
```
```

--------------------------------

### Locate Vehicle with Honk and Flash

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Activates the horn and/or flashes lights to help locate the vehicle. Requires parking position data. The last action status and timestamp can be checked afterwards.

```python
async def locate_vehicle(v):
    # Flash lights only
    if await v.set_honkandflash('flash'):
        print("Flashing lights")

    # Honk and flash
    if await v.set_honkandflash('honkandflash'):
        print("Honking and flashing")

    # Check the action status afterwards
    print(f"Last action: {v.honkandflash_action_status} at {v.honkandflash_action_timestamp}")
```

--------------------------------

### Vehicle read-only properties

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Accesses vehicle state through numerous `@property` fields. Each property has a corresponding `is_<name>_supported` property to check capability before access.

```APIDOC
### Vehicle read-only properties — Access vehicle state

The `Vehicle` class exposes dozens of `@property` fields to read vehicle state. Each has a companion `is_<name>_supported` property to check capability before access.

```python
# Charging and battery
if v.is_battery_level_supported:
    print(f"Battery: {v.battery_level}%")
if v.is_charging_supported:
    print(f"Charging: {v.charging}, state: {v.charging_state}")
    print(f"Charging mode: {v.charging_mode}")
    print(f"Target SoC: {v.target_soc}%")
    print(f"Time left: {v.charging_time_left} min")
    print(f"Power: {v.charging_power} kW")
    print(f"Cable connected: {v.charging_cable_connected}")

# Range
print(f"Electric range: {v.electric_range} km")
print(f"Combustion range: {v.combustion_range} km")
if v.is_fuel_level_supported:
    print(f"Fuel level: {v.fuel_level}%")

# Location
if v.is_position_supported:
    pos = v.position
    print(f"Position: lat={pos['lat']}, lng={pos['lng']}")
    print(f"Parked since: {v.parking_time}")

# Doors and windows
print(f"Doors locked: {v.doors_locked}")
print(f"Windows closed: {v.windows_closed}")
print(f"Hood closed: {v.hood_closed}")
print(f"Trunk locked: {v.trunk_locked}")

# Climatisation
if v.is_climatisation_supported:
    print(f"Electric climatisation on: {v.electric_climatisation}")
    print(f"Target temperature: {v.climatisation_target_temperature} °C")

# Service
if v.is_distance_supported:
    print(f"Odometer: {v.distance} km")
if v.is_service_inspection_supported:
    print(f"Next inspection in: {v.service_inspection} days / {v.service_inspection_distance} km")

# Warnings
if v.is_warnings_supported:
    print(f"Active warnings: {v.warnings}")
```
```

--------------------------------

### Vehicle.send_destination

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sends a navigation destination, including address and GPS coordinates, to the vehicle via the portal.

```APIDOC
## Vehicle.send_destination

### Description
Sends a navigation destination (address + GPS coordinates) to the vehicle via the portal.

### Method
Asynchronous function call within the Vehicle object.

### Parameters
#### Request Body
- **destination** (dict) - Required - A dictionary containing destination details.
  - **address** (dict) - Required - Address information.
    - **city** (str) - Required - The city of the destination.
    - **country** (str) - Required - The country of the destination.
    - **street** (str) - Required - The street of the destination.
    - **houseNumber** (str) - Required - The house number of the destination.
    - **zipCode** (str) - Required - The zip code of the destination.
  - **poiProvider** (str) - Required - The provider of the Point of Interest (e.g., "google").
  - **geoCoordinate** (dict) - Required - GPS coordinates.
    - **latitude** (float) - Required - The latitude.
    - **longitude** (float) - Required - The longitude.
  - **destinationName** (str) - Required - The name of the destination.

### Request Example
```python
await v.send_destination(
    destination={
        "address": {
            "city": "Barcelona",
            "country": "Spain",
            "street": "Carrer de Pallars",
            "houseNumber": "193",
            "zipCode": "08005",
        },
        "poiProvider": "google",
        "geoCoordinate": {"latitude": 41.3989, "longitude": 2.1999},
        "destinationName": "CUPRA HQ Barcelona"
    }
)
```

### Response
- **success** (bool) - True if the destination was sent successfully, False otherwise.
```

--------------------------------

### Vehicle.set_climatisation_timer_schedule

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Sets the schedule for a dedicated climatisation timer.

```APIDOC
## Vehicle.set_climatisation_timer_schedule

### Description
Sets the schedule for a dedicated climatisation timer (separate from departure timers, supported on select vehicles).

### Method
Asynchronous function call within the Vehicle object.

### Parameters
- **id** (integer) - Required - The ID of the climatisation timer.
- **schedule** (object) - Required - An object containing the timer schedule details.
  - **enabled** (boolean) - Required - Whether the timer is enabled.
  - **recurring** (boolean) - Required - Whether the schedule is recurring.
  - **time** (string) - Required - The desired time for the schedule (HH:MM).
  - **days** (string) - Optional (if recurring) - A string representing days of the week (e.g., 'yyyyyyn' for Mon-Sat).

### Request Example
```python
await v.set_climatisation_timer_schedule(
    id=1,
    schedule={
        "enabled": True,
        "recurring": True,
        "time": "06:45",
        "days": "yyyyyyn",
    }
)
```

### Related Functions
- `set_climatisation_timer_active(id, action)`: Toggles a climatisation timer on or off.
```

--------------------------------

### EUDAConnection.getVehicles

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Retrieves a list of vehicles enrolled in ongoing data requests from the EUDA portal.

```APIDOC
## EUDAConnection.getVehicles

### Description
Retrieves a list of vehicles enrolled in ongoing data requests from the EUDA portal.

### Method
Asynchronous function call within the EUDAConnection object.

### Parameters
None

### Response
- **vehicles** (list) - A list of vehicle objects. Each vehicle object may contain properties like:
  - **is_short_term_distance_supported** (bool)
  - **short_term_distance** (float)
  - **is_long_term_average_speed_supported** (bool)
  - **long_term_average_speed** (float)
  - **is_oil_level_supported** (bool)
  - **oil_level** (int)
  - **is_outside_temperature_supported** (bool)
  - **outside_temperature** (float)
```

--------------------------------

### Vehicle.dashboard

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Retrieves a Dashboard object containing all instrument readings, useful for integrations.

```APIDOC
## Vehicle.dashboard

### Description
Returns a `Dashboard` object containing all instrument readings as a flat list, each with `name`, `attr`, `state`, `str_state`, `component`, and `attributes` fields. Useful for Home Assistant integration.

### Method
Asynchronous function call within the Vehicle object.

### Parameters
#### Query Parameters
- **mutable** (bool) - Optional - If True, the dashboard object can be modified.

### Request Example
```python
v.dashboard(mutable=True)
```

### Response
- **Dashboard** (object) - An object containing instrument readings.
  - **instruments** (list) - A list of instrument objects, each with:
    - **name** (str) - The name of the instrument.
    - **attr** (str) - The attribute name of the instrument.
    - **state** (any) - The current state of the instrument.
    - **str_state** (str) - The string representation of the instrument's state.
    - **component** (str) - The component the instrument belongs to.
    - **attributes** (dict) - Additional attributes of the instrument.
```

--------------------------------

### Refresh all vehicle data in parallel

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Calls `vehicle.update(updateType=1)` for every registered vehicle in parallel using `asyncio.gather`, triggering a full data refresh across all API endpoints. Ensure a valid session and vehicles are loaded before calling.

```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')
        await conn.get_vehicles()

        # ... wait some time ...
        success = await conn.update_all()
        if success:
            for v in conn.vehicles:
                print(f"{v.vin}: {v.battery_level}% battery, range {v.electric_range} km")
```

--------------------------------

### Connection.terminate

Source: https://context7.com/wulfgarw/pycupra/llms.txt

Performs a clean logout by stopping Firebase push notification listeners for all vehicles and revoking all session tokens.

```APIDOC
## `Connection.terminate` — Clean logout

Stops Firebase push notification listeners for all vehicles and revokes all session tokens.

```python
async def main():
    async with ClientSession(headers={'Connection': 'keep-alive'}) as session:
        conn = Connection(session, 'cupra', 'user@email.com', 's3cret')
        await conn.doLogin(tokenFile='./token.json')
        await conn.get_vehicles()

        # ... do work ...

        await conn.terminate()   # Stops Firebase, revokes tokens, deletes token file
```
```
Tokens:
Raw