MQTT-Plugin

Dieses Plugin ermöglicht die Verwendung von MQTT für die Integration von MERLIC als MQTT-Client in eine Fertigungseinrichtung und die Einrichtung der Kommunikation mit einem anderen MQTT-Client, z. B. eine SPS oder ein SCADA-System über TCP. Bei MQTT handelt es sich um ein offenes OASIS-Standardnachrichtenprotokoll für den Datenaustausch zwischen IoT-Geräten. Das MQTT-Plugin ermöglicht die Überwachung des Zustands und der Ergebnisse des Prozessintegrationssystems sowie dessen Steuerung.

Grundlegende Funktionsweise

Themen und Nachrichten

Für die Kommunikation über MQTT können Nachrichten mit einer Länge zwischen 2 Bytes und 256 Megabytes verwendet werden. Die Nachrichten sind in hierarchische Themen mit verschiedenen möglichen Nachrichtentypen unterteilt, z. B. zum Herstellen einer Verbindung, zum Veröffentlichen von Daten und zum Bestätigen des Datenempfangs. Die Erfassung und Verteilung der Nachrichten wird von einem MQTT-Nachrichtenbroker bewerkstelligt. Der Broker erfasst Nachrichten von allen Clients und sendet sie an alle Clients, die das entsprechende Thema abonniert haben. Für Clients, die das Thema abonniert haben, kann eine Nachricht pro Thema beibehalten und zu einem späteren Zeitpunkt gesendet werden.

MQTT-Clients

Ein MQTT-Client kann jedes Gerät mit einer MQTT-Bibliothek sein, das mit dem MQTT-Nachrichtenbroker kommunizieren kann. Bei Verwendung des MQTT-Plugins fungiert MERLIC selbst als MQTT-Client, der Nachrichten mit dem MQTT-Broker austauscht.

Um die Funktion des MQTT-Plugins zu testen, können Sie ein beliebiges vorhandenes MQTT-Clientgerät verwenden, das in Ihrem industriellen Bildverarbeitungssystem eingerichtet ist, oder eine MQTT-Clientsoftware auf Ihrem lokalen System installieren, z. B. MQTT Explorer.

MQTT-Nachrichtenbroker

Bei einem MQTT-Broker handelt es sich um einen Server, der alle Nachrichten von den Clients empfängt und dann abonnierte Nachrichten an MQTT-Clients weiterleitet. Sie können einen beliebigen verfügbaren MQTT-Broker verwenden, z. B. den Broker Eclipse Mosquitto™. Ein öffentliches Exemplar ist unter mqtt://test.mosquitto.org:1883 verfügbar.

Einschränkungen

• Im MQTT-Plugin sind derzeit keine Sicherheitsfunktionen, insbesondere keine zertifikatbasierte TLS/SSL-Verschlüsselung, enthalten.
• Andere Plugins können die Funktion des Plugins stören, z. B. die simulierte SPS, die auf der Registerkarte „Hardware-Setup“ des MERLIC RTE Setups verfügbar ist.

Anforderungen

MQTT-Broker und -Client

Wenn kein MQTT-Broker in Ihrem Netzwerk verfügbar ist, müssen Sie einen installieren und ausführen. Darüber hinaus muss mindestens ein MQTT-Client gestartet und verbunden werden.

Gültige Konfiguration

Sie müssen eine gültige Konfiguration mit mindestens einem Rezept für den Prozessintegrationsmodus definieren. Die Konfiguration kann im MERLIC RTE Setup festgelegt werden.

Prozessintegrationsmodus mit dem MQTT-Plugin verwenden

Sie müssen die folgenden Schritte ausführen, um den Prozessintegrationsmodus, d. h. das MERLIC RTE, mit dem MQTT-Plugin verwenden zu können:

1. Stellen Sie einen MQTT-Nachrichtenbroker auf Ihrem lokalen System oder über eine Remote-Verbindung bereit.
2. Stellen Sie einen MQTT-Client bereit, der Nachrichten zum Thema „merlic/action“ an den Broker sendet. Mit diesen Nachrichten kann MERLIC im Prozessintegrationsmodus gesteuert werden.
3. Starten Sie den Communicator, und konfigurieren Sie das MQTT-Plugin. Weitere Informationen finden Sie im Abschnitt Konfigurationsoptionen.
4. Starten Sie das MQTT-Plugin mit einer Verbindung zum MQTT-Nachrichtenbroker. Weitere Informationen finden Sie unter Starten des MQTT-Plugins.
5. Starten Sie MERLIC im Prozessintegrationsmodus mit einer Konfiguration, die mindestens ein gültiges Rezept enthält.
6. Optional: Senden Sie vom MQTT-Client aus Nachrichten zum Thema „merlic/action“ an den Broker, um MERLIC im Prozessintegrationsmodus zu steuern.
7. Optional: Stellen Sie einen MQTT-Client bereit, um die vom MQTT-Plugin veröffentlichten Nachrichten anzuzeigen und zu durchsuchen. Der Client kann der gleiche Client wie in Schritt 2 sein.

