MQTT Client

Contents HideContents Show
  1. Über das Plugin
  2. Terminologie
  3. Einrichtung
  4. Verbindungseinstellungen
  5. Bearbeiten oder Exportieren der Konfiguration
  6. Umgang mit Fehlern
  7. Einschränkungen
  8. Kompatibilität
  9. Unterstützte Datentypen
  10. Weitere Hinweise

Über das Plugin

Mit dem MQTT-Client können Sie eine Verbindung zu einem MQTT-Broker herstellen. Genauer gesagt können Themen abonniert werden und Nachrichten können in Themen veröffentlicht werden.

Terminologie

  • Themen – Kanäle für verschiedene Nachrichten innerhalb eines MQTT-Brokers. Ein Thema hat normalerweise nur eine Art von Nachricht.
  • Broker – Vermittlungskomponente der MQTT-Kommunikation, die Nachrichten empfängt und sie an alle Clients sendet, die dieses Thema abonniert haben.
  • Abonnieren – Ein Kunde kann ein Thema abonnieren. Danach sendet der Broker alle Nachrichten in diesem Thema an alle Abonnenten.
  • Veröffentlichen – Ein Client kann eine Nachricht in einem Thema veröffentlichen. Danach sendet der Broker diese Nachricht erneut an alle Abonnenten.
  • QoS – Quality of Service.

Einrichtung

Um die folgenden Schritte auszuführen, benötigen Sie Zugriff auf einen laufenden MQTT-Broker.

  1. Verbindung mit einem MQTT-Broker herstellen

    1. Verbindungsinformationen
      1. Host: Adresse des MQTT-Brokers.
        1. Geben Sie die Adresse ohne das Präfix „mqtt://“ ein.
      2. Portnummer
    2. Wählen Sie Authentifizierung, um den Benutzernamen und das Passwort für den Broker einzugeben, falls erforderlich.
      1. Wenn die Broker-Authentifizierung die Verwendung einer bestimmten MQTT-Kunden-ID erfordert, wählen Sie unter Erweiterte Optionen die Option Benutzerdefiniert aktivieren und fügen Sie die Kunden-ID (Optional) hinzu.
    3. Klicken Sie auf Verbindung testen.
    4. Klicken Sie auf Speichern.

    5. Klicken Sie auf die Schaltfläche Verbinden/Trennen.

  2. Themen hinzufügen

    1. Klicken Sie auf Sub/Pub in der oberen Multifunktionsleiste, um das Fenster MQTT-Nachrichten zu öffnen.

    2. Klicken Sie auf +, um neue Themen hinzuzufügen. Dies öffnet den Editor Abonnement hinzufügen.
    3. In Benutzerdefinierte Themen hinzufügen definieren Sie den Namen des Themas.
    4. Eine optionale Nachrichtenvorlage im JSON-Format kann ebenfalls definiert werden. Dies unterstützt die Verknüpfung von Variablen innerhalb des Nachrichtenobjekts mit verschiedenen Simulationsvariablen.
      Hinweis: Siehe den Abschnitt Weitere Hinweise unten für Syntaxbeispiele.
    5. Stellen Sie die gewünschte QoS-Stufe ein. Standardmäßig ist die Stufe At most once (0).



      Hinweis: Um die Veröffentlichung einer Nachricht in einem Thema ohne Variablenpaarung zu testen, erweitern Sie Veröffentlichen und geben Sie den Inhalt der Nachricht ein.

  3. Variablenpaarung

    1. Öffnen Sie den Editor Variablen-Zuordnung hinzufügen.
    2. Verwenden Sie die Suchleiste oder die Filterfunktion, um eine bestimmte Variable zu finden.
      Hinweis: Wenn eine Paarung der Komponentenposition erforderlich ist, verwenden Sie die Positionseigenschaften TransformationInWorld und TransformationInReference.
    3. Verbinden Sie die Eigenschaften oder Signale auf der linken Seite mit den Nachrichten oder Variablen innerhalb der Nachrichtenvorlage auf der rechten Seite.

  4. Formeln definieren

    Dieser Schritt ist nur erforderlich, wenn ein Variablenpaar umgewandelt oder berechnet werden muss. Im Editor für variable Formeln kann ein Ausdruck definiert werden, um den Inhalt der Nachricht in das gewünschte Format zu konvertieren.
    Hinweis: Siehe den Abschnitt Weitere Hinweise unten für Syntaxbeispiele.

    SimulationToServer-Variablenpaare enthalten eine Ist Auslöser?-Eigenschaft, die definiert, ob eine Änderung des Variablenwerts die Veröffentlichung einer Nachricht auslöst.


    In Ausdrücken für SimulationToServer-Variablenpaare kann mit dem Schlüsselwort Value auf den aktuellen Wert der Eigenschaft oder des Signals zugegriffen werden.

    In Ausdrücken für ServerToSimulation-Variablenpaare kann auf den Wert der Variablen in der MQTT-Nachricht mit Hilfe der Punktnotation und dem Schlüsselwort Payload zugegriffen werden.
    Hinweis: Siehe den Abschnitt Weitere Hinweise unten für Syntaxbeispiele.

