# 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

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

```yaml
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.