VCDS‑Plotter

Visualise raw CSV logs from a Volkswagen Car‑Diagnostic System (VCDS) with a single command.

vcds-plotter is a lightweight Python package that turns the raw CSV files produced by VCDS into clear, multi‑series plots.
It is intentionally simple: no GUI, no heavy dependencies – just matplotlib and the standard library.

If you’re a developer or power‑user, checkout the contributing guide – the code is small and welcoming.

---

📖 Table of Contents

Section	Description
Features	What the tool can do
Installation	How to get it running
Configuration	Where VCDS logs are expected
Usage	Quick start and advanced options
Examples	Real‑world command snippets
Troubleshooting	Common issues & fixes
Development	Build, test, lint
Contributing	How to help
License	Legal stuff

---

✨ Features

• Fast, zero‑config plotting – a single command shows the newest log or a file you pick.
• Fine‑grained metric selection – include / exclude specific measurements.
• Custom groups – plot a subset of metrics in their own figure with a title you choose.
• Unit‑based grouping – automatically split metrics by unit (e.g., km/h, %) into separate figures.
• Convenience helpers – list all available metrics or CSV files with a flag.

---

📦 Installation

# From PyPI (recommended)
pip install vcds-plotter

The console script is installed as vcds‑plot.
See the help output for all options:

vcds-plot --help

From source

If you want to tweak the code or run tests:

git clone https://github.com/yourorg/vcds-plotter.git
cd vcds-plotter

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate

# Install dev dependencies
pip install -e ".[dev]"

---

⚙️ Configuration

The package expects VCDS logs to live in a directory called logs/ relative to the current working directory.
You can change this by editing the LOGS_DIR constant in vcds_plotter/config.py or, if you prefer, set the environment variable VCDS_LOGS_DIR before running.

# vcds_plotter/config.py
LOGS_DIR = Path(os.getenv("VCDS_LOGS_DIR", "logs")).resolve()

---

🚀 Usage

1️⃣ Basic plot – newest file, grouped by unit

vcds-plot --group-by-unit

2️⃣ Select specific metrics

vcds-plot --metric Motordrehzahl,Temperatur --exclude SensorX

• --metric – comma‑separated list of measurements to include.
• --exclude – measurements to skip (useful for noisy sensors).

3️⃣ Custom groups

vcds-plot --group "Engine & temp=Motordrehzahl,Temperatur"

• --group accepts one or more NAME=METRICS pairs.
  Each group gets its own figure titled with NAME.

4️⃣ Explicit file

vcds-plot --file /path/to/log_2023-09-12.csv

5️⃣ Listing helpers

# List all CSV files in the logs directory
vcds-plot --list-files

# Show every measurement name available in a file
vcds-plot --list-metrics --file /path/to/file.csv

---

🛠️ Troubleshooting

Symptom	Likely cause	Fix
No CSV file found in logs/	The logs/ directory is missing or empty.	Create the folder and copy VCDS logs into it, or set VCDS_LOGS_DIR.
No metrics left after applying filters.	The filter lists are empty or exclude all available metrics.	Double‑check the metric names (case‑sensitive) and try without --exclude.
Plot window freezes	Very large CSV file or too many metrics.	Use --exclude to trim, or plot in groups (--group-by-unit).
Matplotlib errors	Outdated matplotlib or missing backend.	Upgrade: pip install --upgrade matplotlib.

---

🤝 Contributing

We welcome issues, pull requests, and suggestions!
Please read the CONTRIBUTING.md for details on how to set up a dev environment, run tests, and follow our coding style.

---

📄 License

MIT © Supporterino
See the LICENSE file for details.

---

Happy plotting! 🚗💨