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
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:

```bash
# 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:

```python
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

```python
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:

```python
@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.