# MQTT-Anbindung (Prüfstände live anbinden)

## Was ist das?

Prüfstände, die MQTT sprechen, können ihre Messwerte direkt an TestLabIQ
liefern — ohne CSV-Umweg und ohne eigenes REST-Skript. Die App verbindet sich
dazu mit Ihrem MQTT-Broker (z. B. Mosquitto, EMQX, HiveMQ) und nimmt alle
Nachrichten auf einem Topic entgegen. Verarbeitung und Mandantentrennung sind
identisch zur REST-Ingestion: der Prüfstand-API-Key entscheidet, wohin die
Werte gehören.

## So benutzt man es

1. **Broker konfigurieren (Betreiber/On-Premise):** In der Umgebung der App
   `MQTT_BROKER_URL` setzen (z. B. `mqtts://broker.example:8883`), optional
   `MQTT_USERNAME`/`MQTT_PASSWORD` und `MQTT_TOPIC` (Standard
   `testlabiq/ingest`). Ohne `MQTT_BROKER_URL` ist die MQTT-Ingestion
   vollständig abgeschaltet.
2. **Prüfstand-API-Key holen:** Auf der Detailseite des Prüfstands (wie bei
   der REST-Ingestion). Der Key identifiziert Prüfstand **und** Organisation.
3. **Prüfstand publizieren lassen:** JSON auf das Topic (QoS 1 empfohlen),
   gleiches Format wie der REST-Push plus `apiKey`:

   ```json
   {
     "apiKey": "<Prüfstand-API-Key>",
     "sequenceItemId": "<uuid>",
     "measurements": [
       { "timestamp": "2026-07-20T08:00:00Z", "channelName": "U_in",
         "value": 12.1, "unit": "V" }
     ]
   }
   ```

   Der Key steht bewusst im Payload und **nicht im Topic**: Topics sind in
   Broker-Logs und ACLs überall sichtbar — ein Geheimnis hat dort nichts
   verloren.
4. **Live mitverfolgen:** Eingehende Werte erscheinen sofort im Abschnitt
   **„Live-Messwerte"** — auf der Seite des laufenden Testfalls (nur Werte
   dieses Testfalls) oder auf der Prüfstand-Detailseite (alle Werte dieses
   Prüfstands, unabhängig von Testfall/Sequenz). Die Ansicht ist ein reiner
   Lesekanal: Prüfstand → App → Browser; Befehle zurück an den Prüfstand gibt
   es bewusst nicht.
5. **Zwischen Kacheln und Diagramm umschalten:** Standardmäßig zeigt die
   Ansicht Kacheln — letzter Wert je Messkanal (farblich gegen die Grenzwerte
   geprüft, sofern hinterlegt) plus Min/Max seit dem Öffnen der Seite. Über
   den Umschalter oben rechts wechselt die Ansicht auf ein Liniendiagramm, das
   mehrere Messkanäle gleichzeitig darstellt (z. B. Spannung, Strom und
   Temperatur in einem Chart) — jeder Kanal in eigener Farbe, per Klick auf
   die Legende einzeln aus- und einblendbar. Die Zeitachse lässt sich fest auf
   1 Minute bis 6 Stunden einstellen oder auf **Automodus** stellen, der sich
   fortlaufend an die vorhandenen Daten anpasst.
6. **Kontrollieren:** Per MQTT gibt es keine Antwort an den Prüfstand. Ob die
   Werte angekommen sind, zeigt das **Zustell-Log**: abrufbar über
   `GET /api/v1/ingestion/deliveries` (siehe [REST-API](https://www.testlabiq.com/hilfe/rest-api)) oder die
   Frage „Warum kommen meine Messwerte nicht an?" an den Support-Assistenten.

## Typische Probleme

- **Werte kommen nicht an, nichts im Zustell-Log.** Entweder erreicht die
  Nachricht die App nicht (Broker/Topic prüfen: publiziert der Prüfstand auf
  das konfigurierte Topic? Ist `MQTT_BROKER_URL` gesetzt?) oder der `apiKey` im
  Payload ist ungültig — dann kann die Nachricht keiner Organisation zugeordnet
  werden und erscheint nur im Server-Log des Betreibers.
- **Zustell-Log zeigt „Sequenz-Item nicht gefunden…".** Die `sequenceItemId`
  gehört nicht zur Organisation dieses Prüfstands oder existiert nicht. ID
  prüfen — sie steht auf der Testdurchführungs-Seite des jeweiligen Testfalls.
- **Zustell-Log zeigt „Ungültiges Payload…".** Pflichtfelder fehlen oder haben
  den falschen Typ (`timestamp` als ISO-8601, `value` als Zahl). Die Meldung
  nennt die betroffenen Felder.
- **Doppelte Werte.** Identische Messpunkte werden übersprungen (`duplicates`
  im Zustell-Log). Kein Fehler — das macht QoS-1-Wiederholungen nach einem
  Reconnect harmlos.
- **Werte kamen verzögert an.** Bei Verbindungsabbruch puffert der Broker
  (QoS 1, persistente Session) und liefert nach, sobald die App wieder
  verbunden ist. Nichts zu tun.
- **Live-Ansicht zeigt nichts, obwohl Werte ankommen.** Die Ansicht zeigt nur
  Werte für **diesen** Testfall (`sequenceItemId` im Payload prüfen) und ist
  nur sichtbar, solange der Testfall nicht abgeschlossen ist. Nach Abschluss
  zählt die Messergebnis-Tabelle, nicht der Live-Strom.
- **Diagramm zeigt für ein großes Zeitfenster nur einen Ausschnitt.** Die
  Rückschau ist auf maximal 24 Stunden begrenzt, damit eine einzelne Anfrage
  nicht die komplette Messwert-Historie eines Prüfstands laden muss. Für
  ältere Auswertungen die Messergebnis-Tabelle bzw. den Report verwenden statt
  der Live-Ansicht.

---

Quelle: https://www.testlabiq.com/hilfe/mqtt-anbindung