Nachdem das MQTT-Plugin gestartet wurde, werden automatisch Informationen zum aktuellen Zustand des MERLIC-Bildverarbeitungssystems erfasst. Das Plugin stellt außerdem automatisch eine Verbindung zu dem MQTT-Broker her, der im MERLIC RTE Setup im Abschnitt „MQTT Connection Details“ für die Plugin-Instanz definiert wurde. Das MQTT-Plugin veröffentlicht die Informationen von MERLIC in Nachrichten an die folgenden MQTT-Themen:

• merlic/mode
• merlic/preparedRecipeIds
• merlic/recipes
• merlic/runningJobId
• merlic/state

MERLIC wechselt vom Anfangszustand „Preoperational“ zu „Initialized“ und dann zu „Ready“, falls ein Standardrezept konfiguriert wurde. Im Zustand „Ready“ kann eine Einzelausführung des Bildverarbeitungssystems durch Veröffentlichung von {"actionType": "StartSingleJob"} im Thema „merlic/action“ ausgelöst werden. Eine kontinuierliche Ausführung kann mit {"actionType": "StartContinuous"} ausgelöst und mit {"actionType": "Stop"} beendet werden.

Beispiel für einen Veröffentlichungsdialog im MQTT Explorer

Weitere Informationen finden Sie unter Eingehende Nachrichten.

Im Prozessintegrationsmodus, d. h. während die MERLIC RTE-Anwendung ausgeführt wird, werden Ergebnisse von der MVApp vom MQTT-Plugin im Thema „merlic/recipes/0/result“ veröffentlicht:

• Wenn das MERLIC RTE ausgeführt wird, werden die Informationen vom MQTT-Plugin automatisch aktualisiert und gesendet.
• Wenn das MERLIC RTE nicht ausgeführt wird, werden keine Informationen erfasst. Das Plugin geht davon aus, dass sich das Bildverarbeitungssystem im Zustand „Halted“ befindet und die Rezeptliste leer ist.

Starten des MQTT-Plugins

Sie können das MQTT-Plugin über das MERLIC RTE Setup und über die Kommandozeile starten.

Über das MERLIC RTE Setup

Sie müssen zuerst sicherstellen, dass der Communicator ausgeführt wird, bevor Sie das MERLIC RTE Setup starten.

• Öffnen Sie das Menü der MQTT-Plugin-Instanz über das Symbol , und klicken Sie auf „ Starten“.
• Alternativ können Sie die MQTT-Plugin-Instanz auf der linken Seite auswählen und auf die Schaltfläche „ Start plug-in“ unten im MERLIC RTE Setup klicken.

Über die Kommandozeile

Öffnen Sie eine Eingabeaufforderung, wechseln Sie in das Verzeichnis „bin\x64-win64“ in der MERLIC-Installation, und geben Sie den folgenden Befehl ein:

merlic_communicator.exe --plugin MQTT

Weitere Informationen zu anderen Kommandozeilenoptionen und den Nebeneffekten beim Starten eines Plugins über die Kommandozeile finden Sie unter Communicator und Plugins starten.

Rezepte laden und ändern

Falls ein Standardrezept konfiguriert wurde, wird es geladen, und MERLIC wechselt vom Anfangszustand „Preoperational“ zu „Initialized“ und dann zu „Ready“. Ohne Standardrezept verbleibt MERLIC nach dem Start im Zustand „Initialized“. Sie können das erste Rezept laden, in dem Sie mit einem MQTT-Client die folgende JSON-Nachricht im Thema „merlic/action“ veröffentlichen. Das MQTT-Plugin erhält die Nachricht automatisch.

{
    "actionType": "PrepareRecipe",
    "recipeId": "0"
}

Andere Rezepte können nur geladen werden, wenn sich MERLIC im Zustand „Ready“ befindet.

Konfigurationsoptionen

Um die Konfiguration des MQTT-Plugins zu überprüfen und zu bearbeiten, muss der Communicator ausgeführt werden; das Plugin darf aber nicht ausgeführt werden. Sie können mehrere Konfigurationen mit unterschiedlichen Einstellungen verwenden. Zum Konfigurieren sollte nur das MERLIC RTE Setup verwendet werden (siehe Beschreibung in den folgenden Abschnitten). Es ist jedoch möglich, die Einstellungen manuell in der Datei „MQTT.json“ zu überprüfen und zu ändern, z. B. wenn die Datei beschädigt ist.

Plug-in Parameters

Parameter dieses Typs stellen allgemeine Parameter für das Communicator-Plugin dar, die nicht im Konfigurationsbereich der Registerkarte „Kommunikation“ angepasst werden können. Sie können die Versionsnummer des Plugins, den aktuellen Parameterwert für die Log-Ebene, die Zugriffsebene des Plugins und die Einstellung für die Überprüfung der Plugin-Konfiguration anzeigen. Diese Werte müssen an anderen Stellen bzw. mit anderen Methoden festgelegt werden.

