audi-app/ha_install.md

DataMetric360 als native Home-Assistant-Integration

Stand: 2026-08-13. Vorhaben: Das HA-Backend von „pyscript-Skripte plus Dateien kopieren" auf eine eigene Integration mit Konfigurationsdialog umstellen — Einrichtung vollständig über die Oberfläche, kein YAML, Updates als Knopfdruck in HAs eigener Update-Liste.

Alle unten genannten Schnittstellen sind an der laufenden Instanz geprüft (Home Assistant 2026.8.1 im Container audi_ha_test), nicht aus der Dokumentation abgeschrieben. Die geprüften Signaturen stehen jeweils dabei.

Verwandte Dokumente: homeassistant/install.sh (der heutige, automatisierte Weg — siehe §1a), homeassistant/INSTALL.md (ausführliche Handanleitung), REVIEW_main_2026-08-13.md (die Fehler, die hier konstruktionsbedingt verschwinden). Im Branch umsetzung-datametric360 liegt zusätzlich UMSETZUNGSPLAN.md mit dem Phasenplan der Companion-App.

---

1. Was heute nötig ist — und was davon bleibt

Heute	Nach der Umstellung
HACS installieren, darüber pyscript	entfällt
drei Ordner nach /config/ kopieren (pyscript/, data/, www/)	einmalig ein Ordner nach custom_components/
zwei Blöcke in configuration.yaml einfügen	entfällt vollständig
Entity-IDs zuordnen	bleibt, aber als HA-Konfigurationsdialog statt als selbstgebautes Menü
langlebiges Token in audi_dashboard/ha_token.txt ablegen	entfällt ersatzlos
pip install pypdf von Hand	entfällt (manifest.json → requirements)
Neustart	einmalig, wie bei jeder Integration
Updates über update.ps1 per Samba	Knopfdruck in Einstellungen → System → Updates

1a. Was heute schon geht: install.sh

Solange die Integration nicht steht, erledigt homeassistant/install.sh die linke Spalte der Tabelle oben in einem Aufruf. Am einfachsten direkt auf der Instanz, im Add-on Terminal & SSH:

bash <(curl -fsSL https://gitea.nothaft.cloud/paul/audi-app/raw/branch/main/homeassistant/install.sh)

Bei privatem Repository braucht es Zugangsdaten — welche Wege es dafür gibt und warum die Wahl Folgen hat, steht in §1b. Von einem Rechner aus alternativ --ziel /Volumes/config --von ~/Development/audi-app. --hilfe zeigt alle Optionen.

Was es abnimmt: pyscript installieren (neueste Version von GitHub), pyscript/ und www/ einspielen, den Belegleser mitliefern (er liegt in data/, ist aber Code), fehlende Datenbestände aus der Vorlage anlegen, den Abschnitt in die configuration.yaml eintragen und UPDATE_REPO_URL setzen — damit funktioniert „Update suchen" in der App, und weitere Updates sind ein Knopfdruck statt eines Kopiervorgangs über Samba.

Drei Eigenschaften, auf die es dabei ankommt:

• Mehrfach ausführbar. Der Abschnitt in der configuration.yaml steht zwischen Markern und wird beim zweiten Lauf ersetzt statt angehängt. Stehen pyscript: oder panel_custom: bereits außerhalb dieses Abschnitts, weist das Skript darauf hin, statt einen doppelten Schlüssel zu erzeugen.
• Vorhandene Daten bleiben unangetastet. Fahrzeugprofil, Fahrten, Tankvorgänge und ein bereits hinterlegtes Token werden nie überschrieben, nur Fehlendes wird angelegt.
• Die configuration.yaml wird vor jeder Änderung mit Zeitstempel gesichert.

Geprüft gegen eine frische Home-Assistant-Instanz im Container: HA startet ohne Konfigurationsfehler, alle neun pyscript-Entitäten werden veröffentlicht, das Panel ist als „Mein Audi" mit mdi:car-sports unter /audi-dashboard-panel registriert und rendert mit fünf Tabs. Ein zweiter Durchlauf ließ Profil und Token unverändert und den Konfigurationsabschnitt genau einmal stehen.

Was danach von Hand bleibt — und genau das löst die Integration auf:

Bleibt heute	Warum	Nach der Umstellung
Home Assistant neu starten	configuration.yaml hat sich geändert	einmalig beim Hinzufügen der Integration
Zugriffstoken hinterlegen	der Fahrtabschluss liest den Verlauf über die REST-API	entfällt (Recorder direkt, §4)
Sensoren zuordnen	—	bleibt, aber als HA-Konfigurationsdialog (§3)
Fahrzeugdaten eintragen	Profilinhalte, keine Installation	bleibt

Das Skript wird durch die Integration also nicht überflüssig, sondern schrumpft: Übrig bliebe das einmalige Kopieren eines Ordners nach custom_components/. Alles andere — YAML, pyscript, Token, Datenordner — fällt weg.

1b. Zugang zum privaten Repository

Werkzeuge sind da. Im offiziellen Home-Assistant-Container liegen git (2.54), curl, unzip und ssh bereits vor — an der laufenden Instanz nachgesehen. Es muss also nichts nachinstalliert werden.

Der Haken, der die Wahl bestimmt

Die Selbstaktualisierung (updateverwaltung.py) ruft git clone aus dem Home-Assistant-Prozess auf und benutzt dafür ausschließlich einstellungen.UPDATE_REPO_URL. Die Funktion _git() setzt keine Umgebung — es gibt also weder einen Ort für einen SSH-Schlüssel noch für einen Anmeldehelfer. Daraus folgt zweierlei:

• Ein vorher im Terminal ausgeführtes git-Login hilft der Aktualisierung nicht. Unter Home Assistant OS läuft das Add-on Terminal & SSH in einem eigenen Container; eine dort angelegte ~/.git-credentials sieht Home Assistant Core nie, geteilt ist nur /config. Bei einer Container-Installation läge sie zwar im selben Container, verschwände aber beim nächsten HA-Update, weil der Container dabei neu erstellt wird. Für die Installation selbst genügt ein solcher Anmeldehelfer dagegen — install.sh klont ja in derselben Sitzung, in der du ihn eingerichtet hast.
• Was die Aktualisierung braucht, muss in der URL stehen — und die landet im Klartext in pyscript/modules/einstellungen.py, also in /config und damit in jeder Sicherung.

Die Optionen

Weg	Aufruf	Bewertung
Token in der URL (empfohlen)	--repo https://<nutzer>:<token>@gitea…/audi-app.git	Einzeln widerrufbar, ohne das Kontopasswort zu ändern; in Gitea auf Lesezugriff beschränkbar. Liegt trotzdem im Klartext in /config.
Passwort in der URL	--repo https://<nutzer>:<passwort>@gitea…/audi-app.git	Funktioniert mit Gitea genauso — aber es ist das Kontopasswort, im Klartext in /config und in jeder Sicherung. Bei aktivierter Zwei-Faktor-Anmeldung verweigert Gitea es ohnehin.
Ohne hinterlegte Zugangsdaten	--update-repo aus	Es wird nichts gespeichert. Aktualisiert wird dann weiterhin über install.sh — ein Aufruf statt eines Knopfdrucks.
Anmeldung vorher im Terminal	git config --global credential.helper store und einmal von Hand klonen, dann install.sh ohne Zugangsdaten	Reicht für die Installation, nicht für die Selbstaktualisierung (siehe oben). Sinnvoll in Kombination mit --update-repo aus.
Repository öffentlich lesbar oder Spiegel	—	Der einzige Weg ganz ohne Zugangsdaten auf der Platte. Kollidiert mit der Lizenzlage: die Audi-Schrift und die Typenschilder dürfen das Repository nicht verlassen.

Installations- und Updatequelle sind bewusst getrennt: --repo bestimmt, woher installiert wird, --update-repo allein, was für später hinterlegt wird. So lässt sich mit vollen Zugangsdaten installieren und trotzdem nichts davon ablegen.

Enthält die hinterlegte URL Zugangsdaten, weist das Skript beim Lauf darauf hin und maskiert sie in seiner Ausgabe.

Auch das Skript selbst liegt hinter der Anmeldung

install.sh wird aus demselben privaten Repository geladen, curl braucht also ebenfalls Zugang:

# mit Token
curl -fsSL -H "Authorization: token <TOKEN>" \
  https://gitea.nothaft.cloud/paul/audi-app/raw/branch/main/homeassistant/install.sh -o install.sh

# oder mit Nutzer und Passwort
curl -fsSL -u '<nutzer>:<passwort>' \
  https://gitea.nothaft.cloud/paul/audi-app/raw/branch/main/homeassistant/install.sh -o install.sh

bash install.sh --repo https://<nutzer>:<token>@gitea.nothaft.cloud/paul/audi-app.git

Nach der Umstellung auf die Integration

Das Thema verkleinert sich, verschwindet aber nicht: Die UpdateEntity (§5) holt sich die neueste Version über die Gitea-Schnittstelle und braucht dafür ebenfalls einen Zugang. Der Unterschied ist, dass eine Integration ihn selbst verwalten kann — im Konfigurationsdialog abgefragt und über Home Assistants eigene Ablage gespeichert, statt im Klartext in einer Python-Datei. Ein Token ist dann klar die richtige Wahl, weil der Dialog es jederzeit ersetzen kann.

2. Die Bausteine, die HA dafür mitbringt

Alle in 2026.8.1 vorhanden und geprüft:

Baustein	Ersetzt
EntitySelector mit domain, device_class, multiple, reorder, exclude_entities	das gesamte Setup-Menü (entitaeten.py + ~800 Zeilen JS)
panel_custom.async_register_panel(...)	den panel_custom-Block in configuration.yaml
hass.http.async_register_static_paths([StaticPathConfig(url_path, path, cache_headers)])	Kopieren nach /config/www/ samt Cache-Busting-Stub
ConfigEntry.add_update_listener(...)	den „wirkt erst nach Neustart"-Hinweis bei den drei triggergebundenen Feldern
async_track_state_change_event / async_track_time_interval / async_track_time_change	@state_trigger / @time_trigger("period") / @time_trigger("cron")
recorder.history.get_significant_states(...)	den HTTP-Aufruf auf /api/history/period samt Token-Datei
hass.async_add_executor_job(...)	task.executor(io.open, ...)
Store (homeassistant.helpers.storage)	handgeschriebenes JSON-I/O (optional, siehe §6)
HomeAssistantView / websocket_api.async_register_command	die 16-KB-Attributgrenze für Fahrten und Tankvorgänge
UpdateEntity (INSTALL, PROGRESS, BACKUP, RELEASE_NOTES)	updateverwaltung.py als sichtbare Update-Entität

Der wichtigste Einzelfund: EntitySelector kann exclude_entities. Die Duplikat-Prüfung wäre damit keine wegklickbare Warnung mehr, sondern schlicht nicht anwählbar.

3. Aufbau

custom_components/datametric360/
├── manifest.json      Abhängigkeiten, "config_flow": true, Version
├── const.py           Rollen-Tabelle (heute FELDER in entitaeten.py)
├── config_flow.py     Ersteinrichtung + Optionen (die 17 Sensor-Rollen)
├── __init__.py        Dienste, Horcher, Zeitgeber, Panel, statische Dateien
├── update.py          UpdateEntity gegen das eigene Gitea
├── api.py             HomeAssistantView für die Companion-App (später)
└── www/               audi-dashboard-app.js, .css, badges/ — mitgeliefert

Konfigurationsdialog

Statt einer eigenen Katalogverwaltung reicht ein Schema. Skizze für zwei der 17 Rollen:

vol.Schema({
    vol.Required("zuendung_sensor"): EntitySelector(
        EntitySelectorConfig(domain=["binary_sensor"])
    ),
    vol.Optional("tuer_sensoren", default=[]): EntitySelector(
        EntitySelectorConfig(domain=["binary_sensor"], device_class=["door"],
                             multiple=True, reorder=True)
    ),
})

Suche, Übersetzung, Gerätezuordnung und Mehrfachauswahl kommen von HA. Die vier Türpositionen werden zu einer sortierbaren Mehrfachauswahl — die Reihenfolge ersetzt die heutigen festen Positionsfelder.

Panel und Dateien

await hass.http.async_register_static_paths([
    StaticPathConfig("/datametric360", hass.config.path("custom_components/datametric360/www"),
                     cache_headers=False),
])
panel_custom.async_register_panel(
    hass, frontend_url_path="datametric360", webcomponent_name="audi-dashboard-panel",
    sidebar_title="Mein Audi", sidebar_icon="mdi:car-sports",
    module_url=f"/datametric360/audi-dashboard-app.js?v={VERSION}",
)

Die Versionsnummer in der URL macht den Lade-Stub audi-dashboard-panel.js und audi-dashboard-version.json überflüssig — das Cache-Problem löst sich, weil die Integration ihre eigene Version kennt.

Das Frontend selbst bleibt unangetastet. Alle 3.873 Zeilen audi-dashboard-app.js laufen weiter; nur das Setup-Menü darin wird überflüssig.

4. Übersetzung der pyscript-Eigenheiten

Mechanisch, kein Neuentwurf. Die Fachlogik — Fahrterkennung, Tankerkennung, Beleg-Parser, Reifenzähler, Prognose — geht nahezu unverändert mit.

pyscript	Integration
@service def audi_dashboard_x()	hass.services.async_register(DOMAIN, "x", handler, schema)
@state_trigger(f"{SENSOR}")	async_track_state_change_event(hass, [sensor], handler)
@time_trigger("period(now, 20 seconds)")	async_track_time_interval(hass, handler, timedelta(seconds=20))
@time_trigger("cron(0 4 * * *)")	async_track_time_change(hass, handler, hour=4, minute=0, second=0)
task.unique() + task.sleep()	asyncio.Task merken und bei Bedarf cancel()
task.executor(io.open, …)	hass.async_add_executor_job(...)
state.set("pyscript.x", …)	eigene Entität oder HomeAssistantView (siehe §6)
subprocess.run(shell_beleg_parser.py)	pypdf direkt importieren, in einem Executor-Job
urllib.request auf /api/history/period	recorder.history.get_significant_states(...)

Die letzte Zeile ist die wichtigste: Sie beseitigt zwei Befunde auf einmal — den blockierenden Aufruf, den HA seit 2026.8 abbricht (siehe REVIEW_main_2026-08-13.md, und derselbe Fehler wurde im Branch umsetzung-datametric360 bereits behoben), und die Token-Datei im Klartext.

5. Installation und Updates

Hier liegt der eigentliche Knackpunkt, deshalb ausführlich.

HACS scheidet aus

HACS spricht ausschließlich mit GitHub. Anfragen, auch GitLab, Gitea oder Codeberg zuzulassen, gibt es seit Jahren; umgesetzt sind sie nicht. Das Repository liegt auf gitea.nothaft.cloud — HACS ist damit kein Weg, außer man spiegelt nach GitHub.

„App" ist der falsche Behälter

App-Repositories (früher Add-ons) akzeptieren beliebige Git-URLs, auch selbst gehostete; nötig ist nur eine repository.yaml im Wurzelverzeichnis. Das ist die einzige Stelle, an der Gitea nativ mitspielen würde.

Inhaltlich passt es trotzdem nicht: Apps sind Docker-Container neben Home Assistant. Eine Integration muss im HA-Prozess laufen, um Entitäten anzulegen, Dienste zu registrieren und ein Panel einzuhängen. Eine App kann das nicht.

(Es gäbe den Trick, eine winzige App zu bauen, die nichts weiter tut, als die Integration nach custom_components/ zu schreiben — dann käme auch die Erstinstallation aus dem eigenen Gitea. Ein Docker-Container für einen einmaligen Kopiervorgang ist das aus meiner Sicht nicht wert; der Vollständigkeit halber notiert.)

Der native Weg: eigene UpdateEntity

UpdateEntity lässt die Integration ihre Updates selbst melden — sichtbar in Einstellungen → System → Updates, derselben Liste wie HA-Kern und Apps. Geprüfte Möglichkeiten:

UpdateEntityFeature: INSTALL, SPECIFIC_VERSION, PROGRESS, BACKUP, RELEASE_NOTES
async_install(version: str | None, backup: bool, **kwargs) -> None

BACKUP gibt es genau für das, was updateverwaltung.py heute von Hand macht: vor dem Einspielen den alten Code sichern.

Die Logik ist bereits vorhanden. updateverwaltung.py klont flach, vergleicht Versionen, sichert nach code_backups/ und ersetzt die Dateien. Das wandert nahezu unverändert in async_install(). Neu sind nur zwei Eigenschaften:

@property
def installed_version(self) -> str: return VERSION          # aus manifest.json
@property
def latest_version(self) -> str | None: return self._neueste  # aus Gitea

Für latest_version empfiehlt sich statt der heutigen Zeitstempel-Zahl aus audi-dashboard-version.json ein Git-Tag. Gitea bietet eine GitHub-kompatible Schnittstelle:

GET https://gitea.nothaft.cloud/api/v1/repos/paul/audi-app/releases/latest

Ein einzelner HTTP-Aufruf, kein Klonen. In HA steht dann „1.4.0 → 1.5.0" statt einer nichtssagenden Zahl, und die Release-Beschreibung lässt sich über release_notes direkt anzeigen.

Was bleibt

Die Erstinstallation bleibt ein einmaliges Kopieren des Ordners nach custom_components/. Für Integrationen aus Nicht-GitHub-Quellen gibt es keinen nativen Installationsweg. Jedes weitere Update ist danach ein Knopfdruck.

Das lässt sich genauso automatisieren wie heute: install.sh (§1a) schrumpft dann auf genau diesen einen Kopiervorgang zusammen — kein pyscript, kein YAML, kein Token, keine Datenordner. Wer den Aufruf ohnehin schon einmal benutzt hat, merkt vom Wechsel bei der Installation also kaum etwas; der Unterschied liegt danach, in der Einrichtung.

6. Datenhaltung — bewusst zu entscheiden

Zwei Möglichkeiten, beide vertretbar:

• Store (.storage/datametric360): atomar, versioniert, mit Migrationspfad. Nachteil: für Menschen nicht mehr lesbar, und die heutige Sicherung über backup.py müsste neu gedacht werden.
• JSON-Dateien behalten unter /config/audi_dashboard/, gelesen über Executor-Jobs. Nachteil: kein Migrationspfad. Vorteil: Fahrten und Tankvorgänge bleiben von Hand einsehbar und mit den bestehenden Sicherungen kompatibel.

Empfehlung: Dateien behalten. Bei einem Fahrzeugprofil, einem Fahrtenbuch und einer Tankhistorie ist Lesbarkeit mehr wert als Migrationskomfort — und die vorhandene Sicherungslogik bleibt gültig.

Unabhängig davon: Fahrten und Tankvorgänge gehören nicht in Entitäts-Attribute (16-KB-Grenze, siehe frontend_veroeffentlichung.py), sondern hinter einen HomeAssistantView. Das ist zugleich die saubere Schnittstelle für die Companion-App, die heute Attribut-Blobs auslesen muss.

7. Was dabei konstruktionsbedingt verschwindet

Aus REVIEW_main_2026-08-13.md:

• Befund 1 (Speichern mit leerem Katalog löscht alle Zuordnungen) — der Konfigurationsdialog validiert serverseitig, ein leeres Formular kommt gar nicht durch.
• Befunde 2 und 5 (Zurücksetzen wirkungslos bzw. zu stark) — die setattr-Override-Ebene entfällt komplett; HA verwaltet Optionen selbst.
• Befunde 3 und 4 (falsche Vorbelegung, beliebige Sensoren) — HAs Entity-Picker schlägt nichts vor, der Nutzer wählt; exclude_entities verhindert Doppelbelegung.
• Befund 7 (kaputte entitaeten.json legt das Panel lahm) — die Datei existiert nicht mehr.
• Der Neustart-Zwang bei den drei triggergebundenen Feldern — add_update_listener lädt die Integration neu und registriert die Horcher dabei mit den neuen Entity-IDs.

Nicht gelöst werden dadurch: die Frontend-Befunde (Standort-Dauerfeuer, Barrierefreiheit, .navmarke) — das Frontend bleibt ja unverändert.

8. Aufwand und Reihenfolge

Realistisch einige Tage, nicht Wochen — der Großteil ist Umschreiben von Dekoratoren.

1. Zuerst die drei Setup-Fehler roh fixen. Erledigt am 2026-08-13 — siehe REVIEW_main_2026-08-13.md. Die Instanz läuft bis zur Umstellung ohne den Datenverlust-Pfad, der Zeitdruck ist damit raus.
2. Gerüst aufsetzen: manifest.json, config_flow.py, Panel- und Dateiregistrierung. Die pyscript-Skripte laufen dabei zunächst unverändert weiter.
3. Logik Datei für Datei herüberziehen, beginnend mit fahrtabschluss_logik.py — dort verschwinden Token und blockierender Aufruf zuerst.
4. update.py gegen das Gitea-Repository.
5. api.py für die Companion-App, sobald diese so weit ist.

Was dabei zu beachten ist

• Neuladen im laufenden Betrieb entfällt. pyscript lädt bei jeder Dateiänderung neu; eine Integration braucht einen Neustart oder ein Neuladen. Beim Entwickeln spürbar, im Betrieb egal.
• Die Companion-App liest heute pyscript.audi_dashboard_*. Werden daraus eigene Entitäten oder ein eigener Endpunkt, ändert sich die Tabelle ENTITAETEN in companion-app/src/api/types.ts — eine Datei, überschaubar.
• shell_beleg_parser.py wandert mit in die Integration. Heute liegt er unter /config/audi_dashboard/ und wird von keinem Update-Pfad ausgeliefert (siehe Review) — als Teil des Integrationsordners löst sich das mit.