Verbindungseinstellungen

  1. Aktualisierungsmodus: Zyklisch oder Ereignisbasiert.
    1. Aktualisierungsmodus Zyklisch: Aktualisierungsintervall begrenzt die Rate der gesendeten und empfangenen Nachrichten.
    2. Aktualisierungsmodus Ereignisbasiert: Nachrichten werden immer gesendet, wenn sich der Wert einer auslösenden Eigenschaft ändert. Alle empfangenen Nachrichten werden sofort verarbeitet.
  2. Zuordnungssteuerung: Exportieren oder Importieren von Themendefinitionen und Variablenpaaren im .CSV-Format.
  3. Simulationssteuerung: Nur in der Simulation aktualisieren legt fest, ob Aktualisierungen nur bei laufender Simulation erfolgen. Um dies auf Falsch zu setzen, muss der Aktualisierungsmodus Ereignisbasiert sein.
  4. Erweitert: Kunden-ID legt die Kennung fest, die der MQTT-Client bei der Verbindung mit einem Broker verwendet.
  5. Erweitert: Nachrichten aufzeichnen Die Nachrichten werden in Textdateien gespeichert, eine pro Topic und MQTT-Client-Sitzung. Die Dateien werden gespeichert in:
    C:\Users\%username%\AppData\Local\Visual Components\%version%\Plugins\MQTT\Messages

Bearbeiten oder Exportieren der Konfiguration

Mit Konfigurieren in der obigen Multifunktionsleiste kann die MQTT-Verbindungskonfiguration als JSON- oder XML-Datei geöffnet werden, um die Konfiguration zu bearbeiten oder zu exportieren. Die Datei wird in dem Standard-Texteditor auf dem PC geöffnet. Änderungen an der Konfigurationsdatei werden nach dem Speichern der Datei und dem Schließen des Texteditors übernommen.

Umgang mit Fehlern

  • Nachrichtenvorlagen werden validiert, sobald sie hinzugefügt werden.
  • Wenn eine empfangene Nachricht Variablen enthält, die nicht in der Nachrichtenvorlage enthalten sind, wird die Nachricht dennoch verarbeitet.
  • Wenn in einer empfangenen Nachricht die in der Nachrichtenvorlage definierten Variablen fehlen, werden die Simulationsvariablen, die mit den fehlenden Nachrichtenvariablen gepaart sind, nicht aktualisiert.
  • Ausdrücke werden nach dem Hinzufügen mit der Schaltfläche Aktualisieren validiert.
  • Wenn sich ein Ausdruck auf eine Nachrichtenvariable bezieht, die in einer Nachricht fehlt, wird die Simulationsvariable nicht aktualisiert.

Einschränkungen

Wildcard-Themenabonnements mit einstufigen oder mehrstufigen Symbolen (+, #) werden nicht unterstützt: Es können nur bestimmte Themen abonniert werden.

Variablenpaare können nicht direkt mit Objekten gebildet werden, die sich innerhalb eines Arrays in der Nachrichtenvorlage befinden. Der Inhalt von Arrays wird im Editor Variablen-Zuordnung hinzufügen ausgeblendet. Um eine Variable, die sich in einem Array befindet, einer Simulationsvariablen zuzuordnen, verwenden Sie Ausdrücke im Editor für variable Formeln, um den Wert aus der empfangenen Nachricht zu lesen oder um das Array für eine veröffentlichte Nachricht zu konstruieren.
Hinweis: Siehe den Abschnitt Weitere Hinweise unten für Syntaxbeispiele.

Kompatibilität

Die MQTT-Protokollversionen v3.1.0 und v3.1.1 werden unterstützt.

Die Verbindung wurde mit Brokern getestet, die die Portnummern 1883 oder 8883 haben.

Unterstützte Datentypen

Der MQTT-Client unterstützt den Zugriff auf Variablen, die in MQTT-Nachrichten enthalten sind. Wenn Sie eine Nachrichtenvorlage verwenden, liegt die Nachricht im JSON-Format vor.

JSON Type VC PROPERTY TYPE
Array VC_BOOLEAN/VC_REAL/VC_STRING/VC_MATRIX*/VC_VECTOR**
Boolean VC_BOOLEAN
Number VC_INTEGER***/VC_REAL
String VC_STRING

* Ein Array mit 6 numerischen Werten wird als Translations- und Rotationsmatrix (X, Y, Z, Rx, Ry, Rz) interpretiert.
** Ein Array mit 3 numerischen Werten wird als Vektor in einem Server-zu-Simulation-Paar interpretiert. Ein Vektor im Simulation-zu-Server-Paar wird als JSON-Objekt mit 6 Werten veröffentlicht: X, Y, Z, W, Länge und Länge zum Quadrat.
*** Zahlenvariablen werden automatisch gerundet, wenn sie mit Integer-Eigenschaften oder Signalen gepaart sind.

Wenn keine Nachrichtenvorlage verwendet wird, muss die Nachrichten-Nutzlast einen JSON-Typ verwenden. Nutzlasten vom Typ String müssen in Anführungszeichen gesetzt werden.

Weitere Hinweise

Im Folgenden finden Sie Beispielausdrücke, die im Editor für variable Formeln verwendet werden.

Ausdrücke für das Abonnieren:

Koordinatennachricht { "x": 100.0, "y": 200.0, "rz": 90.0} in eine Positionsmatrix konvertieren:

@Array(Payload.x, Payload.y, 0, 0, 0, Payload.rz)

Erstes Element des Arrays in der Nachricht { "jointValues": [0.0, 20.0, 90.0, 0.0, 0.0, 0.0]} auswählen:

Payload.jointValues[0]

Element „Wert“ im zweiten Element des Arrays in der Nachricht { "array": [{"id": 10, "value": 1.0}, {"id": 11, "value": 3.0}]} auswählen:

Payload.array[1].value

Empfangene Nachricht in einen String konvertieren:

Convert.ToString(Payload)

Ausdrücke für die Veröffentlichung:

Rz-Koordinate der Weltposition der Komponente auswählen:

Value[5]

Eine Positionsmatrix in Nachricht { "x": 0.0, "y": 0.0, "rz": 0.0} konvertieren:

@Object(@Pair("x", Value[0]), @Pair("y", Value[1]), @Pair("rz", Value[5]))

Den Wert einer String-Eigenschaft in JSON konvertieren:

@Json(Value)