Metadata-Version: 2.4
Name: upxlink
Version: 0.1.0
Summary: Access the REST interface of VW up! and related cars
Project-URL: Homepage, https://github.com/hahnworks/upXlink
Project-URL: Issues, https://github.com/hahnworks/upXlink/issues
Author-email: Alexander Hahn <hahnworks@posteo.net>
License-Expression: EUPL-1.2
License-File: LICENCE
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: mibbridge>=0.1
Requires-Dist: requests
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: requests; extra == 'test'
Description-Content-Type: text/markdown

# 🚗🎛️🔧 upXlink

Re-implementation of the data exchange part of [maps + more](https://www.volkswagen.de/de/konnektivitaet-und-mobilitaetsdienste/volkswagen-apps.html#:~:text=maps%20+%20more).
The goal is to support all settings and read out all the data, just as with the original app.

>[!WARNING]
>Currently the application will not change the car’s configuration, unless the `post` command is used to send a POST request.
>While the API exposed by the car seems to be straightforward, no “safe” write access with checking for data sanity has been implemented yet.
>As always, use at your own risk when experimenting.

You can check out [this](https://www.w3.org/submissions/viwi-service-car/) rather outdated document specifying the REST interface partially.


## Screenshot

![upXlink CLI in action: Shows departure times and car and battery information](docs/screenshot.png)


## Installation

You can get upXlink from PyPI:

```bash
pip install upxlink
```


## Usage

After pairing to your car, you can use your car’s MAC address with:

```bash
upxlink 12:34:56:78:90:00
```

Connecting for the first time requires a registration.
Just confirm the PIN shown on the cars display.
Client-side calculation of the PIN is not available (yet).
The credentials will be saved in your home directory at `.upxlink_credentials`
This is only necessary for the first time.


### Command line

You can use upXlink directly from the command line using below commands.

Use `help` to get a list of commands.

Available commands are
- `battery`: Print battery data
- `info`: Print car info
- `range`: Print range info
- `chargingmanager`: Print current chargingmanager configuration
- `get <path>`: Get content from `<path>`, e.g. `get /car/info`
- `post <path> <content>`: Post `<content>` to `<path>`


## Status

### What works

- Registration (albeit without PIN calculation) works.
- Authentication works.
- Accessing the REST interface using `GET` and `POST` works.
- Readout works for
    - Battery SoC
    - Car information (VIN, region, model)
    - Range
    - ChargingManager (departure times, locations, charging times)
        - **Note**: The car reports departure times in UTC.


### What does not work yet (but is planned)

- More robust registration
    - Certificate at first registration is not checked
    - PIN calculation is not performed (we are forced to [TOFU](https://en.wikipedia.org/wiki/Trust_on_first_use))
- ChargingManager
    - Manipulation
        - **Note**: Using the `post` command, modifications can be made. As always, use at your own risk.
- MediaControl
- WebSocket functionality (subscribing to events like button presses)
- A nice documentation


## Disclaimer

This project is not associated with VWAG or its sub-brands.
All trademarks are the property of their respective owners.

This program is free software: you can redistribute it and/or modify
it under the terms of the European Union Public License (EUPL), version 1.2.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
European Union Public License for more details.
