# 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 für die **Erstinstallation** — die Integration muss laufen, bevor sie
sich selbst aktualisieren kann.

Für **Updates danach** gibt es seit 2026-08-24 einen zweiten, bevorzugten
Weg: die Integration lädt ihre neueste Fassung direkt von Gitea und ersetzt
sich selbst (Einstellungen → Geräte & Dienste → Audi Dashboard →
Konfigurieren, dort ein Gitea-Zugriffstoken eintragen; danach in der App
unter Einstellungen → Integration-Update). Grund: Windows Smart App Control
blockiert die Ausführung von `install.ps1` zuverlässig und lässt sich —
anders als der SmartScreen davor — nicht per „trotzdem ausführen" umgehen.
Der Installer unten bleibt der Weg für die Erstinstallation und für den
seltenen Fall, dass das Selbst-Update selbst nicht mehr erreichbar ist.

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 |