Codec JSON statt Traccar: Datenweg vom FMM003 neu festlegen

Der FMM003 beherrscht Codec JSON - damit entfällt der einzige Grund, aus
dem Traccar überhaupt vorgesehen war: das Entschlüsseln des binären
Codec8-Protokolls.

Recherchiert und bestätigt: Codec JSON ist ein Datenprotokoll, kein
Transportweg; der zugehörige Transport ist MQTT, nicht ein HTTP-Webhook.
Ein eigener Broker ist vorgesehen (IP, Port, optional Anmeldung), TLS ist
dabei Pflicht. Home Assistant bringt beides von Haus aus mit: das
Mosquitto-Add-on und die MQTT-Integration samt json_attributes_topic.

Damit entfallen ersatzlos: das Traccar-Add-on, dessen H2-Datenbank samt
Sicherung, das Position Forwarding an einen HA-Webhook, der offene rohe
TCP-Port und die Alternative eines selbst geschriebenen Codec8-Decoders.
Übrig bleibt FMM003 -> MQTT/TLS -> Mosquitto -> MQTT-Integration.

Neu zu klären und in §5 aufgenommen: wie das Fahrzeug den Broker von außen
erreicht (Portfreigabe 8883 oder VPS-Broker mit Mosquitto-Bridge - Cloudflare
Tunnel hilft hier nicht, der ist auf HTTP zugeschnitten), sowie die
TLS-Zertifikate. Die Zuordnungstabelle der Fahrzeugwerte kann erst nach dem
Mitschnitt einer echten MQTT-Nachricht entstehen - die Feldnamen werden nicht
geraten.

Der bisherige Traccar-Abschnitt bleibt als Entscheidungsprotokoll stehen,
deutlich als überholt markiert.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

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.