audi-app/homeassistant/installationspaket/ANLEITUNG.md

Kurzanleitung — Installation auf einer neuen Home-Assistant-Instanz

Alle Dateien, die dafür nötig sind, liegen schon in diesem Ordner. Ausführliche Erklärungen, Troubleshooting und Hintergründe stehen in ../INSTALL.md — hier nur die Checkliste.

Voraussetzungen

• HACS installiert, darüber pyscript installiert (HACS → Integrationen → „pyscript" suchen → Download → HA neu starten)
• Das Samba-Share-Add-on in HA läuft, damit \\<HA-IP>\config vom PC aus erreichbar ist

---

Der schnelle Weg: Installieren.cmd

Doppelklick auf Installieren.cmd — das erledigt die Schritte 1–3 unten von selbst: es sucht die HA-Instanz im Netz (\\homeassistant\config und die üblichen Alternativen, sonst fragt es nach dem Pfad), kopiert pyscript\, data\ → audi_dashboard\ und www\, trägt die beiden Blöcke in die configuration.yaml ein und listet am Ende auf, was noch von Hand zu tun ist (Neustart, Token, Sensoren zuordnen).

Was es dabei nicht tut:

• Bestehende Daten überschreiben. fahrzeugprofil.json, fahrten.jsonl, tankvorgaenge.jsonl, entitaeten.json und ha_token.txt bleiben unangetastet — ein zweiter Lauf auf einer laufenden Installation ist deshalb gefahrlos.
• Die configuration.yaml blind verändern. Sie wird vorher zeitgestempelt gesichert (configuration.yaml.<Datum-Uhrzeit>.bak), und stehen dort schon eigene pyscript:- oder panel_custom:-Einträge, fasst das Skript sie gar nicht an und sagt stattdessen, was zu ergänzen ist (zwei gleiche Top-Level-Schlüssel wären ungültiges YAML — HA würde nicht mehr starten). Nach dem Schreiben liest es die Datei zurück und prüft sie; weicht auch nur eine Kleinigkeit ab, rollt es selbsttätig auf die Sicherung zurück.

Ist das für meine bestehende HA-Installation gefährlich?

Nein — und das lässt sich nachprüfen statt glauben:

• Es löscht nie etwas. Im ganzen Skript kommt kein Remove-Item vor, und kopiert wird ohne robocopy /MIR; fremde Dateien in pyscript\ und www\ bleiben liegen.
• Es fasst .storage\ nicht an — keine Integrationen, Geräte, Entitäten, Benutzer, Automatisierungen. automations.yaml, scripts.yaml, scenes.yaml und secrets.yaml werden weder gelesen noch geschrieben.
• Es startet HA nicht neu. Bis zum manuellen Neustart ändert sich am laufenden Betrieb nichts.
• Die einzige Datei außerhalb der eigenen Ordner, die es überhaupt anfasst, ist configuration.yaml — mit den drei Netzen oben.

Der einzige Punkt, der einer sonst gesunden Installation gefährlich werden kann, ist nicht der Installer, sondern die Datenaufbewahrung aus Schritt 3: ein Jahr Fahrzeugverlauf braucht grob 1–1,5 GB. Auf HA OS mit SD-Karte oder kleiner eMMC vorher unter Einstellungen → System → Speicher nachsehen; ist der Datenträger voll, startet HA nicht mehr — unabhängig von dieser App.

Erst schauen, was passieren würde, ohne etwas zu schreiben:

.\install.ps1 -Pruefen

Mit festem Ziel und Token in einem Rutsch:

.\install.ps1 -Ziel "\\192.168.1.50\config" -Token "eyJhb..."

Danach weiter bei Schritt 3 (Datenaufbewahrung — macht der Installer bewusst nicht selbst, siehe dort), 4 (Token, falls nicht übergeben), 5 und 6.

---

Der Weg von Hand

Falls Installieren.cmd nicht durchläuft oder lieber nachvollziehbar Schritt für Schritt gearbeitet werden soll:

1. Dateien kopieren

Ziel ist das config-Verzeichnis der neuen HA-Instanz, z. B. über das Samba-Share-Add-on (\\<HA-IP>\config):

Aus diesem Ordner	Nach
pyscript\	\\<HA-IP>\config\pyscript\
data\	\\<HA-IP>\config\audi_dashboard\ (umbenennen von data zu audi_dashboard)
www\	\\<HA-IP>\config\www\

In audi_dashboard\ danach fahrzeugprofil.example.json zu fahrzeugprofil.json umbenennen — die Platzhalter darin lassen sich nach dem ersten Start direkt in der App unter Einstellungen → Fahrzeug einrichten eintragen.

2. configuration.yaml ergänzen

Die beiden Blöcke aus configuration_snippet.yaml (pyscript: und panel_custom:) in die bestehende configuration.yaml übernehmen — nicht ersetzen. Falls dort schon pyscript: existiert, nur die beiden Zeilen allow_all_imports: true und hass_is_global: true ergänzen.

3. Datenaufbewahrung — je früher, desto besser

Auch recorder_snippet.yaml übernehmen. Home Assistant löscht Sensor-Verläufe standardmäßig nach 10 Tagen; der Block hebt das auf ein Jahr an.

Das ist der einzige zeitkritische Schritt der ganzen Anleitung: was der recorder einmal gelöscht hat, ist endgültig weg und lässt sich auch mit „Daten importieren aus Home Assistant" (Schritt 7) nicht mehr nachtragen. Jeder Tag ohne diesen Block ist ein Tag Vergangenheit, den es später nicht mehr gibt.

Vorher Einstellungen → System → Speicher ansehen: ein Jahr braucht grob 1–1,5 GB. Bei wenig Platz mit purge_keep_days: 90 anfangen — Begründung, gemessene Zahlen und eine exclude:-Liste zum Kürzen stehen im Kopf der Datei.

Nicht betroffen sind die Bestände der App selbst (fahrten.jsonl, tankvorgaenge.jsonl, batteriespannung.jsonl, fahrzeugprofil.json) — die werden nirgends automatisch gekürzt.

4. Long-Lived Access Token

Profil-Avatar (unten links) → „Long-lived access tokens" → Token erstellen → Wert in eine neue Datei audi_dashboard\ha_token.txt einfügen (nur der Token, keine Anführungszeichen). Wird fürs Kilometerstand-Screening gebraucht.

5. Neu starten

Einstellungen → System → Neu starten.

6. Sensoren zuordnen

Nach dem Neustart sollte „Mein Audi" in der Sidebar erscheinen. Dort: Einstellungen → Fahrzeug einrichten → Einrichten → „Setup — Sensoren zuordnen". Im Auslieferstand ist kein Sensor vorbelegt.

Zwingend für die Fahrterkennung: der Zündungs-/ACC-Sensor (binary_sensor, meist vom Teltonika FMM003). Alles Weitere ist optional — ohne zugeordneten Sensor zeigt die App „unbekannt" statt eines Werts.

Danach noch einmal neu starten: die drei trigger-gebundenen Felder (Zündung, Kilometerstand, Tankfüllstand) werden erst mit einem Neustart wirksam. Das Setup-Menü weist bei diesen Feldern selbst darauf hin.

Beim Kilometerstand nicht den vom FMM003 selbst berechneten Wert (*_total_calculated_mileage) nehmen — der beruht auf GPS-Streckenrechnung statt auf dem Tacho und verfälscht Reifenzähler, Ölwechsel-Prognose und Fahrtabschluss. Richtig ist der CAN-Wert (*_total_vehicle_mileage_read_from_can) oder der Kilometerstand der EU-Data-Act-Integration.

7. Optional: Vergangenheit nachtragen

Sobald die Sensoren zugeordnet sind, holt Einstellungen → Einrichten → „Daten importieren aus Home Assistant" nach, was Home Assistant schon vor der Installation aufgezeichnet hat: Zeitraum wählen, „Importieren", fertig. Es entstehen dieselben Fahrten, Tankvorgänge und Spannungswerte, die die Live-Erkennung erzeugt hätte.

Gefahrlos wiederholbar — überschneidet sich ein Zeitraum mit bereits erfassten Fahrten, wird er übersprungen statt doppelt angelegt. Wie weit er zurückreicht, hängt allein an Schritt 3.

8. Optional: Beleg-Parser

Nur nötig, wenn Shell-Tankbelege hochgeladen werden sollen: im Terminal & SSH-Add-on (oder docker exec) pip install pypdf ausführen.

Künftige Updates

Nicht diesen Ordner erneut kopieren — stattdessen ..\update.ps1 aus dem Hauptprojekt verwenden:

..\update.ps1 -Ziel "\\<HA-IP-Adresse>\config"

Kopiert pyscript\ und alle www\-Dateien (inkl. audi-dashboard-ios.css und badges\, die früher hier im Skript fehlten), lässt data\/ audi_dashboard\ unangetastet. pyscript lädt automatisch neu, fürs Frontend reicht ein normales Neuladen der Seite (F5).

---

Details, Screenshots-Ersatz-Erklärungen und die vollständige Troubleshooting-Tabelle: siehe ../INSTALL.md.