diff --git a/COMPANION_APP_ARCHITECTURE.md b/COMPANION_APP_ARCHITECTURE.md index 4bffa9d..07af1d8 100644 --- a/COMPANION_APP_ARCHITECTURE.md +++ b/COMPANION_APP_ARCHITECTURE.md @@ -72,7 +72,12 @@ as Android. All vehicle data comes from the FMM003 (see §2), not from the iPhon into Home Assistant as one combined, flexibly-mapped entity (no hardcoded field list — see the no-hardcoding mapping system discussed separately, not yet written to a file). -**Decided (2026-08-10, after web research — see rationale below): Traccar, minimal variant.** +> **ÜBERHOLT durch eine neue Erkenntnis (2026-08-11): Der FMM003 kann Codec JSON.** +> Damit entfällt Traccar ersatzlos — siehe den Abschnitt „§2b Codec JSON + MQTT" direkt unterhalb. +> Der folgende Traccar-Abschnitt bleibt als Entscheidungsprotokoll stehen, ist aber **nicht mehr der +> geplante Weg**. + +**Überholte Entscheidung (2026-08-10, nach Recherche): Traccar, minimale Variante.** **Research question:** is there something more efficient than Traccar for decoding Codec8 from an FMM003? Checked and ruled out: @@ -110,6 +115,71 @@ FMM003? Checked and ruled out: Hardware confirmed sufficient for this: Dell OptiPlex 3000 TC, Pentium N6005, 16 GB DDR4, 256 GB NVMe — comfortably enough for Traccar alone, more so without a MariaDB add-on alongside it. +--- + +## 2b. Codec JSON + MQTT — der tatsächlich geplante Weg (2026-08-11) + +**Neue Information vom Besitzer: der FMM003 beherrscht „Codec JSON".** Das ändert die Architektur +grundlegend, weil damit die eine Sache entfällt, die Traccar überhaupt nötig gemacht hat: das +Entschlüsseln des binären Codec8-Protokolls. Das Gerät liefert die Daten dann bereits als JSON. + +### Was recherchiert und bestätigt ist + +- **Codec JSON ist ein Datenprotokoll, kein Transportweg.** Eingestellt wird es im Teltonika + Configurator unter *System → System Settings → Data Protocol → Codec JSON*. +- **Der zugehörige Transportweg ist MQTT**, nicht ein HTTP-Webhook: *GPRS Server Settings → MQTT*. + Das war die wichtigste Überraschung — die erste Vermutung „JSON heißt HTTP-POST an einen + HA-Webhook" ist falsch. +- **Ein eigener Broker ist vorgesehen:** in den MQTT-Einstellungen werden schlicht IP und Port des + Brokers eingetragen; Login und Passwort werden verwendet, wenn der Broker Anmeldung verlangt. +- **TLS ist Pflicht, nicht optional:** ohne hochgeladene Zertifikate arbeitet MQTT nicht. Zertifikat, + privater Schlüssel und Wurzelzertifikat werden im Configurator unter *Security* hinterlegt. +- **Firmware-Abhängigkeit:** Codec JSON ist nicht in jeder Firmware enthalten (bei mehreren + Modellen erst ab 03.28.00 dokumentiert). Der Besitzer bestätigt, dass es auf diesem Gerät + verfügbar ist — vor der Inbetriebnahme trotzdem die Firmware-Version notieren. +- **Home Assistant kann MQTT von Haus aus:** Mosquitto-Broker als offizielles Add-on, dazu die + MQTT-Integration mit `sensor`/`device_tracker`, `json_attributes_topic` und Templates, um beliebige + JSON-Felder herauszuziehen. Es gibt Community-Berichte, die genau das mit Teltonika-Trackern + gemacht haben. + +### Was damit ersatzlos entfällt + +| Bisher geplant | Jetzt | +|---|---| +| Traccar-Add-on | entfällt — es gibt nichts mehr zu dekodieren | +| Traccar-Datenbank (H2) inkl. Sicherung der `.mv.db` | entfällt — kein eigener Datenspeicher mehr | +| Position Forwarding → HA-Webhook | entfällt — HA hört direkt am Broker mit | +| Offener roher TCP-Port für Codec8 | entfällt — stattdessen MQTT über TLS | +| Eigener Codec8-Decoder als Alternative | erledigt sich | + +Übrig bleibt: **FMM003 → MQTT/TLS → Mosquitto-Add-on → MQTT-Integration → Entitäten in HA.** Ein +Baustein statt dreien, und alle Teile davon sind offizielle HA-Add-ons beziehungsweise +Kernintegrationen statt Fremdsoftware. + +### Was dadurch neu zu klären ist + +1. **Erreichbarkeit des Brokers von außen.** Das Problem verschwindet nicht, es ändert nur die Form: + Das Fahrzeug muss den Broker im Internet erreichen. Cloudflare Tunnel hilft hier **nicht** — der + ist auf HTTP zugeschnitten, und der FMM003 kann keinen Tunnel-Client mitbringen. Zwei gangbare + Wege: + - **Portfreigabe 8883** direkt auf Mosquitto. Verstößt formal gegen den Grundsatz „nichts + freigeben", ist aber etwas völlig anderes als Home Assistant selbst freizugeben: ein Port mit + TLS-Zwang und Anmeldung, hinter dem nur ein Nachrichtenbroker sitzt. + - **Kleiner Broker auf einem VPS**, der per Mosquitto-eigenem *Bridge*-Modus mit dem Broker + zuhause gekoppelt wird (die Verbindung baut das Zuhause nach außen auf, über Tailscale). Dann + ist zuhause weiterhin nichts erreichbar. Aufwendiger, dafür ohne jede Freigabe. +2. **Tatsächliche Nutzlast.** Wie die CAN/FMS-Werte im JSON heißen, ist noch unbekannt. Sobald das + Gerät läuft: mit MQTT Explorer oder `mosquitto_sub` eine echte Nachricht mitschneiden und daraus + die Zuordnungstabelle bauen (siehe offener Punkt 2 in §5) — nicht vorher raten. +3. **Zertifikate.** Für Mosquitto müssen Server-Zertifikat und die passenden Dateien für das Gerät + erzeugt werden. Bei eigenem Broker heißt das in der Regel eine eigene kleine CA. +4. **Datenvolumen.** Teltonika weist selbst darauf hin, dass Codec JSON deutlich mehr Bytes braucht + als das binäre Codec8E. Bei einem privat genutzten Fahrzeug ist das vernachlässigbar, sollte man + bei einem knappen Mobilfunktarif aber im Blick behalten. + +Beides — Broker-Erreichbarkeit und Zertifikate — ist erst bei der Inbetriebnahme zu erledigen und +blockiert nichts, was jetzt gebaut wird. + ### Trip detection (substitutes the old WLAN-based logic) - **Start / end trigger:** FMM003 ignition state (CAN), not WLAN connectivity. @@ -230,7 +300,14 @@ else in this document: 1. **Exact reverse-proxy path allowlist** — depends on the final pyscript entity/service names once the FMM003 combined-entity mapping is implemented; write these down here once decided. 2. **No-hardcoding mapping system** for the FMM003 combined entity — discussed in an earlier session, - not yet written to a file or finalized in detail. + not yet written to a file or finalized in detail. **Kann erst nach der ersten echten + MQTT-Nachricht fertig werden** (§2b): die Feldnamen im Codec-JSON sind noch unbekannt und werden + mitgeschnitten, nicht geraten. +2a. **Erreichbarkeit des MQTT-Brokers für das Fahrzeug** — Portfreigabe 8883 gegen VPS-Broker mit + Mosquitto-Bridge, siehe §2b. Betrifft nur den Weg Fahrzeug→Zuhause und ist unabhängig von der + Anbindung der App (§4, dort bleibt es bei Cloudflare Tunnel). +2b. **TLS-Zertifikate für Mosquitto und das Gerät** — bei der Inbetriebnahme zu erzeugen; ohne sie + verweigert der FMM003 die MQTT-Verbindung. 3. **Reverse-proxy add-on: Nginx Proxy Manager vs. Traefik** — both viable (§4), pick deferred to the next audit pass. Doesn't depend on the FMM003 — could be set up and tested against HA's existing API before the hardware arrives, if worth doing ahead of time.