Version

Dieser Parameter zeigt die Versionsnummer an, die bei der Plugin-Implementierung definiert wurde. Er besteht aus einer Haupt-, Neben- und Wartungsversion. Sie wird auch beim Hinzufügen einer neuen Plugin-Instanz angezeigt. Die Version ist optional. Daher ist es möglich, dass bei der Implementierung keine Versionsnummer definiert wurde.

Log level

Dieser Parameter zeigt die Log-Ebene an, die für das MQTT-Plugin verwendet wird. Standardmäßig wird die Log-Ebene des Communicators verwendet („Info“). Das bedeutet, dass alle Meldungen mit dem Schweregrad „critical“, „error“, „warning“ und „info“, d. h. Meldungen für allgemeine unkritische Informationen, protokolliert werden.

Sie können auch eine andere Log-Ebene für den Communicator festlegen, die allgemein oder nur für eine bestimmte Plugin-Instanz gilt. Weitere Informationen finden Sie im Abschnitt Plugin mit einer bestimmten Log-Ebene starten unter Communicator-Plugins starten bzw. beenden im MERLIC-Handbuch.

Access level

Dieser Parameter zeigt die für das Plugin festgelegte Zugriffsebene an. Für das MQTT-Plugin ist die Zugriffsebene standardmäßig auf „monitor and control“ festgelegt, d. h., das Plugin kann „Ereignisse“ empfangen und „Aktionen“ senden. Die Zugriffsebene bestimmt die Berechtigung, die in der Implementierung des Plugin definiert wird. Die implementierte Berechtigung kann im MERLIC RTE Setup nicht angepasst werden. Es ist jedoch möglich, die Zugriffsebene des Plugins auf „monitor“ oder „control“ einzuschränken. Weitere Informationen finden Sie unter Communicator- und Plugin-Einstellungen ändern.

Supports rapid validation

Dieser Parameter zeigt an, ob das Plugin die umgehende Validierung der aktuellen Plugin-Konfiguration unterstützt. Für dieses Plugin ist das Kontrollkästchen aktiviert, d. h., dass eine „schnelle Validierung“ unterstützt wird. Das bedeutet, dass die Konfiguration des Plugins bei jeder Änderung eines bearbeitbaren Parameter auf der Registerkarte „Kommunikation“ des MERLIC RTE Setups überprüft wird. Wenn das Plugin keine „schnelle Validierung“ unterstützt, wird die Konfiguration des Plugins nur beim Speichern der Konfiguration überprüft.

User Parameters

Die „User parameters“ stellen die Parameter dar, die für das Plugin konfiguriert werden können. Sie werden in verschiedenen Kategorien angezeigt, die erweitert oder geschlossen werden können.

Die Parameter der einzelnen Kategorien werden in den folgenden Abschnitten beschrieben.

• MQTT Connection Details
• Authentication
• Topics & Messages
• Image Results
• Quality of Service (QoS)

MQTT Connection Details

Die Parameter in dieser Kategorie definieren die Verbindungseinstellungen für den MQTT-Broker. Wenn der MQTT-Broker auf Ihrem lokalen System am üblichen Port 1883 ausgeführt wird, kann die Standardkonfiguration ohne Änderungen verwendet werden. Derzeit werden zertifikatbasiertes SSL/TLS und TLS basierend auf vorinstallierten Schlüsseln nicht unterstützt.

Die folgende Abbildung veranschaulicht die verfügbaren Parameter für die MQTT-Verbindung mit der jeweiligen Standardeinstellung. Unter der Abbildung finden Sie eine ausführliche Beschreibung der Parameter.

Hostname

Dieser Parameter definiert den Hostnamen oder die IP-Adresse des MQTT-Brokers. Der Parameter ist standardmäßig auf „localhost“ festgelegt.

Port

Dieser Parameter definiert den Port, den der MQTT-Broker verwendet. Der Parameter ist standardmäßig auf 1883 festgelegt.

Authentication

Die Parameter in dieser Kategorie bieten die Möglichkeit, Benutzeranmeldeinformationen zu definieren, wenn Sie eine Verbindung zu einem MQTT-Broker herstellen möchten, für den eine Passwortauthentifizierung erforderlich ist.

Die folgende Abbildung veranschaulicht die verfügbaren Parameter für die Authentifizierung.

Authenticate with username/password

Dieser Parameter legt fest, ob eine Authentifizierung verwendet wird. Er ist standardmäßig nicht aktiviert, d. h., für die Verbindung zum MQTT-Broker werden keine Anmeldeinformationen angegeben.

Username

Dieser Parameter definiert den Benutzernamen für die Authentifizierung. Er kann nur festgelegt werden, wenn der Parameter „Authenticate with username/password“ aktiviert ist.

