From 2c6e8e5ce49dab72222f812e4cf819ffbd8203c7 Mon Sep 17 00:00:00 2001 From: Tobi G Date: Wed, 12 Aug 2026 16:07:47 +0200 Subject: [PATCH] =?UTF-8?q?INSTALL.md=20an=20Setup-Men=C3=BC=20und=20FMM00?= =?UTF-8?q?3=20anpassen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ersetzt die veralteten Installationsschritte (manuelles Eintragen von WLAN_SENSOR/TommiG1-Entity-IDs in einstellungen.py) durch eine Anleitung für das neue Setup-Menü in der App und die aktuellen FMM003-Feldnamen (ZUENDUNG_SENSOR, STANDORT_TRACKER, BATTERIE_SENSOR). AGENTS.md entsprechend nachgeführt. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 23 ++++------ homeassistant/INSTALL.md | 93 +++++++++++++++++++++++++--------------- 2 files changed, 68 insertions(+), 48 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4318a07..b718fb6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,15 +149,6 @@ capacitor/iframe/browser (`umgebung.ts`), types + entity table (`types.ts`), fac - `homeassistant/README.md:99`, `INSTALL.md:204`, and the header comment `audi-dashboard-app.js:13-15` claim the statistics view shows sample numbers — **false**; `vStat()` computes real values from `TRIPS`/`FILLS`. -- `INSTALL.md` step 4 names variables that no longer exist (`DOORS_SENSOR`, `WINDOWS_SENSOR`, - `LOCK_ENTITY`, `BATTERY_VOLTAGE_SENSOR`) — actual names: `TUER_SENSOREN`/`FENSTER_SENSOREN`/ - `TUERSCHLOSS_SENSOREN`/`BATTERIE_SENSOR`. -- **(worse than drift, since 2026-08-12)** `INSTALL.md` step 4 and its troubleshooting table - still walk through configuring `WLAN_SENSOR` and the `TommiG1/HA_VAG-EU-Data-Act` entities - (`KM_SENSOR`, `TANK_SENSOR`, etc.) — both are gone (see section B). A fresh install following - this doc today would configure settings that no longer exist and skip `ZUENDUNG_SENSOR`/ - `STANDORT_TRACKER`, which now actually matter. Needs a real rewrite, not a find-replace — not - done yet, flagging so it isn't mistaken for accurate. - `homeassistant/README.md:110` mentions the removed 97% full-tank rule (removal documented in `belegverarbeitung.py:18-20`); the README file list omits 5 pyscript files. - Obsolete comment `belegverarbeitung.py:41` ("TODO: Datei ablegen" — file has long existed). @@ -272,9 +263,12 @@ capacitor/iframe/browser (`umgebung.ts`), types + entity table (`types.ts`), fac Übersicht correctly shows "Status unbekannt" and em-dash placeholders for the now-blank VAG fields instead of crashing (that container itself has no `device_tracker.testzone_fmm003` registered, so Standort still shows "Kein GPS-Signal" there — expected, the real HA instance - has it). **Follow-up still needed:** `INSTALL.md` step 4 and its troubleshooting table still - document the old WLAN/TommiG1 entity list — now actively wrong, not just stale (see - Documentation drift below). + has it). `INSTALL.md` step 4 and its troubleshooting table have since been rewritten + (2026-08-12) to point at the Setup menu instead of manual `einstellungen.py` edits, and to + use the current FMM003 field names (`ZUENDUNG_SENSOR`/`STANDORT_TRACKER`/`BATTERIE_SENSOR`) + instead of `WLAN_SENSOR`/TommiG1 — not live-tested against a real install (INSTALL.md itself + was never run end-to-end in this project, per its own opening note), but consistent with the + actual code. ### C) Maintain the existing HA panel (low priority — being replaced) @@ -345,8 +339,9 @@ capacitor/iframe/browser (`umgebung.ts`), types + entity table (`types.ts`), fac the whole popup partially see-through against the app content behind it. Fixed by switching to `--tile-deckend` (Design's own opaque-surface token, already used by `.standortmenu` for the same reason), with `var(--canvas)` as a defensive fallback. -- [ ] Fix documentation drift (statistics claim, INSTALL variable names, README gaps, obsolete - TODO comment) — text-only changes +- [ ] Fix remaining documentation drift (statistics claim, README gaps, obsolete TODO comment) — + text-only changes; INSTALL.md's WLAN/TommiG1 drift and stale variable names were fixed + 2026-08-12 (see section B) - [ ] Harden `profil_lesen()` against missing/corrupt `fahrzeugprofil.json` - [ ] Decide whether the 3 audit leftovers get fixed here or only in DataMetric360 - [ ] Optional: persist the RAM-only states (trip start, fuel low-water-mark) — deliberately diff --git a/homeassistant/INSTALL.md b/homeassistant/INSTALL.md index 419fc1e..03c6803 100644 --- a/homeassistant/INSTALL.md +++ b/homeassistant/INSTALL.md @@ -22,8 +22,13 @@ zeigt. `panel_custom` selbst ist Home Assistants eigener, seit Jahren stabiler Mechanismus, nicht eigener Code, entsprechend gering ist das Risiko dort. -**Voraussetzung:** HACS ist bereits installiert (ergibt sich aus der -laufenden Integration `TommiG1/HA_VAG-EU-Data-Act`). +**Voraussetzung:** HACS ist bereits installiert (wird für pyscript selbst +gebraucht, siehe Schritt 1). Für die Fahrterkennung und die Fahrzeugdaten +wird zusätzlich ein Teltonika FMM003 (bzw. dessen Integration in Home +Assistant, z. B. über flespi) vorausgesetzt — Details siehe +`COMPANION_APP_ARCHITECTURE.md` im Projektstamm. Ohne FMM003 läuft die App +trotzdem: alle davon abhängigen Werte zeigen einfach „unbekannt" statt +eines Werts. Zeitaufwand: ca. 30–40 Minuten, größtenteils Warten auf Neustarts. @@ -82,36 +87,52 @@ ergänzen statt einen zweiten Block anzulegen. Der `panel_custom:`-Block kann schon jetzt mit rein; er wird erst mit dem Frontend-Baustein wirksam und stört bis dahin nicht. -## Schritt 4 — die Entity-IDs eintragen +## Schritt 4 — die Sensoren zuordnen -Das ist die einzige Stelle, die inhaltlich angepasst werden muss — Datei -`pyscript/modules/einstellungen.py`. +Anders als früher wird dafür **nicht** mehr `pyscript/modules/ +einstellungen.py` von Hand bearbeitet — das übernimmt ein grafisches +Setup-Menü direkt in der App: **Mein Audi → Einstellungen → Fahrzeug +einrichten → Einrichten → „Setup — Sensoren zuordnen"** (letzter Punkt, +erscheint erst nach Klick auf „Einrichten"). Dafür muss die App bereits +laufen, siehe Schritt 9 zuerst. -**Zwingend fürs Backend** (ohne diese drei läuft die Kernlogik nicht): +Das Setup-Menü listet jede Sensor-Rolle, die die App kennt (Zündung/ +Fahrterkennung, Kilometerstand, Tankfüllstand, Standort, Batteriespannung, +Türen/Fenster/Schlösser, Ölwechsel/Inspektion, …), schlägt je Rolle +passende vorhandene HA-Entitäten vor (Schalter „Nur passende Sensoren +anzeigen" grenzt auf die erwartete Domäne/Einheit ein) und schreibt die +Auswahl direkt in eine Override-Datei — `einstellungen.py` selbst bleibt +unverändert. -1. In Home Assistant: **Entwicklerwerkzeuge → Zustände** -2. Dort suchen und die genauen Entity-IDs notieren für: - - den Kilometerstand-Sensor (aus `TommiG1/HA_VAG-EU-Data-Act`) → `KM_SENSOR` - - den Tankfüllstand-Sensor (dieselbe Integration) → `TANK_SENSOR` - - den WLAN-Verbindungssensor des iPhones → `WLAN_SENSOR` — dafür vorher - in der iOS-Companion-App unter **Einstellungen → Companion App → - Sensoren** den Sensor für das verbundene WLAN aktivieren, falls er dort - noch grau ist +**Zwingend, damit die Fahrterkennung läuft:** +- **Zündung/ACC-Status** (`ZUENDUNG_SENSOR`) — ein `binary_sensor`, `on` + = Fahrt läuft. Kommt vom Teltonika FMM003 (z. B. + `binary_sensor._engine_ignition_or_acc_status`). -**Optional fürs Frontend** (nur für die Übersicht/Zustand-Seite, ohne sie -zeigt die Oberfläche „unbekannt" statt eines Werts — kein Absturz): +**Alles Weitere ist optional** — ohne zugeordneten Sensor zeigt die +Oberfläche „unbekannt"/em-dash statt eines Werts, kein Absturz: +- Kilometerstand (`KM_SENSOR`), Tankfüllstand (`TANK_SENSOR`), Reichweite + (`RANGE_SENSOR`) — bis zu einer neuen Datenquelle unbelegt, siehe + `AGENTS.md` (die frühere `TommiG1/HA_VAG-EU-Data-Act`-Integration liefert + diese nicht mehr) +- Standort (`STANDORT_TRACKER`, ein `device_tracker`) und Batteriespannung + (`BATTERIE_SENSOR`) — vom FMM003, z. B. `device_tracker.` + bzw. `sensor._external_power_voltage` (**nicht** + `..._battery_voltage` — das ist die interne Pufferzelle des Trackers, + nicht die Fahrzeugbatterie) +- Türen/Fenster/Schlösser, Ölwechsel/Inspektion — je nach Fahrzeug/ + Integration vorhanden oder nicht -3. Ebenfalls in Entwicklerwerkzeuge → Zustände suchen: - - Reichweite → `RANGE_SENSOR` - - Türstatus (falls als ein Sammel-Sensor vorhanden) → `DOORS_SENSOR` - - Fensterstatus → `WINDOWS_SENSOR` - - Verriegelung (Domäne `lock.`) → `LOCK_ENTITY` - - Batteriespannung, falls überhaupt vorhanden → `BATTERY_VOLTAGE_SENSOR` +Wer lieber direkt in Entwicklerwerkzeuge → Zustände nach Entity-IDs sucht, +kann das weiterhin tun — die Suche im Setup-Menü filtert exakt auf +denselben Datenbestand (`HASS.states`), nur mit Vorschlägen und Filter. -4. Datei `pyscript/modules/einstellungen.py` öffnen (Samba: direkt im - Explorer, Studio Code Server: im Editor) und alle gefundenen Werte - eintragen. Was ihr nicht findet, einfach auf dem Platzhalter stehen - lassen — siehe Kommentar in der Datei dazu. +**Einschränkung bei drei Feldern** (Zündung, Kilometerstand, +Tankfüllstand): sie sind intern fest mit einem Auslöser verdrahtet +(`@state_trigger`), der einmalig beim Laden des Backends gesetzt wird. +Eine Änderung im Setup-Menü wird gespeichert, wirkt für die Fahrterkennung +selbst aber erst nach einem Neustart von Home Assistant — das Setup-Menü +zeigt dafür einen Hinweis an. ## Schritt 5 — Long-Lived Access Token erzeugen @@ -152,10 +173,14 @@ eingebauten Weg, auf die Recorder-Historie zuzugreifen, deshalb läuft das `pyscript.audi_dashboard_tankvorgang_manuell` sollten dort erscheinen Wenn das alles stimmt, läuft das Backend. Die Fahrterkennung selbst lässt -sich am einfachsten testen, indem das WLAN am Handy kurz ausgeschaltet und -wieder eingeschaltet wird (Pausenregel greift) bzw. länger als die -eingestellte Pausenzeit ausgeschaltet bleibt (Fahrt wird angelegt) — danach -in `audi_dashboard/fahrten.jsonl` nachsehen, ob eine Zeile entstanden ist. +sich am einfachsten testen, indem der Zündungs-Sensor (`ZUENDUNG_SENSOR`, +nach dem Zuordnen in Schritt 4) kurz auf `on` und wieder auf `off` gesetzt +wird (Pausenregel greift, kurzer Ausflug wird als eine Fahrt gewertet) bzw. +länger als die eingestellte Pausenzeit auf `off` bleibt (Fahrt wird +angelegt) — am Fahrzeug reicht dafür kurz die Zündung, ohne Fahrzeug +funktioniert es auch manuell über **Entwicklerwerkzeuge → Zustände** (den +Sensor suchen, Zustand testweise auf `on`/`off` setzen). Danach in +`audi_dashboard/fahrten.jsonl` nachsehen, ob eine Zeile entstanden ist. ## Schritt 8 — was jetzt noch fehlt, bevor es vollständig nutzbar ist @@ -186,7 +211,7 @@ Der `panel_custom`-Eintrag aus Schritt 3 zeigt auf 2. Die Übersicht sollte erscheinen: Fahrzeugbild (als Platzhalter, siehe unten), Typenschild, Kilometerstand, Reichweite. Falls Kilometerstand oder Reichweite „unbekannt"/leer bleiben, obwohl Schritt 7 erfolgreich - war: die optionalen Entity-IDs aus Schritt 4 nachtragen. + war: die optionalen Sensoren aus Schritt 4 im Setup-Menü zuordnen. 3. Falls die Seite leer bleibt oder gar nicht in der Sidebar erscheint: im Browser die Entwicklerkonsole öffnen (F12) und nach Fehlern mit „audi-dashboard" oder „pyscript" suchen — siehe Troubleshooting. @@ -265,10 +290,10 @@ Update-Durchlauf bei euch. |---|---| | `ModuleNotFoundError: No module named 'einstellungen'` (oder `profil`, `fahrtabschluss_logik`) | Ordner falsch kopiert — `modules/`-Unterordner muss unter `pyscript/modules/` liegen, nicht direkt unter `pyscript/` | | pyscript lädt gar nicht, keine Fehler, keine Services | `allow_all_imports: true` fehlt oder Einrückung in der `configuration.yaml` ist falsch (YAML ist einrückungsempfindlich) | -| Fahrt wird nie angelegt | `WLAN_SENSOR` in `einstellungen.py` zeigt auf die falsche Entity, oder `fahrzeug.wlan_name` im Profil passt nicht exakt zum Sensorwert (Groß-/Kleinschreibung zählt) | +| Fahrt wird nie angelegt | `ZUENDUNG_SENSOR` ist im Setup-Menü nicht oder falsch zugeordnet, oder er ist nach einer Änderung im Setup-Menü noch nicht durch einen HA-Neustart aktiv geworden (siehe Schritt 4) | | Screening findet nie einen Kilometerstand | `ha_token.txt` fehlt, ist leer, oder der Token wurde widerrufen — in den Protokollen nach `HTTPError` oder `401` suchen | -| Reifenzähler zeigt dauerhaft „unbekannt" | `KM_SENSOR` in `einstellungen.py` liefert keinen Wert, oder es kam seit der Installation noch keine Änderung des Kilometerstands an (reifenzaehler.py reagiert nur auf Sensor-Änderungen) | +| Reifenzähler zeigt dauerhaft „unbekannt" | `KM_SENSOR` ist im Setup-Menü nicht zugeordnet, oder es kam seit der Installation noch keine Änderung des Kilometerstands an (reifenzaehler.py reagiert nur auf Sensor-Änderungen) | | „Mein Audi" fehlt in der Sidebar | `panel_custom:`-Block fehlt oder ist falsch eingerückt in `configuration.yaml`; nach Änderungen daran hilft nur ein vollständiger Neustart, kein „YAML neu laden" | | Sidebar-Eintrag da, Seite bleibt leer | Browser-Konsole (F12) prüfen: 404 bei `/local/audi-dashboard-panel.js` → Datei liegt nicht unter `/config/www/`; JS-Fehler beim Laden → Datei unvollständig kopiert, Dateigröße mit dem Original vergleichen | -| Übersicht erscheint, aber alle Werte „unbekannt" | Normal, solange `KM_SENSOR`/`TANK_SENSOR`/... in `einstellungen.py` noch Platzhalter sind (Schritt 4) — kein Frontend-Fehler | +| Übersicht erscheint, aber alle Werte „unbekannt" | Normal, solange `KM_SENSOR`/`TANK_SENSOR`/... im Setup-Menü noch nicht zugeordnet sind (Schritt 4) — kein Frontend-Fehler | | Karten bleiben leer auf Fahrt-/Tankdetailseite | Gerät hat keinen Internetzugang zusätzlich zu Tailscale — Leaflet lädt von einem CDN (siehe Schritt 9) |