audi-app/homeassistant/INSTALL.md

Installation — Schritt für Schritt

Zwei Wege führen zum selben Ergebnis: HACS lädt den Ordner custom_components/audi_dashboard/ aus dem Repository, das Skript kopiert denselben Ordner von der Festplatte. Was danach passiert, ist identisch.

Wer von der früheren pyscript-Fassung kommt: Umstieg 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) — nur für den Weg ohne HACS
• 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.

---

Weg A — über HACS

1. HACS → Integrationen → Menü oben rechts → Benutzerdefinierte Repositories
2. Repository-URL eintragen, Kategorie Integration, hinzufügen
3. Audi Dashboard suchen und herunterladen
4. Home Assistant neu starten

Hürde, die man kennen muss: HACS spricht ausschließlich mit GitHub — github.com und api.github.com stehen fest im Code, es gibt keinen Schalter für Gitea, GitLab oder eine selbst gehostete Instanz. Liegt das Repository woanders, findet HACS es auch als benutzerdefiniertes Repository nicht, und es bleibt Weg B.

Weg B — ohne HACS, 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 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 (Weg A oder B 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.