# Audi Dashboard — „Mein Audi" für Home Assistant

Fahrtenbuch, Tankstatistik, Reifen- und Servicebuch für ein einzelnes
Fahrzeug — als eigener Sidebar-Eintrag in Home Assistant und als iOS-App, die
dieselben Daten zeigt.

Die App wertet aus, was Home Assistant ohnehin über das Fahrzeug weiß
(Zündung, Kilometerstand, Tankfüllstand, Bordspannung, GPS — etwa über einen
Teltonika FMM003 oder eine EU-Data-Act-Integration des Herstellers), und macht
daraus einen dauerhaften Bestand: erkannte Fahrten, erkannte Tankvorgänge,
Belegdaten aus hochgeladenen Tank-PDFs, ein Spannungsverlauf über Jahre.

> Privates Projekt für ein bestimmtes Fahrzeug. Es ist nicht als allgemein
> nutzbare Integration gedacht und steht in keinem Verhältnis zur AUDI AG.

---

## Installation

HACS scheidet aus, und zwar endgültig: laut eigener Dokumentation
(hacs.xyz/docs/faq/private_repositories) kann HACS **grundsätzlich nicht**
mit privaten GitHub-Repositories arbeiten — „HACS can only get publicly
available information", ohne Ausnahme für Tokens oder verbundene Konten. Und
öffentlich machen ist keine Option: das Repository enthält die
Audi-Hausschrift und die Typenschilder, die nur für diese eine private
Installation lizenziert sind.

Der Installer unten ist deshalb nicht die zweite Wahl, sondern der einzige
Weg. Er ist genauso wenig Handarbeit wie ein HACS-Update — derselbe Aufruf
installiert und aktualisiert.

Von einem Windows-Rechner aus, der das `config`-Verzeichnis der HA-Instanz
erreicht (Samba-Add-on oder gemounteter Pfad):

```
homeassistant\installationspaket\Installieren.cmd
```

Das Skript kopiert `custom_components\audi_dashboard\` in die Instanz und
fasst sonst nichts an — keine `configuration.yaml`, keine Fahrzeugdaten. Mit
`-Pruefen` zeigt es vorher, was es tun würde. Details und die
Sicherheitszusagen stehen im Kopf von
[`install.ps1`](homeassistant/installationspaket/install.ps1).

Danach ebenfalls: neu starten, Integration hinzufügen.

## Nach der Installation

**Sensoren zuordnen** — **Einstellungen → Fahrzeug einrichten → Setup** in der
App. Im Auslieferstand ist bewusst *kein* Sensor vorbelegt: welche Entity-IDs
richtig sind, hängt an der Instanz, und eine gesetzte, aber falsche ID ist
schlechter als eine leere. Zwingend ist allein der Zündungs-/ACC-Sensor — er
trägt die Fahrterkennung. Änderungen wirken sofort, ohne Neustart.

**Datenaufbewahrung verlängern** — Home Assistant löscht Sensor-Verläufe nach
10 Tagen. Das begrenzt, wie weit „Daten importieren aus Home Assistant"
zurückreichen kann, und was einmal gelöscht ist, kommt nicht wieder. Der Block
aus [`recorder_snippet.yaml`](homeassistant/recorder_snippet.yaml) hebt das
auf ein Jahr an; dort steht auch der gemessene Platzbedarf. Bewusst nicht
automatisch eingefügt: das ist eine Entscheidung über den Plattenplatz der
Instanz.

**Vergangenes nachholen** — **Einstellungen → Einrichten → Daten importieren
aus Home Assistant** leitet Fahrten, Tankvorgänge und Spannungswerte
rückwirkend aus dem bereits aufgezeichneten Verlauf ab.

## Was die Integration mitbringt

| | |
|---|---|
| Panel | Sidebar-Eintrag „Mein Audi", von der Integration selbst angemeldet |
| Entitäten | `sensor.audi_dashboard_*` — Profil, Fahrten, Tankvorgänge, Fahrzeugstatus, Batterieverlauf, Reifenzähler |
| Dienste | `audi_dashboard.*` — 18 Stück, in Entwicklerwerkzeuge → Aktionen dokumentiert |
| Daten | `/config/audi_dashboard/` — JSON und JSON Lines, dauerhaft, nie von einem Update angefasst |
| Abhängigkeit | `pypdf` (für Tankbelege), von Home Assistant automatisch nachinstalliert |

Die Nutzlast der Entitäten steckt im Attribut `daten` und ist ausdrücklich von
der Aufzeichnung ausgenommen — das Fahrtenarchiv wächst über Jahre auf
Hunderte Kilobyte und hat in der Recorder-Datenbank nichts verloren.

## Companion-App (iOS)

`companion-app/` ist dieselbe Oberfläche als eigenständige App (React +
Capacitor), die über die HA-API auf dieselben Entitäten und Dienste zugreift.
Sie trägt ihre Version fest einkompiliert und meldet selbst, wenn sie älter
ist als die installierte Integration — siehe
[`VERSIONIERUNG.md`](VERSIONIERUNG.md).

## Ordner in diesem Repository

| Ordner | Inhalt |
|---|---|
| `custom_components/audi_dashboard/` | die Integration — Backend und Panel-Dateien |
| `companion-app/` | die iOS-App |
| `design-system/` | gemeinsame UI-Bausteine (`@audi-dash/ui`) |
| `homeassistant/` | Installationspaket, Konfigurationsschnipsel, Anleitungen |
| `testumgebung/` | Wegwerf-Home-Assistant in Docker für Entwicklung und Tests |
| `tests/belegparser/` | Regressionstest des Tankbeleg-Lesers |