tobias
1354ca6b06
HACS kann laut eigener Dokumentation grundsätzlich nicht mit privaten GitHub-Repositories arbeiten (hacs.xyz/docs/faq/private_repositories) - keine Ausnahme für Tokens oder verbundene Konten. Meine frühere Annahme, HACS käme damit zurecht, wenn es unter dem richtigen Konto angemeldet ist, war falsch. Da das Repository aus Lizenzgründen privat bleiben muss (Audi-Hausschrift, Typenschilder), ist install.ps1 damit nicht die Rückfallebene, sondern der einzige Installationsweg - README, INSTALL.md, ANLEITUNG.md, install.ps1 und VERSIONIERUNG.md korrigiert. Oberflächen-Updates für die iOS-App laufen jetzt ohne Xcode: @capgo/capacitor-updater eingebaut, ein Update-Abschnitt in den Einstellungen lädt ein neues Bündel und tauscht die Oberfläche aus. Kein Selbstlauf (autoUpdate: false) - nur auf Tastendruck, nie während der Benutzung. Das Bündel liegt in der Integration selbst (custom_components/audi_dashboard/frontend/app/), nicht unter /local/: so reist es bei jeder Installation automatisch mit, ohne zweiten Auslieferungsweg. Gebaut von companion-app/scripts/ota-paket.ps1 (neuer Befehl: npm run ota), gemeldet über sensor.audi_dashboard_app_version (neues Feld daten.buendel). Ein echter Bug beim Bauen gefunden: [IO.Compression.ZipFile]::CreateFrom- Directory schreibt unter Windows PowerShell 5.1 Backslashes in die Zip-Einträge - iOS hätte das Archiv falsch entpackt. Behoben, indem die Einträge von Hand mit "/" geschrieben werden. Rückfallebene: notifyAppReady() läuft erst, wenn React nachweislich gerendert hat (App.tsx). Kommt diese Meldung nicht, rollt das Plugin nach 20 Sekunden von selbst auf das vorherige Bündel zurück. Am laufenden Testcontainer verifiziert: die ausgelieferte Zip hasht exakt auf den in bundle.json hinterlegten Wert, 13 Einträge, index.html in der Wurzel, keine Backslashes, keine Beschädigung. tsc sauber, 117/117 Tests (5 davon neu für buendelPasst() - dabei eine echte Lücke gefunden: die Funktion hätte bei unbekannter eigener Version fälschlich ein Update angeboten, jetzt genauso vorsichtig wie versionVergleichen). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
153 lines
5.7 KiB
Markdown
153 lines
5.7 KiB
Markdown
# Kurzanleitung — Installation auf einer Home-Assistant-Instanz
|
||
|
||
Ausführliche Erklärungen, Umstieg von der alten Fassung und Troubleshooting
|
||
stehen in [`../INSTALL.md`](../INSTALL.md) — hier nur die Checkliste.
|
||
|
||
## Voraussetzungen
|
||
|
||
- Home Assistant 2025.1 oder neuer
|
||
- Das **Samba-Share-Add-on** in HA läuft, damit `\\<HA-IP>\config` vom PC aus
|
||
erreichbar ist
|
||
|
||
Das war's. Anders als früher braucht es weder HACS noch pyscript, kein
|
||
Zugriffstoken und keinen `pip install` auf der HA-Maschine.
|
||
|
||
---
|
||
|
||
## Der schnelle Weg: `Installieren.cmd`
|
||
|
||
**Doppelklick auf `Installieren.cmd`.** Das Skript sucht die HA-Instanz im
|
||
Netz (`\\homeassistant\config` und die üblichen Alternativen, sonst fragt es
|
||
nach dem Pfad) und kopiert einen einzigen Ordner:
|
||
|
||
```
|
||
custom_components\audi_dashboard\ -> <config>\custom_components\
|
||
```
|
||
|
||
Am Ende listet es auf, was noch von Hand zu tun ist.
|
||
|
||
Erst schauen, was passieren würde, ohne dass etwas geschrieben wird:
|
||
|
||
```powershell
|
||
.\install.ps1 -Pruefen
|
||
```
|
||
|
||
Mit festem Ziel:
|
||
|
||
```powershell
|
||
.\install.ps1 -Ziel "\\192.168.1.50\config"
|
||
```
|
||
|
||
### Ist das für meine bestehende HA-Installation gefährlich?
|
||
|
||
Nein — und das lässt sich nachprüfen statt glauben.
|
||
|
||
Die riskanteste Stelle der früheren Fassung ist weg: sie musste Blöcke in die
|
||
`configuration.yaml` eintragen, und eine kaputte `configuration.yaml` ist der
|
||
eine Weg, auf dem ein Installer Home Assistant am Starten hindern kann.
|
||
**Diese Fassung fasst die Datei überhaupt nicht mehr an** — die Integration
|
||
meldet ihr Panel selbst an, dafür braucht es kein YAML.
|
||
|
||
Was bleibt:
|
||
|
||
- Geschrieben wird **ausschließlich** in
|
||
`<config>\custom_components\audi_dashboard`. Kein anderer Pfad — nicht
|
||
`.storage\`, nicht `configuration.yaml`, nicht `automations.yaml`, nicht
|
||
`www\`, nicht `audi_dashboard\` (die Fahrzeugdaten).
|
||
- Gelöscht wird nur der eigene Ordner, und auch der nur, wenn darin eine
|
||
`manifest.json` mit `"domain": "audi_dashboard"` liegt. Ein fremder Ordner
|
||
unter demselben Namen führt zum Abbruch, nicht zum Löschen.
|
||
- Nach dem Kopieren liest das Skript die `manifest.json` im Ziel zurück und
|
||
prüft die Version. Stimmt sie nicht, bricht es mit einer Meldung ab, statt
|
||
eine halbe Installation stehen zu lassen.
|
||
- Es **startet HA nicht neu**. Bis zum manuellen Neustart ändert sich am
|
||
laufenden Betrieb nichts.
|
||
|
||
Ein zweiter Lauf auf einer laufenden Installation ist damit gefahrlos — er ist
|
||
sogar der vorgesehene Weg für Updates.
|
||
|
||
Der einzige Punkt, der einer sonst gesunden Installation gefährlich werden
|
||
kann, ist **nicht** der Installer, sondern die Datenaufbewahrung aus Schritt 3
|
||
unten: 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.
|
||
|
||
---
|
||
|
||
## Der Weg von Hand
|
||
|
||
Falls `Installieren.cmd` nicht durchläuft oder lieber nachvollziehbar:
|
||
|
||
Den Ordner `custom_components\audi_dashboard` aus dem Projekt nach
|
||
`<config>\custom_components\` kopieren. Ist dort schon eine ältere Fassung,
|
||
diese vorher komplett löschen — bleibt eine Datei liegen, die es im neuen
|
||
Stand nicht mehr gibt, lädt Home Assistant sie trotzdem mit.
|
||
|
||
---
|
||
|
||
## Danach
|
||
|
||
### 1. Home Assistant neu starten
|
||
|
||
**Einstellungen → System → Neu starten.** Beim ersten Start lädt HA die
|
||
Abhängigkeit `pypdf` nach (für die Tankbelege) — das kann eine Minute dauern.
|
||
|
||
### 2. Integration hinzufügen
|
||
|
||
**Einstellungen → Geräte & Dienste → Integration hinzufügen → Audi
|
||
Dashboard.** Es gibt nichts einzugeben.
|
||
|
||
Danach steht **Mein Audi** in der Seitenleiste.
|
||
|
||
### 3. Datenaufbewahrung — zeitkritisch
|
||
|
||
Den Block aus [`recorder_snippet.yaml`](recorder_snippet.yaml) in die
|
||
`configuration.yaml` übernehmen. Home Assistant löscht Sensor-Verläufe sonst
|
||
nach 10 Tagen; was weg ist, lässt sich auch mit „Daten importieren aus Home
|
||
Assistant" nicht mehr nachtragen. Je früher der Block drin ist, desto mehr
|
||
Vergangenheit bleibt erhalten.
|
||
|
||
Vorher den Speicher prüfen (siehe oben). Bei knappem Platz mit
|
||
`purge_keep_days: 90` anfangen — Details im Kopf der Datei.
|
||
|
||
Bewusst nicht vom Installer erledigt: das ist eine Entscheidung über den
|
||
Plattenplatz der Instanz, und viele Instanzen haben schon einen eigenen
|
||
`recorder:`-Block, den man zusammenführen muss statt zu überschreiben.
|
||
|
||
### 4. Sensoren zuordnen
|
||
|
||
In der App: **Einstellungen → Fahrzeug einrichten → Setup.**
|
||
|
||
Im Auslieferstand ist **kein** Sensor vorbelegt — das ist Absicht, siehe
|
||
`../INSTALL.md`. Zwingend ist allein der Zündungs-/ACC-Sensor
|
||
(`binary_sensor`, meist vom Teltonika FMM003): er trägt die Fahrterkennung.
|
||
|
||
Änderungen wirken sofort, ein Neustart ist dafür nicht mehr nötig.
|
||
|
||
### 5. Fahrzeugdaten eintragen
|
||
|
||
**Einstellungen → Fahrzeug einrichten.** Das Profil ist bereits da — die
|
||
Integration hat es beim ersten Start aus ihrer Vorlage angelegt. Zu ersetzen
|
||
sind die Platzhalter: VIN, Kennzeichen, Erstzulassung, HU-Termin,
|
||
Versicherung, Werkstatt, Servicebuch.
|
||
|
||
### 6. Vergangenes nachholen (optional)
|
||
|
||
**Einstellungen → Einrichten → Daten importieren aus Home Assistant** holt
|
||
Fahrten, Tankvorgänge und Spannungswerte aus dem bereits aufgezeichneten
|
||
HA-Verlauf nach.
|
||
|
||
---
|
||
|
||
## Updates
|
||
|
||
Denselben Aufruf noch einmal — `Installieren.cmd` oder `install.ps1`. Der
|
||
Ordner wird ersetzt, die Fahrzeugdaten unter `audi_dashboard\` und die eigenen
|
||
Fotos unter `www\bilder\` bleiben unangetastet. Danach HA neu starten (oder
|
||
kürzer: **Einstellungen → Geräte & Dienste → Audi Dashboard → Neu laden**).
|
||
|
||
HACS ist hier bewusst keine Alternative: es kann laut eigener Dokumentation
|
||
grundsätzlich nicht mit privaten GitHub-Repositories arbeiten, und das
|
||
Repository ist privat, weil es lizenzierte Audi-Assets enthält.
|