Password

Dieser Parameter definiert das Passwort für die Authentifizierung. Er kann nur festgelegt werden, wenn der Parameter „Authenticate with username/password“ aktiviert ist. Das Passwort ist standardmäßig nicht sichtbar und wird stattdessen mit Kreissymbolen dargestellt. Klicken Sie auf das Symbol , um das Passwort als Klartext anzuzeigen.

Topics & Messages

Die Parameter in dieser Kategorie definieren die Einstellungen für Nachrichten, die vom Communicator über das MQTT-Plugin gesendet werden. Die Nachrichten werden im JSON-Format veröffentlicht.

Die folgende Abbildung veranschaulicht die verfügbaren Parameter für die Themen und Nachrichten mit der jeweiligen Standardeinstellung. Unter der Abbildung finden Sie eine ausführliche Beschreibung der Parameter. Weitere Informationen zu den verfügbaren Themen und dem zugehörigen JSON-Schema finden Sie im Abschnitt Themenübersicht.

Topic prefix

Dieser Parameter definiert das Präfix für Themen, das vom Communicator zum Kennzeichnen von Nachrichten verwendet wird. Das Präfix ist standardmäßig auf „merlic“ festgelegt. Weitere Informationen finden Sie unter Ausgehende Nachrichten.

Compact JSON

Wenn dieser Parameter aktiviert ist, erfolgt die Ausgabe im JSON-Format ohne Leerräume und Zeilenumbrüche. Der Parameter ist standardmäßig bereits aktiviert.

JSON indentation level

Dieser Parameter definiert die JSON-Einzugsebene, d. h. die Anzahl der Leerzeichen, die in JSON-Nachrichten verwendet werden. Diese Option ist nur verfügbar, wenn der Parameter „Compact JSON“ nicht aktiviert ist. Normalerweise wird eine Einzugsebene zwischen 2 und 4 verwendet. Der Parameter ist standardmäßig auf 2 festgelegt.

Publish errors

Wenn dieser Parameter aktiviert ist, werden die vom MERLIC RTE gemeldeten Fehler im Thema „merlic/error“ und den zugehörigen untergeordneten Themen veröffentlicht. Fehlermeldungen werden nicht beibehalten, d. h., sie werden nur beim Auftreten des Fehlers an die Abonnenten der Themen gesendet. Der Parameter ist standardmäßig bereits aktiviert.

Publish recipe data

Wenn dieser Parameter aktiviert ist, wird die Rezeptliste im Thema „merlic/recipes“ veröffentlicht. Darüber hinaus wird für jedes Rezept ein boolescher Wert in einem Thema der Form „merlic/recipes/{id}/isPrepared“ veröffentlicht, wobei {id} die numerische Rezept-ID ist. Der boolesche Wert gibt an, ob das betreffende Rezept derzeit geladen ist. Diese Nachrichten werden beibehalten, damit Clients, die diese Themen abonniert haben, als das Plugin bereits ausgeführt wurde, die aktuellen Rezeptdaten erhalten. Der Parameter ist standardmäßig bereits aktiviert.

Publish result data

Wenn dieser Parameter aktiviert ist, werden neue Ergebnisse in Themen der Form „merlic/recipes/{id}/result“ und den zugehörigen untergeordneten Themen veröffentlicht, wobei {id} die numerische Rezept-ID des Rezepts ist, für das das Ergebnis generiert wurde. Ergebnismeldungen werden nicht beibehalten, d. h., sie werden lediglich bei der Ankunft des Ergebnisses an die Abonnenten der Themen gesendet. Der Parameter ist standardmäßig bereits aktiviert.

Publish result images

Dieser Parameter definiert, ob Ergebnisbilder der MVApp, die als Rezept ausgeführt wurde, abgerufen und veröffentlicht werden. Er ist nur verfügbar, wenn der Parameter „Publish result data“ aktiviert ist.

Wenn „Publish result images“ aktiviert ist, werden die Daten von erfolgreich abgerufenen Ergebnisbildern im Thema „{prefix}/recipes/{id}/result/images/{dataIndex}/data“ veröffentlicht. Dieses Thema ist das einzige, das keine JSON-Nachrichten überträgt.

{dataIndex} bezieht sich auf den numerischen (0-basierten) Index des entsprechenden Bildergebnisses der MVApp. Wenn Ergebnisbilder veröffentlicht werden sollen, haben Sie die Möglichkeit, einige weitere Einstellungen für die Ergebnisbilder anzugeben, z. B. Filtermodus oder das Nutzdatenformat für die Bilddaten. Die betreffenden Parameter befinden sich zusammen mit anderen Konfigurationsoptionen für Ergebnisbilder in der Kategorie „Image Results“.

