# 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 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.` statt `pyscript.audi_dashboard_`) — 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.