<# .SYNOPSIS Installiert "Mein Audi" (DataMetric360) in einem Rutsch auf einer neuen Home-Assistant-Instanz - die Schritte 1-3 aus ANLEITUNG.md. .BESCHREIBUNG Nimmt dem Erstaufsetzen die Handarbeit ab: 1. pyscript\ -> \pyscript\ 2. data\ -> \audi_dashboard\ (Ordner wird umbenannt) fahrzeugprofil.example.json -> fahrzeugprofil.json 3. www\ -> \www\ 4. configuration_snippet.yaml wird in \configuration.yaml eingefügt 5. ha_token.txt wird geschrieben, wenn -Token übergeben wurde SICHERHEIT GEGENÜBER DER BESTEHENDEN HA-INSTALLATION ---------------------------------------------------- Das Skript ist so gebaut, dass es eine laufende Home-Assistant-Installation (auch HA OS) nicht gefährden kann. Konkret und nachprüfbar: - Es LÖSCHT NIE etwas. Im gesamten Skript kommt kein Remove-Item vor, und kopiert wird bewusst ohne robocopy /MIR - fremde Dateien in pyscript\ und www\ bleiben liegen, es wird nur ergänzt. - Es fasst .storage\ nicht an: keine Integrationen, keine Geräte, keine Entitäten, keine Benutzer, keine Automatisierungen. automations.yaml, scripts.yaml, scenes.yaml und secrets.yaml werden nicht gelesen und nicht geschrieben. - Es startet Home Assistant nicht neu und greift nicht in den laufenden Betrieb ein. Bis zum manuellen Neustart ändert sich am Verhalten der Instanz nichts. - Die einzige Datei außerhalb der eigenen Ordner, die überhaupt verändert wird, ist configuration.yaml - und das ist der einzige Weg, auf dem dieses Skript HA am Starten hindern könnte. Deshalb dort drei Netze: eine zeitgestempelte Sicherung vor jeder Änderung, ein Abbruch ohne jede Änderung falls dort schon fremde pyscript:/panel_custom:-Blöcke stehen, und eine Rücklese-Prüfung nach dem Schreiben, die bei der kleinsten Abweichung automatisch zurückrollt. - -Pruefen zeigt den kompletten Ablauf, ohne irgendetwas zu schreiben. Im Zweifel damit anfangen. Was das Skript NICHT kann: pyscript installieren (das macht HACS), pypdf nachinstallieren (braucht eine Shell auf der HA-Maschine) und HA neu starten. Diese Schritte stehen am Ende als Restliste. Grundsatz: nichts kaputtmachen, was schon da ist. Das Skript ist darauf ausgelegt, gefahrlos mehrfach zu laufen (etwa nach einem Abbruch): - Bestandsdaten (fahrzeugprofil.json, fahrten.jsonl, tankvorgaenge.jsonl, entitaeten.json, ha_token.txt) werden NIE überschrieben. Wer eine laufende Installation neu bespielt, behält sein Fahrzeugprofil, seine Fahrten, Tankvorgänge und Sensorzuordnung. - configuration.yaml wird vor jeder Änderung nach configuration.yaml.bak kopiert. Der eingefügte Teil steht zwischen zwei Markierungszeilen und wird bei einem erneuten Lauf ersetzt statt ein zweites Mal angehängt. - Stehen `pyscript:` oder `panel_custom:` dort schon aus anderer Quelle, fasst das Skript die Datei NICHT an, sondern zeigt an, was von Hand zu ergänzen ist. Zwei gleiche Top-Level-Schlüssel wären ungültiges YAML und HA würde nicht mehr starten - das ist keine Entscheidung, die ein Installer still für jemanden treffen sollte. Nicht automatisierbar und deshalb am Ende als Restliste ausgegeben: HA-Neustart, `pip install pypdf` (braucht eine Shell auf der HA-Maschine) und das Zuordnen der Sensoren im Setup-Menü der App. .PARAMETER Ziel config-Verzeichnis der HA-Instanz, z. B. "\\homeassistant.local\config" (Samba-Add-on) oder ein lokal gemounteter Pfad. Ohne Angabe sucht das Skript die üblichen Samba-Namen selbst ab. .PARAMETER Token Long-Lived Access Token aus HA (Profil-Avatar -> "Long-lived access tokens"). Wird nur nach audi_dashboard\ha_token.txt geschrieben und für das Kilometerstand-Screening gebraucht. Ohne Angabe wird die Datei nicht angelegt und der Schritt landet in der Restliste. Eine schon vorhandene Datei bleibt in jedem Fall unangetastet. .PARAMETER Pruefen Nur anzeigen, was passieren würde - es wird nichts geschrieben. .BEISPIEL .\install.ps1 .\install.ps1 -Ziel "\\192.168.1.50\config" .\install.ps1 -Ziel "\\homeassistant.local\config" -Token "eyJhb..." .\install.ps1 -Pruefen #> param( [string]$Ziel, [string]$Token, [switch]$Pruefen ) $ErrorActionPreference = "Stop" $hier = $PSScriptRoot function Schritt($text) { Write-Host "`n$text" -ForegroundColor Cyan } function Gut($text) { Write-Host " [ok] $text" -ForegroundColor Green } function Info($text) { Write-Host " [info] $text" -ForegroundColor DarkGray } function Warnung($text) { Write-Host " [!] $text" -ForegroundColor Yellow } # Sammelt alles ein, was der Mensch am Ende noch selbst tun muss. $restliste = New-Object System.Collections.ArrayList Write-Host "" Write-Host " Mein Audi - Installation" -ForegroundColor White Write-Host " ========================" -ForegroundColor White if ($Pruefen) { Warnung "Pruefmodus - es wird nichts geschrieben." } # ---------------------------------------------------------------- Ziel finden if (-not $Ziel) { Schritt "Suche Home Assistant ..." # Die Reihenfolge ist Absicht: der kurze Name antwortet in den meisten # Heimnetzen schneller als der .local-Name über mDNS. $kandidaten = @( "\\homeassistant\config", "\\homeassistant.local\config", "\\hassio\config" ) foreach ($k in $kandidaten) { Info "probiere $k" if (Test-Path $k) { $Ziel = $k; break } } if (-not $Ziel) { Write-Host "" Warnung "Keine HA-Instanz automatisch gefunden." Write-Host " Bitte den config-Pfad angeben, z. B. \\192.168.1.50\config" Write-Host " (Samba-Share-Add-on in HA muss laufen und verbunden sein.)" Write-Host "" $Ziel = Read-Host " config-Pfad" if (-not $Ziel) { throw "Kein Ziel angegeben - Abbruch." } } } if (-not (Test-Path $Ziel)) { throw "Ziel nicht erreichbar: $Ziel - Samba-Share verbunden? Pfad korrekt?" } Gut "Ziel: $Ziel" # Ein config-Verzeichnis ohne configuration.yaml ist mit hoher Wahrscheinlichkeit # der falsche Ordner - lieber hier abbrechen als Dateien irgendwohin streuen. $configYaml = Join-Path $Ziel "configuration.yaml" if (-not (Test-Path $configYaml)) { throw "In $Ziel liegt keine configuration.yaml - ist das wirklich das config-Verzeichnis von HA?" } # pyscript wird über HACS installiert, nicht von hier - ohne die Integration # läuft das komplette Backend nicht, deshalb früh darauf hinweisen. if (-not (Test-Path (Join-Path $Ziel "custom_components\pyscript"))) { Warnung "custom_components\pyscript fehlt - pyscript ist offenbar noch nicht über HACS installiert." [void]$restliste.Add("pyscript über HACS installieren (HACS -> Integrationen -> 'pyscript' -> Download), danach dieses Skript erneut laufen lassen.") } # --------------------------------------------------------------- 1. pyscript Schritt "1/5 pyscript-Backend kopieren" if ($Pruefen) { Info "würde kopieren: $hier\pyscript\* -> $Ziel\pyscript\" } else { New-Item -ItemType Directory -Force -Path (Join-Path $Ziel "pyscript") | Out-Null # Bewusst kein robocopy /MIR: das würde fremde Skripte im selben Ordner # löschen. Hier wird nur ergänzt und überschrieben. Copy-Item (Join-Path $hier "pyscript\*") (Join-Path $Ziel "pyscript") -Recurse -Force Gut "pyscript\ kopiert" } # ------------------------------------------------------- 2. data -> audi_dashboard Schritt "2/5 Datenverzeichnis anlegen (data -> audi_dashboard)" $datenZiel = Join-Path $Ziel "audi_dashboard" # Dateien, die einer laufenden Installation gehören - nie überschreiben. $bestandsdaten = @( "fahrzeugprofil.json", "fahrten.jsonl", "tankvorgaenge.jsonl", "entitaeten.json", "ha_token.txt" ) if (-not $Pruefen) { New-Item -ItemType Directory -Force -Path $datenZiel | Out-Null } foreach ($datei in Get-ChildItem (Join-Path $hier "data") -File) { # fahrzeugprofil.example.json ist die Vorlage und heißt am Ziel anders. $zielName = $datei.Name if ($zielName -eq "fahrzeugprofil.example.json") { $zielName = "fahrzeugprofil.json" } $zielPfad = Join-Path $datenZiel $zielName if (($bestandsdaten -contains $zielName) -and (Test-Path $zielPfad)) { Info "$zielName existiert bereits - bleibt unverändert" continue } if ($Pruefen) { Info "würde schreiben: $zielPfad" } else { Copy-Item $datei.FullName $zielPfad -Force Gut "$zielName" } } # --------------------------------------------------------------- 3. Frontend Schritt "3/5 Frontend kopieren" if ($Pruefen) { Info "würde kopieren: $hier\www\* -> $Ziel\www\" } else { New-Item -ItemType Directory -Force -Path (Join-Path $Ziel "www") | Out-Null Copy-Item (Join-Path $hier "www\*") (Join-Path $Ziel "www") -Recurse -Force # Wie in update.ps1: die Versionsdatei bestimmt, ob Browser den neuen Code # ziehen. Immer frisch schreiben, sonst zeigt ein Browser, der die App # schon einmal geladen hatte, weiter den alten Stand. $version = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds() $versionsDatei = Join-Path $Ziel "www\audi-dashboard-version.json" [System.IO.File]::WriteAllText($versionsDatei, "{ ""version"": $version }", (New-Object System.Text.UTF8Encoding($false))) Gut "www\ kopiert (Version $version)" } # ---------------------------------------------------- 4. configuration.yaml Schritt "4/5 configuration.yaml ergänzen" $markeAuf = "# >>> Mein Audi (DataMetric360) - automatisch eingefügt, nicht von Hand bearbeiten" $markeZu = "# <<< Mein Audi (DataMetric360)" # Beide Dateien ausdrücklich als UTF-8 lesen: Get-Content nimmt in # PowerShell 5.1 sonst die ANSI-Codepage an und macht aus "Ergänzung" ein # "Ergänzung", das dann so in der configuration.yaml landet. $utf8OhneBom = New-Object System.Text.UTF8Encoding($false) $snippet = [System.IO.File]::ReadAllText((Join-Path $hier "configuration_snippet.yaml"), $utf8OhneBom) $inhalt = [System.IO.File]::ReadAllText($configYaml, $utf8OhneBom) if ($null -eq $inhalt) { $inhalt = "" } $block = "$markeAuf`r`n$snippet`r`n$markeZu`r`n" $schonDa = $inhalt.Contains($markeAuf) # Top-Level-Schlüssel aus fremder Quelle? Dann Finger weg (siehe Kopfkommentar). $ohneUnserenBlock = $inhalt if ($schonDa) { $ohneUnserenBlock = [regex]::Replace( $inhalt, "(?ms)" + [regex]::Escape($markeAuf) + ".*?" + [regex]::Escape($markeZu) + "\r?\n?", "" ) } $fremdePyscript = [regex]::IsMatch($ohneUnserenBlock, "(?m)^pyscript:") $fremdePanel = [regex]::IsMatch($ohneUnserenBlock, "(?m)^panel_custom:") if ($fremdePyscript -or $fremdePanel) { Warnung "configuration.yaml enthält bereits eigene Einträge - sie wird NICHT verändert." if ($fremdePyscript) { Info "gefunden: pyscript:" } if ($fremdePanel) { Info "gefunden: panel_custom:" } Write-Host "" Write-Host " Bitte von Hand zusammenführen (Inhalt aus configuration_snippet.yaml):" -ForegroundColor Yellow Write-Host " - unter pyscript: allow_all_imports: true" Write-Host " - hass_is_global: true" Write-Host " - unter panel_custom: den Listeneintrag 'audi-dashboard-panel'" [void]$restliste.Add("configuration.yaml von Hand ergänzen (siehe Hinweis oben) - zwei gleiche Top-Level-Schlüssel wären ungültiges YAML.") } elseif ($Pruefen) { if ($schonDa) { Info "würde den vorhandenen Mein-Audi-Block ersetzen" } else { Info "würde den Mein-Audi-Block anhängen" } } else { # Zeitgestempelte Sicherung statt einer festen .bak: die feste Datei wurde # bei einem zweiten Lauf von der bereits geänderten Fassung überschrieben - # ausgerechnet das Original, auf das man im Notfall zurückwill, war dann weg. $sicherung = "$configYaml.bak" $stempel = Get-Date -Format "yyyyMMdd-HHmmss" $sicherungZeit = "$configYaml.$stempel.bak" Copy-Item $configYaml $sicherungZeit -Force if (-not (Test-Path $sicherung)) { Copy-Item $configYaml $sicherung -Force } Info "Sicherung: $(Split-Path $sicherungZeit -Leaf)" if ($schonDa) { $neu = [regex]::Replace( $inhalt, "(?ms)" + [regex]::Escape($markeAuf) + ".*?" + [regex]::Escape($markeZu) + "\r?\n?", [System.Text.RegularExpressions.MatchEvaluator]{ param($m) $block } ) } else { $trenner = "" if ($inhalt.Length -gt 0 -and -not $inhalt.EndsWith("`n")) { $trenner = "`r`n" } $neu = $inhalt + $trenner + "`r`n" + $block } # Ohne BOM schreiben - HA liest die Datei als YAML, ein BOM hat da nichts # zu suchen (Out-File -Encoding utf8 setzt in PowerShell 5.1 eines). [System.IO.File]::WriteAllText($configYaml, $neu, (New-Object System.Text.UTF8Encoding($false))) # Rücklesen und prüfen, bevor wir die Datei so stehen lassen. Eine kaputte # configuration.yaml ist der einzige Weg, auf dem dieses Skript eine # laufende Home-Assistant-Installation lahmlegen könnte (HA startet dann # nicht mehr) - deshalb wird das Ergebnis hier verifiziert und im # Zweifelsfall sofort zurückgerollt, statt es dem Nutzer zu überlassen. $kontrolle = [System.IO.File]::ReadAllText($configYaml, $utf8OhneBom) $bestandNoch = [regex]::Replace( $kontrolle, "(?ms)" + [regex]::Escape($markeAuf) + ".*?" + [regex]::Escape($markeZu) + "\r?\n?", "" ) $treffer = ([regex]::Matches($kontrolle, [regex]::Escape($markeAuf))).Count $heil = $true $grund = "" if ($kontrolle.Length -lt $inhalt.Length) { $heil = $false; $grund = "die Datei ist kürzer geworden als vorher" } elseif ($treffer -ne 1) { $heil = $false; $grund = "der Mein-Audi-Block steht $treffer mal statt genau einmal darin" } elseif ($bestandNoch.Trim() -ne $ohneUnserenBlock.Trim()) { $heil = $false; $grund = "der bisherige Inhalt der Datei hat sich verändert" } if (-not $heil) { Copy-Item $sicherungZeit $configYaml -Force Warnung "configuration.yaml wurde zurückgerollt - $grund." Write-Host " Die Datei ist unverändert wie vor dem Start dieses Skripts." -ForegroundColor Yellow [void]$restliste.Add("configuration.yaml von Hand ergänzen (Inhalt aus configuration_snippet.yaml) - der automatische Weg wurde aus Sicherheitsgründen zurückgenommen.") } elseif ($schonDa) { Gut "vorhandenen Block ersetzt (geprüft)" } else { Gut "Block angehängt (geprüft)" } } # --------------------------------------------------------------- 5. Token Schritt "5/5 Zugriffstoken" $tokenDatei = Join-Path $datenZiel "ha_token.txt" if (Test-Path $tokenDatei) { Info "ha_token.txt existiert bereits - bleibt unverändert" } elseif ($Token) { if ($Pruefen) { Info "würde schreiben: $tokenDatei" } else { [System.IO.File]::WriteAllText($tokenDatei, $Token.Trim(), (New-Object System.Text.UTF8Encoding($false))) Gut "ha_token.txt geschrieben" } } else { Info "kein -Token übergeben" [void]$restliste.Add("Long-Lived Access Token anlegen (HA: Profil-Avatar unten links -> 'Long-lived access tokens' -> Token erstellen) und den Wert in $tokenDatei speichern - nur den Token, keine Anführungszeichen. Wird fürs Kilometerstand-Screening gebraucht.") } # --------------------------------------------------------------- Restliste # Bewusst nicht automatisch eingefügt: der recorder-Block ist eine Entscheidung # über den Plattenplatz der Instanz (ein Jahr Fahrzeugverlauf sind grob 1-1,5 GB, # siehe Kopf von recorder_snippet.yaml), und viele Instanzen haben bereits einen # eigenen recorder:-Block mit anderen Einstellungen. Zusammenführen ist Handarbeit. [void]$restliste.Add("ZEITKRITISCH - Datenaufbewahrung: den Block aus 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 Einstellungen -> System -> Speicher prüfen: ein Jahr Verlauf braucht grob 1-1,5 GB. Bei wenig freiem Platz (SD-Karte, kleine eMMC) mit purge_keep_days: 90 anfangen - Details im Kopf der Datei.") [void]$restliste.Add("Home Assistant neu starten: Einstellungen -> System -> Neu starten.") [void]$restliste.Add("Nur für Tankbeleg-Upload: auf der HA-Maschine 'pip install pypdf' ausführen (Terminal-&-SSH-Add-on oder docker exec).") [void]$restliste.Add("Nach dem Neustart in der App: Einstellungen -> Fahrzeug einrichten -> Setup - Sensoren zuordnen. Im Auslieferstand ist KEIN Sensor vorbelegt; zwingend für die Fahrterkennung ist der Zündungs-/ACC-Sensor (binary_sensor, meist vom Teltonika FMM003). Danach einmal neu starten - die drei trigger-gebundenen Felder (Zündung, Kilometerstand, Tankfüllstand) werden erst dann wirksam.") [void]$restliste.Add("Optional, sobald die Sensoren zugeordnet sind: Einstellungen -> Einrichten -> 'Daten importieren aus Home Assistant' holt Fahrten, Tankvorgänge und Spannungswerte aus dem bereits aufgezeichneten HA-Verlauf nach.") Write-Host "" if ($Pruefen) { Write-Host " Pruefmodus beendet - es wurde nichts geschrieben." -ForegroundColor Yellow } else { Write-Host " Dateien sind kopiert." -ForegroundColor Green } Write-Host "" Write-Host " Das fehlt noch:" -ForegroundColor White $nr = 1 foreach ($punkt in $restliste) { Write-Host " $nr. $punkt" $nr++ } Write-Host "" Write-Host " Danach erscheint 'Mein Audi' in der Seitenleiste." -ForegroundColor White Write-Host " Spätere Updates: update.ps1 statt install.ps1 - das lässt audi_dashboard\ in Ruhe." Write-Host ""