Wenn das Bild nicht abgerufen werden kann, weil es beispielsweise nicht mehr in MERLIC gespeichert oder die Konvertierung in das gewünschte Format fehlgeschlagen ist, wird der Fehler in „{prefix}/recipes/{id}/result/images/{dataIndex}/error“ veröffentlicht. Dieses Thema verwendet das gleiche error.json-Schema, das bereits vom Thema „{prefix}/error“ verwendet wird.

Standardmäßig ist der Parameter nicht aktiviert, sodass keine Ergebnisbilder veröffentlicht werden.

Image Results

Die Parameter in dieser Kategorie definieren, wie Ergebnisbilder veröffentlicht werden. Sie können nur dann konfiguriert werden, wenn der Parameter „Publish result images“ in der Kategorie „Topics & Messages“ aktiviert ist.

Image result filter mode

Dieser Parameter bietet die Möglichkeit, einen Filter zu aktivieren, der bestimmt, welche Bildergebnisse abgerufen werden. Zur Auswahl stehen folgende Optionen. Die Standardeinstellung ist „None“.

Result name filter regex

Dieser Parameter bietet die Möglichkeit, einen regulären Ausdruck zum Filtern der Namen von Ergebnisbildern anzugeben, die veröffentlicht werden sollen. Er ist nur verfügbar, wenn der Filtermodus im Parameter „Image result filter mode“ auf „Regular expression“ festgelegt ist. Es werden dann nur Ergebnisbilder veröffentlicht, deren Name dem regulären Ausdruck entspricht. Die Standardeinstellung ist „.*“ (jeder Name entspricht dem regulären Ausdruck).

Payload format for image data

Dieser Parameter definiert, wie die eigentlichen Bilddaten im MQTT-Thema veröffentlicht werden sollen. Der Parameter ist standardmäßig auf „Data URI (base64)“ festgelegt.

Image format

Dieser Parameter definiert das Format, in dem Ergebnisbilder der MVApp veröffentlicht werden. Das ausgewählte Format wird blau hervorgehoben. Um ein anderes auszuwählen, klicken Sie auf das gewünschte Bildformat. Abhängig vom ausgewählten Bildformat können weitere Parameter konfiguriert werden. Weitere Informationen zu den verfügbaren Bildformaten finden Sie in der folgenden Tabelle. Die Standardeinstellung ist „JPEG“.

Im Allgemeinen können alle Bilder der Typen „byte“, „int1“, „uint2“, „int2“, „int4“, „int8“ und „real“ als MVApp-Ergebnis exportiert und in die verfügbaren Bildformat konvertiert werden. Bilder des Typs „real“ sind jedoch eine Ausnahme, da sie nur in das Format „HALCON Serialized Item“ konvertiert werden können. Weitere Informationen zu den Bildformaten und der jeweiligen Pixeltransformation finden Sie im Abschnitt Bildergebnis auf der Seite Communicator-Plugins konfigurieren.

Use progressive JPEG

Dieser Parameter ist nur verfügbar, wenn der Parameter „Image format“ auf „JPEG“ festgelegt ist. Er legt fest, ob die Bilder als progressives JPEG veröffentlicht werden. Der Parameter ist standardmäßig nicht aktiviert.

JPEG quality

Dieser Parameter ist nur verfügbar, wenn der Parameter „Image format“ auf „JPEG“ festgelegt ist. Er definiert die Komprimierungsqualität für JPEG in Prozent. Die Standardeinstellung ist 50 %.

PNG compression

Dieser Parameter ist nur verfügbar, wenn der Parameter „Image format“ auf „PNG“ festgelegt ist. Er definiert den Komprimierungsgrad für PNG. Er kann auf einen Wert zwischen 0 und 9 festgelegt werden. Die Standardeinstellung ist 6.

Image zoom mode

Dieser Parameter bietet die Möglichkeit, die Größe der Ergebnisbilder zu ändern. Die verfügbaren Optionen sind in der folgenden Tabelle aufgelistet. Abhängig vom ausgewählten Modus können weitere Parameter konfiguriert werden. Der Parameter ist standardmäßig auf „None“ festgelegt.

Image width

Dieser Parameter ist nur verfügbar, wenn der Parameter „Image zoom mode“ auf „Fixed width and height“ festgelegt ist. Er definiert die Breite der Ergebnisbilder. Hierdurch werden alle Bilder mit der in „Image width“ und „Image height“ angegebenen Größe veröffentlicht. Die angegebene Größe wird unabhängig von der jeweiligen Originalgröße auf alle Bilder angewendet, und das Seitenverhältnis wird nicht beibehalten. Die Standardeinstellung ist 512 px.

Image height

Dieser Parameter ist nur verfügbar, wenn der Parameter „Image zoom mode“ auf „Fixed width and height“ festgelegt ist. Er definiert die Höhe der Ergebnisbilder. Hierdurch werden alle Bilder mit der in „Image width“ und „Image height“ angegebenen Größe veröffentlicht. Die angegebene Größe wird unabhängig von der jeweiligen Originalgröße auf alle Bilder angewendet, und das Seitenverhältnis wird nicht beibehalten. Die Standardeinstellung ist 512 px.

