audi-app/homeassistant/INSTALL.md

# Installation — Schritt für Schritt

HACS scheidet für dieses Repository aus — nicht als Vorbehalt, sondern nach
eigener Dokumentation von HACS: „Private GitHub repositories can not be used
with HACS at all" (hacs.xyz/docs/faq/private_repositories), ohne Ausnahme für
Tokens oder verbundene Konten. Das Repository ist privat, weil es die
Audi-Hausschrift und die Typenschilder enthält, die nur für diese eine
private Installation lizenziert sind — öffentlich machen ist deshalb keine
Option.

Es gibt also nur einen Weg: das Skript unten kopiert
`custom_components/audi_dashboard/` von der Festplatte in die Instanz. Das
ist keine Verlegenheitslösung — es prüft dieselben Dinge, die HACS auch
prüfen würde, und derselbe Aufruf installiert und aktualisiert.

Wer von der früheren pyscript-Fassung kommt: [Umstieg](#umstieg-von-der-pyscript-fassung)
weiter unten. Die Fahrzeugdaten bleiben dabei, wo sie sind.

---

## Voraussetzungen

- Home Assistant 2025.1 oder neuer
- Zugriff auf das `config`-Verzeichnis (Samba-Add-on, SSH oder ein
  gemounteter Pfad)
- Mindestens eine Datenquelle, die den Zündungs-/ACC-Status des Fahrzeugs
  als `binary_sensor` meldet. Ohne sie läuft die App, erkennt aber keine
  Fahrten.

Nicht mehr nötig, anders als bei der pyscript-Fassung: pyscript selbst, ein
langlebiges Zugriffstoken, ein `pip install` im Container und Einträge in der
`configuration.yaml`. Details dazu im Kopf von
[`__init__.py`](../custom_components/audi_dashboard/__init__.py).

---

## Installation per Skript

Vom Windows-Rechner aus, der das `config`-Verzeichnis erreicht:

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

Das Skript sucht die HA-Instanz selbst (`\\homeassistant\config` und die
üblichen Varianten) und fragt nach, wenn es sie nicht findet. Es kopiert
`custom_components\audi_dashboard\` dorthin — und sonst nichts.

Zum Vorabschauen, ohne dass etwas geschrieben wird:

```
powershell -ExecutionPolicy Bypass -File homeassistant\installationspaket\install.ps1 -Pruefen
```

Was das Skript garantiert (und warum), steht in seinem eigenen Kopfkommentar.
Die kurze Fassung: es schreibt ausschließlich in seinen eigenen Ordner, fasst
`configuration.yaml` und `.storage\` nicht an, löscht nur den eigenen Ordner
und auch den nur, wenn dessen `manifest.json` ihn als solchen ausweist.

Danach Home Assistant neu starten.

---

## Nach dem Neustart

### 1. Integration hinzufügen

**Einstellungen → Geräte & Dienste → Integration hinzufügen → Audi
Dashboard.** Es gibt nichts einzugeben — ein Bestätigungsschritt, mehr nicht.

Beim ersten Laden installiert Home Assistant die Abhängigkeit `pypdf` nach
(für die Tankbelege); das kann eine Minute dauern.

Danach steht **Mein Audi** in der Seitenleiste, und es entstehen zwölf
Entitäten `sensor.audi_dashboard_*` sowie 18 Dienste `audi_dashboard.*`.

### 2. Sensoren zuordnen

In der App: **Einstellungen → Fahrzeug einrichten → Setup.**

Im Auslieferstand ist **kein** Sensor vorbelegt. Das ist Absicht: welche
Entity-IDs richtig sind, hängt an der Instanz und ihren Integrationen, und
eine gesetzte, aber falsche ID ist schlechter als eine leere — die App zeigt
dann „unbekannt" statt eines falschen Werts.

| Rolle | Braucht es für |
|---|---|
| **Zündung/ACC** (Pflicht) | Fahrterkennung, Anzeige „fährt/steht" |
| Kilometerstand | Fahrtabschluss, Reifenzähler, Ölwechsel-Prognose |
| Tankfüllstand | automatische Tankerkennung |
| 12V-Spannung | Batterieverlauf |
| GPS Breiten-/Längengrad | Standort-Kachel |
| Türen, Fenster, Heckklappe, Haube | „Sicher abgestellt" |
| Reichweite, Service-Fälligkeiten | Anzeige in der Übersicht |

Beim FMM003 **nicht** den selbst berechneten Gesamtkilometerstand
(`*_total_calculated_mileage`) zuordnen: der beruht auf GPS-Streckenrechnung
statt auf dem Tacho und verfälscht damit alle drei Auswertungen, die daran
hängen. Der vom CAN gelesene Wert ist der richtige.

Änderungen wirken sofort. Der frühere Hinweis „wirkt erst nach einem
Neustart" bei Zündung, Kilometerstand und Tankfüllstand ist entfallen — die
Integration meldet ihre Beobachter bei jedem Speichern neu an.

### 3. Datenaufbewahrung verlängern — zeitkritisch

Home Assistant löscht Sensor-Verläufe nach **10 Tagen**. Das ist die Grenze,
bis zu der „Daten importieren aus Home Assistant" zurückreichen kann; was
gelöscht ist, kommt nicht wieder. Je früher der Block aus
[`recorder_snippet.yaml`](recorder_snippet.yaml) in der `configuration.yaml`
steht, desto mehr Vergangenheit bleibt erhalten.

Vorher **Einstellungen → System → Speicher** prüfen: ein Jahr Verlauf braucht
grob 1–1,5 GB. Bei knappem Platz mit `purge_keep_days: 90` anfangen.

Bewusst nicht automatisch eingetragen: das ist eine Entscheidung über den
Plattenplatz der Instanz, und viele Instanzen haben bereits einen eigenen
`recorder:`-Block, den man zusammenführen muss statt zu überschreiben.

### 4. Fahrzeugdaten eintragen

**Einstellungen → Fahrzeug einrichten.** Das Profil ist bereits angelegt —
die Integration hat es beim ersten Start aus ihrer Vorlage erzeugt. Zu
ersetzen sind die Platzhalter: VIN, Kennzeichen, Erstzulassung, HU-Termin,
Versicherung, Werkstatt, Servicebuch.

### 5. Vergangenes nachholen (optional)

**Einstellungen → Einrichten → Daten importieren aus Home Assistant.** Der
Import liest denselben Verlauf, den die Live-Erkennung sonst in Echtzeit
sieht, und leitet daraus rückwirkend Fahrten, Tankvorgänge und
Spannungswerte ab. Mehrfach ausführbar — überschneidende Zeiträume erzeugen
keine Dubletten.

---

## Prüfen, ob alles geladen hat

**Entwicklerwerkzeuge → Zustände**, Filter `audi_dashboard`. Erwartet werden
zwölf Entitäten. Zwei sagen auf einen Blick, ob es läuft:

- `sensor.audi_dashboard_app_version` — steht auf der installierten Version
- `sensor.audi_dashboard_fahrzeugstatus` — Attribut `daten` enthält die live
  gelesenen Fahrzeugwerte

Im Protokoll (**Einstellungen → System → Protokolle**) steht beim Start eine
Zeile `Audi Dashboard <Version> eingerichtet`.

---

## Umstieg von der pyscript-Fassung

Die Daten wandern nicht: Ordnername (`/config/audi_dashboard/`) und
Dateiformate sind unverändert. Die Integration liest den bestehenden Bestand
einfach weiter — es gibt keine Migration und damit auch keinen Weg, dabei
etwas zu verlieren.

1. Integration installieren (siehe oben)
2. Aus der `configuration.yaml` entfernen: den `pyscript:`-Block und den
   `panel_custom:`-Eintrag `audi-dashboard-panel`. Bleiben sie stehen, gibt
   es den Sidebar-Eintrag zweimal, und beide Backends schreiben in dieselben
   Dateien.
3. Aus `/config/pyscript/` entfernen: `backup.py`, `batterieverlauf.py`,
   `belegverarbeitung.py`, `bilderverwaltung.py`, `fahrtabschluss.py`,
   `fahrterkennung.py`, `frontend_api.py`, `historienimport.py`,
   `reifenzaehler.py`, `tankerkennung.py`, `updateverwaltung.py` und den
   Ordner `modules/`. Andere pyscript-Skripte bleiben unberührt; wird
   pyscript sonst nicht gebraucht, kann es über HACS ganz entfernt werden.
4. Aus `/config/www/` entfernen: `audi-dashboard-app.js`,
   `audi-dashboard-panel.js`, `audi-dashboard.css`, `audi-dashboard-ios.css`,
   `audi-dashboard-version.json` und den Ordner `badges/`. Die Integration
   liefert diese Dateien selbst aus. **`www/bilder/` bleibt** — das sind die
   eigenen Fahrzeugfotos.
5. `/config/audi_dashboard/ha_token.txt` kann weg: der Verlauf wird nicht mehr
   über die REST-API gelesen.
6. Home Assistant neu starten, Integration hinzufügen.

Die Sensor-Zuordnung aus `entitaeten.json` wird unverändert übernommen.

**Die Companion-App muss neu gebaut und aufgespielt werden.** Sie spricht
Entitäten und Dienste unter neuen Namen an (`sensor.audi_dashboard_*` statt
`pyscript.audi_dashboard_*`, `audi_dashboard.<dienst>` statt
`pyscript.audi_dashboard_<dienst>`) — eine App vom alten Stand findet nach
dem Umstieg nichts mehr. Das Panel ist davon nicht betroffen: es wird von der
Integration mitgeliefert und ist damit automatisch auf demselben Stand.

---

## Troubleshooting

**„Mein Audi" fehlt in der Seitenleiste.** Ist die Integration unter
Einstellungen → Geräte & Dienste wirklich hinzugefügt? Das Panel entsteht
erst dabei, nicht schon beim Kopieren der Dateien.

**Das Panel bleibt auf „Lädt …".** Die App fragt so lange nach, bis das
Backend Daten liefert — ein Abbruch ist nicht vorgesehen. Bleibt es dauerhaft
stehen, im Protokoll nach `audi_dashboard` suchen.

**Alle Kacheln zeigen „unbekannt".** Kein Sensor zugeordnet (siehe Schritt 2)
oder die zugeordneten Entitäten existieren nicht mehr. Das Setup-Fenster
zeigt neben jedem Feld, ob der gewählte Sensor gerade einen brauchbaren Wert
liefert.

**Fahrten werden nicht erkannt.** Ohne Zündungs-/ACC-Sensor gibt es keine
Fahrterkennung — das ist das eine Pflichtfeld. Prüfen lässt sich das direkt:
den Zustand der zugeordneten Entität in Entwicklerwerkzeuge → Zustände
beobachten, während das Fahrzeug an- und ausgeht.

**Fahrten bleiben „offen".** „Offen" heißt: die Strecke fehlt noch, nicht
„unterwegs". Der Kilometerstand kommt laut Datenquelle teils erst mit der
nächsten Fahrt; das Screening trägt ihn dann nach. Bleibt es dauerhaft offen,
fehlt der Kilometerstand-Sensor oder der recorder reicht nicht weit genug
zurück.

**Belege lassen sich nicht lesen.** `pypdf` fehlt — normalerweise
installiert Home Assistant es beim ersten Laden der Integration selbst. Im
Protokoll nach `pypdf` suchen.