audi-app/homeassistant/FMM003_MAPPING.md

FMM003 → Home Assistant: Zuordnungstabelle

Gerüst, noch nicht ausgefüllt. Gehört zu Phase 13 des ../UMSETZUNGSPLAN.md; die Architektur dahinter steht in ../COMPANION_APP_ARCHITECTURE.md §2b.

Grundregel: nicht raten. Wie die CAN/FMS-Werte im Codec JSON heißen, ist unbekannt und je nach Firmware verschieden. Die Tabelle unten wird aus einer echten mitgeschnittenen Nachricht gefüllt, nicht aus der Dokumentation abgeleitet. Bis dahin bleiben die Felder leer.

Datenweg

FMM003 (CAN/FMS)  ──MQTT über TLS──▶  Mosquitto-Add-on  ──▶  MQTT-Integration  ──▶  Entitäten

Traccar entfällt: Das Gerät liefert bereits JSON, es gibt nichts zu dekodieren.

Schritt 1 — Gerät einstellen

Im Teltonika Configurator:

Ort	Einstellung
System → System Settings → Data Protocol	Codec JSON
GPRS → Server Settings	Broker-IP und Port 8883
GPRS → Server Settings	Benutzername und Passwort des Brokers
Security	Wurzelzertifikat, Gerätezertifikat, privater Schlüssel

Firmware-Version hier eintragen: ________________

Codec JSON ist nicht in jeder Firmware enthalten (bei mehreren Modellen erst ab 03.28.00). Ohne hochgeladene Zertifikate verweigert das Gerät die MQTT-Verbindung — das ist kein Fehler, sondern Absicht.

Schritt 2 — Nachricht mitschneiden

mosquitto_sub -h <broker> -p 8883 --cafile ca.crt \
  -u <benutzer> -P <passwort> -t '#' -v | tee mitschnitt.txt

Dabei nacheinander: Zündung an, kurz fahren, anhalten, Zündung aus. Danach den Mitschnitt sichten und die Tabelle unten füllen.

Nicht ins Repository legen — der Mitschnitt enthält echte Positionsdaten.

Schritt 3 — Zuordnungstabelle

Aus dem Mitschnitt zu füllen. Die Spalte „Entität" nennt den Namen, unter dem das Backend den Wert erwartet.

JSON-Feld	Bedeutung	Einheit	Entität in HA	Gefunden am
	Zündung an/aus	0/1	binary_sensor.audi_zuendung
	Geschwindigkeit	km/h	sensor.audi_geschwindigkeit
	Position Breite	Grad	device_tracker.audi_position
	Position Länge	Grad	device_tracker.audi_position
	Kilometerstand	km	sensor.audi_kilometerstand
	Tankfüllstand	%	sensor.audi_tankfuellstand
	Drehzahl	min⁻¹	sensor.audi_drehzahl
	Kühlmitteltemperatur	°C	sensor.audi_kuehlmittel
	Bordspannung	V	sensor.audi_bordspannung
	Zeitstempel	ISO/Epoch	— (Attribut)

Teltonika nennt CAN-Werte oft nur über eine AVL-Kennung (etwa "12" für Kraftstoffstand). Deshalb hier immer beides notieren: die Kennung aus der Nachricht und ihre Bedeutung aus der AVL-Liste des Geräts.

Schritt 4 — MQTT-Integration

Aus der ausgefüllten Tabelle entstehen die Entitäten. Gerüst für configuration.yaml, die Feldnamen in den Vorlagen sind erst danach einsetzbar:

mqtt:
  binary_sensor:
    - name: "Audi Zündung"
      state_topic: "teltonika/<imei>/data"
      value_template: "{{ 'ON' if value_json.<FELD> | int == 1 else 'OFF' }}"
      device_class: power

  sensor:
    - name: "Audi Geschwindigkeit"
      state_topic: "teltonika/<imei>/data"
      value_template: "{{ value_json.<FELD> }}"
      unit_of_measurement: "km/h"
      state_class: measurement

  device_tracker:
    - name: "Audi Position"
      state_topic: "teltonika/<imei>/data"
      json_attributes_topic: "teltonika/<imei>/data"
      # latitude/longitude erwartet HA als Attribute

Schritt 5 — Fahrterkennung umstellen

Neues pyscript/fahrterkennung_fmm003.py nach dem Muster von pyscript/fahrterkennung.py, mit zwei Unterschieden:

1. Der Auslöser ist die Zündungs-Entität, nicht der WLAN-Sensor.
2. Der Startzeitpunkt darf nicht mehr nur im Arbeitsspeicher liegen — beim FMM003 gibt es keinen Grund mehr für diese Einschränkung, weil der Zustand jederzeit vom Gerät neu gelesen werden kann.

Unverändert übernehmen: die Pausentoleranz (fahrten_pausenzeit_min aus dem Profil, Standard 15 Minuten) über task.unique() und task.sleep(). Das ist eine bewusste Produktentscheidung, dreimal durchdacht: Springt der Motor innerhalb der Toleranz wieder an, ist es eine Fahrt, nicht zwei. Die Zündung fällt bei Start-Stopp nicht ab, ein zusätzlicher Filter dafür ist also unnötig.

Vorgehen: erst parallel laufen lassen und in eine Testdatei schreiben, mit der bisherigen Erkennung vergleichen, dann scharf schalten. Danach WLAN_SENSOR aus pyscript/modules/einstellungen.py entfernen.

Schritt 6 — Live-Ansicht einschalten

In companion-app/src/funktionen.ts den Schalter LIVE_VERFUEGBAR auf true setzen und in companion-app/src/screens/LiveFahrt.tsx die Feldnamen in liveZustandLesen() an die tatsächlichen Entitäten anpassen.

Damit werden auch die Fahrtdetails erstmals echte Routen zeigen, statt nur Start- und Zielpunkt.

Noch zu entscheiden

• Erreichbarkeit des Brokers für das Fahrzeug: Portfreigabe 8883 direkt auf Mosquitto gegen VPS-Broker mit Mosquitto-Bridge über Tailscale. Ersteres ist einfacher, aber eine echte Freigabe; letzteres öffnet zuhause nichts, kostet aber einen zusätzlichen Server.
• Datenvolumen: Codec JSON braucht deutlich mehr Bytes als das binäre Codec8E. Bei einem privat genutzten Fahrzeug vernachlässigbar, bei knappem Mobilfunktarif im Blick behalten.