Image zoom factor

Dieser Parameter ist nur verfügbar, wenn der Parameter „Image zoom mode“ auf „Zoom factor“ festgelegt ist. Er definiert den Prozentwert, auf dessen Basis die Größe der Bilder in beiden Dimensionen geändert wird. Sie können auch einen Wert größer als 100 % angeben. Der Parameter ist standardmäßig auf 100 % festgelegt, das heißt, die ursprüngliche Bildgröße wird beibehalten.

Quality of Service (QoS)

Die Parameter in dieser Kategorie definieren das Verhalten des Brokers, wenn bei der Übertragung Pakete verloren gehen, z. B. aufgrund von Datenübertragungsfehlern oder Netzwerküberlastung.

Die einzelnen Parameter können jeweils auf die Werte 0, 1 oder 2 festgelegt werden. Die ausgewählten Werte werden blau hervorgehoben. Um andere auszuwählen, klicken Sie auf die gewünschten Werte. Die folgende Tabelle enthält eine Übersicht über die Bedeutung der Werte.

Die folgende Abbildung veranschaulicht die verfügbaren Parameter mit der jeweiligen Standardeinstellung. Unter der Abbildung finden Sie eine ausführliche Beschreibung der Parameter.

QoS for status updates

Dieser Parameter definiert die QoS für Statusaktualisierungen. Die Standardeinstellung ist 1.

QoS for errors

Dieser Parameter definiert die QoS für Fehlermeldungen. Die Standardeinstellung ist 2. Dieser Parameter ist nur verfügbar, wenn der Parameter „Publish errors“ aktiviert ist.

QoS for updates of the recipe list

Dieser Parameter definiert die QoS für Aktualisierungen der Rezeptliste. Die Standardeinstellung ist 2. Dieser Parameter ist nur verfügbar, wenn der Parameter „Publish recipe data“ aktiviert ist.

QoS for the delivery of new results

Dieser Parameter definiert die QoS für die Übermittlung neuer Ergebnisse. Die Standardeinstellung ist 0. Dieser Parameter ist nur verfügbar, wenn der Parameter „Publish result data“ aktiviert ist.

MQTT-Themen abonnieren

Eingehende Nachrichten

Das MQTT-Plugin abonniert automatisch das Thema „merlic/action“. Wird das Plugin jedoch mit der Zugriffsebene „monitor“ gestartet, wird dieses Thema nicht abonniert. Falls das Plugin mit der Zugriffsebene „control“ gestartet wird, werden keine Nachrichten in diesem Thema veröffentlicht. Sie können einen beliebigen MQTT-Client verwenden, um die Ausführung von MERLIC zu steuern, indem Sie die folgenden actionType-Nachrichten an das Thema „merlic/action“ senden:

• SelectMode
• PrepareRecipe
• UnprepareRecipe
• StartSingleJob
• StartContinuous
• Halt
• Reset
• Stop
• Abort

Beispiele und weitere Informationen

Laden und Entladen eines Rezepts

Laden eines Rezepts:

Kopieren

{
  "actionType": "PrepareRecipe",
  "recipeId": "3"
}

Entladen eines Rezepts:

Kopieren

{
  "actionType": "UnprepareRecipe",
  "recipeId": null
}

Ausführung starten

Ausführung starten

Starten der kontinuierlichen Ausführung einer MVApp mit einem Rezept:

Kopieren

{
  "actionType": "StartContinuous",
  "recipeId": "3"
}

Starten eines einzelnen Jobs:

Kopieren

{
  "actionType": "StartSingleJob"
}

Für beide Ausführungsmodi gilt, dass keine Rezept-ID angegeben werden muss, weil nur die MVApp, auf die in der aktuell geladenen Rezeptdatei verwiesen wird, ausgeführt werden kann. Wird die Rezept-ID angegeben, müssen Sie unbedingt die ID des aktuell geladenen Rezepts angeben, da sonst ein Fehler auftritt.

Ausführung mit Parameterwerten starten

Sie können Parameterwerte für die Ausführung angeben, wenn Sie die Parameterwerte überschreiben möchten, die im aktuell geladenen Rezept definiert sind (siehe folgende Beispiele).

Starten der kontinuierlichen Ausführung mit Parametern:

Kopieren

{
  "actionType": "StartContinuous",
  "parameters": [42, 3.141, "mvapp-parameter"]
}

Starten eines einzelnen Jobs mit Parametern:

Kopieren

{
  "actionType": "StartSingleJob",
  "parameters": [42, 3.141, "mvapp-parameter"]
}

Für die Spezifikation der Parameter gelten dieselben Regeln wie für den Parameter „MV_PARAM_START_PARAMS“, die auf der Seite Available Actions in der Referenzdokumentation der Communicator-API angegeben sind.

