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:

   {
     "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) 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.