Die angegebenen Parameterwerte im JSON-Array müssen mit der Anzahl der in der Rezeptdatei definierten Werte übereinstimmen. Darüber hinaus muss eine verlustfreie Umwandlung des Array-Datentyps in den Datentyp des jeweiligen Parameterwerts im Rezept möglich sein.

Derzeit ist keine verlustfreie Umwandlung in den Datentyp REAL möglich. Daher wird empfohlen, den Datentyp LREAL für die betreffenden Parameter in der MVApp zu verwenden, anstatt dafür zu sorgen, dass diese Parameter beim Starten der Ausführung ebenfalls parametrisiert werden können.

Ausführung mit optionalen Metadaten starten

Beim Starten eines Jobs können Sie eine Mess-ID oder eine Teile-ID angeben

Kopieren

{
  "actionType": "StartSingleJob",
  "measId": "optional-measurement-id",
  "partId": "S/N-123456789"
}

„measId“ und „partId“ sind jeweils optional und können weggelassen oder explizit auf null gesetzt werden. Wenn sie festgelegt werden, wird in den Nachrichten, die in „merlic/recipes/{id}/result“ für die bei der Ausführung des Jobs erzeugten Ergebnisse veröffentlicht werden, darauf verwiesen.

Ausgehende Nachrichten

Das MQTT-Plugin veröffentlicht die Informationen von MERLIC im Prozessintegrationsmodus in Nachrichten an die folgenden MQTT-Themen:

• merlic/mode
• merlic/preparedRecipeIds
• merlic/recipes
• merlic/runningJobId
• merlic/state

Sie können Nachrichten, die vom MQTT-Plugin veröffentlicht wurden, mit einem beliebigen MQTT-Client abonnieren.

Alle Themen beginnen mit dem Platzhalter {prefix}, der durch einen konfigurierbaren Präfixpfad für die jeweiligen Themen- und Nachrichteneinstellungen ersetzt werden muss. Für das MQTT-Plugin ist dies standardmäßig merlic, z. B. „merlic/state“. Die Konfiguration eines benutzerdefinierten Präfix erleichtert die Integration der Bildverarbeitungsanwendung in bestehende Themenhierarchien und ermöglicht den gleichzeitigen Betrieb mehrerer verschiedener Bildverarbeitungsanwendungen über denselben MQTT-Broker.

Weitere Informationen zum Konfigurieren der Informationsebene finden Sie im Abschnitt MQTT-Plugin.

Beispiele

Nachricht an das Thema „merlic/recipes/0/result“ (wenn „Compact JSON“ deaktiviert ist):

Kopieren

{
  "id": 111,
  "recipeId": "0",
  "jobId": 111,
  "measId": "measurement-42",
  "partId": null,
  "timestamp": "2024-02-05T15:12:27.699Z",
  "processingTimes": {
    "executionStartTime": "2024-02-05T15:12:27.528Z",
    "executionEndTime": "2024-02-05T15:12:27.698Z",
    "acquisitionDurationMillis": 0.368,
    "processingDurationMillis": 168.952
  },
  "resultState": "Completed",
  "content": [
     {
      "name": "Match_Result",
      "value": true
    },
    {
      "name": "Match_Confidence",
      "value": 0.99
    },
    {
      "name": "Detected_Part_Number",
      "value": "B21TA9322"
    }
  ]
}

Beibehaltene Nachrichten

Das MQTT-Plugin markiert einige Nachrichten automatisch als beibehalten, um Abonnenten über den aktuellen Status und die Liste der Rezepte zu informieren. Ein Client erhält die beibehaltene Nachricht, sobald er das Thema abonniert (auch wenn das Plugin die Nachricht vor der Abonnierung veröffentlicht hat). Dieses Verhalten gilt nur für zustandsähnliche Informationen. Ereignisähnliche Informationen wie Fehler und neue Ereignisse werden nicht beibehalten.

Themenübersicht

Die folgende Tabelle enthält eine Liste aller verfügbaren Themen mit dem jeweils zugehörigen JSON-Schema.

JSON-Schemas

action.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "actionType": {
      "enum": [
        "SelectMode",
        "PrepareRecipe",
        "UnprepareRecipe",
        "StartSingleJob",
        "StartContinuous",
        "Halt",
        "Reset",
        "Stop",
        "Abort"
      ]
    }
  },
  "required": [
    "actionType"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "actionType": {
            "const": "SelectMode"
          }
        }
      },
      "then": {
        "properties": {
          "mode": {
            "enum": [
              "Automatic",
              "FrontendAccess"
            ]
          }
        },
        "required": [
          "mode"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "actionType": {
            "const": "PrepareRecipe"
          }
        }
      },
      "then": {
        "properties": {
          "recipeId": {
            "type": "string"
          }
        },
        "required": [
          "recipeId"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "actionType": {
            "enum": [
              "UnprepareRecipe",
              "StartSingleJob",
              "StartContinuous"
            ]
          }
        }
      },
      "then": {
        "properties": {
          "recipeId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "actionType": {
            "enum": [
              "StartSingleJob",
              "StartContinuous"
            ]
          }
        }
      },
      "then": {
        "properties": {
          "measId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "partId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "parameters": {
            "anyOf": [
              {
                "type": "array"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    }
  ]
}

error.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 65535
    },
    "severity": {
      "enum": [
        "Warning",
        "Error",
        "Critical"
      ]
    },
    "cause": {
      "enum": [
        null,
        "SelectMode",
        "PrepareRecipe",
        "UnprepareRecipe",
        "StartSingleJob",
        "StartContinuous",
        "Halt",
        "Reset",
        "Stop",
        "Abort"
      ]
    },
    "brief": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "severity",
    "cause",
    "brief",
    "message"
  ]
}

error_brief.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "string"
}

error_code.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "integer",
  "minimum": 0,
  "maximum": 65535
}

error_message.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "string"
}

mode.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "enum": [
    null,
    "Automatic",
    "FrontendAccess"
  ]
}

preparedRecipeIds.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "array",
  "items": {
    "type": "string"
  }
}

recipes.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "$defs": {
    "recipe_parameters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "valueType": {
            "enum": [
              "Scalar",
              "Array"
            ]
          },
          "dataType": {
            "enum": [
              "Bool",
              "Int8",
              "UInt8",
              "Int16",
              "UInt16",
              "Int32",
              "UInt32",
              "Int64",
              "UInt64",
              "Float",
              "Double",
              "String",
              "Variant"
            ]
          }
        }
      }
    },
    "data_infos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      }
    }
  },
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "acquisitionSequence": {
        "type": ["string", "null"]
      },
      "inputs": {
        "$ref": "#/$defs/recipe_parameters"
      },
      "outputs": {
        "$ref": "#/$defs/recipe_parameters"
      },
      "outputData": {
        "$ref": "#/$defs/data_infos"
      }
    },
    "required": [
      "id",
      "inputs",
      "outputs",
      "outputData"
    ]
  }
}

recipes_isPrepared.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": "boolean"
}

result.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "$defs": {
    "scalar": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "timestampRfc3339": {
      "type": "string",
      "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-([0-2][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{1,3})Z$"
    }
  },
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 0
    },
    "recipeId": {
      "type": "string"
    },
    "jobId": {
      "type": "integer",
      "minimum": 1
    },
    "measId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "partId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "timestamp": {
      "$ref": "#/$defs/timestampRfc3339"
    },
    "processingTimes": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "executionStartTime": {
              "$ref": "#/$defs/timestampRfc3339"
            },
            "executionEndTime": {
              "$ref": "#/$defs/timestampRfc3339"
            },
            "acquisitionDurationMillis": {
              "type": "number"
            },
            "processingDurationMillis": {
              "type": "number"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "resultState": {
      "type": "string",
      "enum": [
        "Completed",
        "Processing",
        "Aborted",
        "Failed"
      ]
    },
    "content": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "anyOf": [
              {
                "$ref": "#/$defs/scalar"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/scalar"
                }
              }
            ]
          }
        },
        "required": [
          "name",
          "value"
        ]
      }
    }
  },
  "required": [
    "id",
    "recipeId",
    "jobId",
    "timestamp",
    "resultState",
    "content"
  ]
}

{

"$schema": "http://json-schema.org/schema#",

"$defs": {

"scalar": {

"anyOf": [

{

"type": "boolean"

},

{

"type": "number"

},

{

"type": "string"

}

]

}

},

"type": "object",

"properties": {

"id": {

"type": "integer",

"minimum": 0

},

"recipeId": {

"type": "string"

},

"jobId": {

"type": "integer",

"minimum": 1

},

"timestamp": {

"type": "string",

"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-([0-2][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]Z$"

},

"resultState": {

"type": "string",

"enum": [

"Completed",

"Processing",

"Aborted",

"Failed"

]

},

"content": {

"type": "array",

"items": {

"type": "object",

"properties": {

"name": {

"type": "string"

},

"value": {

"anyOf": [

{

"$ref": "#/$defs/scalar"

},

{

"type": "array",

"items": {

"$ref": "#/$defs/scalar"

}

}

]

}

},

"required": [

"name",

"value"

]

}

}

},

"required": [

"id",

"recipeId",

"jobId",

"timestamp",

"resultState",

"content"

]

}

result_content_value.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "$defs": {
    "scalar": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    }
  },
  "anyOf": [
    {
      "$ref": "#/$defs/scalar"
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/$defs/scalar"
      }
    }
  ]
}

runningJobId.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "type": ["null", "integer"]
}

state.json

Kopieren

{
  "$schema": "http://json-schema.org/schema#",
  "enum": [
    "Preoperational",
    "Halted",
    "Error",
    "Initialized",
    "Ready",
    "SingleExecution",
    "ContinuousExecution",
    "FrontendAccess"
  ]
}