MQTT-Plugin
Dieses Plugin ermöglicht die Verwendung von MQTT MQTT (Message Queuing Telemetry Transport) ist ein Netzwerkprotokoll für die Gerätekommunikation, insbesondere bei begrenzter Bandbreite. 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 Supervisory Control and Data Acquisition-System über TCP. Bei MQTT handelt es sich um ein offenes OASIS Organization for the Advancement of Structured Information Standards-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 MERLIC RTE Setup-Registerkarte „I/O“ 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 Runtime Environment Setup festgelegt werden.
Prozessintegrationsmodus mit dem MQTT-Plugin verwenden
Sie müssen die folgenden Schritte ausführen, um den Prozessintegrationsmodus, d. h. MERLIC RTE, mit dem MQTT-Plugin verwenden zu können:
- Stellen Sie einen MQTT-Nachrichtenbroker auf Ihrem lokalen System oder über eine Remote-Verbindung bereit.
- 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.
- Starten Sie MERLIC RTE mit einer Konfiguration, die mindestens ein gültiges Rezept aufweist, und konfigurieren Sie das MQTT-Plugin im MERLIC RTE Setup. Weitere Informationen finden Sie im Abschnitt Konfigurationsoptionen.
- Starten Sie das MQTT-Plugin mit einer Verbindung zum MQTT-Nachrichtenbroker. Weitere Informationen finden Sie unter MQTT-Plugin starten.
- Optional: Senden Sie vom MQTT-Client aus Nachrichten zum Thema „merlic/action“ an den Broker, um MERLIC RTE zu steuern.
- 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.
Weitere Informationen finden Sie im Abschnitt 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: Die Informationen werden vom MQTT-Plugin automatisch aktualisiert und gesendet.
MQTT-Plugin starten
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 MERLIC RTE ausgeführt wird. Wenn dies nicht der Fall ist, können Sie es im MERLIC RTE Setup starten. Gehen Sie dazu folgendermaßen vor:
- Ö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.
Vergewissern Sie sich, dass MERLIC RTE wie gewünscht konfiguriert ist, bevor Sie das MQTT-Plugin starten. Beim Hinzufügen einer Instanz des MQTT-Plugins im MERLIC RTE Setup wird die Plugin-Instanz beispielsweise mit der für MERLIC RTE definierten Log-Ebene hinzugefügt. Um Nachrichten zu protokollieren, die im MQTT-Nachrichtenbroker veröffentlicht werden, müssen Sie die Log-Ebene für MERLIC RTE auf „debug“ festlegen, bevor MERLIC RTE gestartet und die Plugin-Instanz hinzugefügt wird.
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 MERLIC RTE 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 Kommunikations-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 für die Plugin-Instanz an. Als Log-Ebene wird standardmäßig die Log-Ebene des jeweiligen MERLIC RTE-Prozesses festgelegt, wenn die Plugin-Instanz im MERLIC RTE Setup hinzugefügt wird.
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 Plugins definiert wird. Die Zugriffsebene kann im MERLIC RTE Setup nicht angepasst werden.
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
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.
Das Passwort wird unverschlüsselt gespeichert. Die TLS-Verschlüsselung wird derzeit nicht unterstützt.
Topics & Messages
Die Parameter in dieser Kategorie definieren die Einstellungen für Nachrichten, die vom MERLIC RTE ü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 MERLIC RTE zum Kennzeichnen von Nachrichten verwendet wird. Das Präfix ist standardmäßig auf „merlic“ festgelegt. Weitere Informationen finden Sie im Abschnitt 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“.
|
Modus |
Beschreibung |
|---|---|
|
None |
Es wird kein Filter angewendet und alle Ergebnisbilder werden abgerufen. |
|
Regular expression |
Es werden nur Ergebnisbilder abgerufen, deren Name dem im Parameter Result name filter regex angegebenen regulären Ausdruck entspricht. |
Result name filter regex
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.
|
Format |
Beschreibung |
|---|---|
|
Binary |
Die Bilddaten werden als binäre Rohdaten veröffentlicht. Dies ist die einfachste und effizienteste Option. Allerdings können viele MQTT-Clients keine Binärdaten verarbeiten oder anzeigen. |
|
Base64‑encoded string |
Die Bilddaten werden als base64-codierte Zeichenfolge veröffentlicht. Für die Darstellung der Daten als lesbarer Text (mit einer Größenzunahme von 33 %) wird die base64-Codierung verwendet. |
|
Data URI (base64) |
Die Bilddaten werden als base64-codierter Daten-URI veröffentlicht. Dabei wird ebenfalls die base64-Codierung verwendet. Die Nutzdaten werden jedoch mit einem Daten-URI-Protokollschema, das den MIME-Typ („image/jpeg“, „image/png“ oder „application/octet-stream“ für HALCON Serialized Item) enthält, als Präfix versehen. |
Image format
|
Format |
Beschreibung |
|---|---|
|
PNG |
|
|
JPEG |
Die Bilder werden als JPEG-Bilder veröffentlicht. Bei Auswahl dieses Formats werden die folgenden zusätzlichen Parameter verfügbar: |
|
HALCON Serialized Item |
|
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 Bildergebnisse unter Kommunikations-Plugins konfigurieren.
Use progressive JPEG
Dieser Parameter ist nur verfügbar, wenn der Parameter „Image format“ auf „JPEG“ festgelegt ist.
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.
|
Modus |
Beschreibung |
|---|---|
|
None |
|
|
Fixed width and height |
Die Bilder werden auf die in den Parametern Image width und Image height angegebene Größe skaliert. |
|
Zoom factor |
Die Größe der Bilder wird um den im Parameter Image zoom factor angegebenen Faktor geändert und entsprechend in beiden Dimensionen angepasst. |
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.
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.
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.
|
QoS-Wert |
Beschreibung |
|---|---|
|
0 |
Nachrichten werden unabhängig davon, ob sie bestätigt werden, nur ein Mal übermittelt („Fire-and-Forget“). |
|
1 |
Nachrichten werden mindestens ein Mal übermittelt, bis sie bestätigt werden („bestätigte Übermittlung“). |
| 2 |
Nachrichten werden genau ein Mal übermittelt („garantierte Übermittlung“). |
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
Ausführung starten
Ausführung starten
Starten der kontinuierlichen Ausführung einer MVApp mit einem Rezept:
{
"actionType": "StartContinuous",
"recipeId": "3"
}Starten eines einzelnen Jobs:
{
"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:
{
"actionType": "StartContinuous",
"parameters": [42, 3.141, "mvapp-parameter"]
}Starten eines einzelnen Jobs mit Parametern:
{
"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 unter Available Actions im Handbuch für die Entwicklung von Kommunikations-Plugins 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
{
"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 Themen und Nachrichten.
Beispiele
Nachricht an das Thema „merlic/recipes/0/result“ (wenn „Compact JSON“ deaktiviert ist):
{
"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.
|
Thema |
Beibehalten |
Beispiel |
JSON-Schema |
|---|---|---|---|
|
{prefix}/action |
n/v |
|
|
|
{prefix}/error |
✘ |
|
|
|
{prefix}/error/brief |
✘ |
"brief error message" |
|
|
{prefix}/error/code |
✘ |
8565 |
|
|
{prefix}/error/message |
✘ |
"error message" |
|
|
{prefix}/mode |
✔ |
"Automatic", null |
|
|
{prefix}/preparedRecipeId |
✔ |
[], ["4"] |
|
|
{prefix}/recipes |
✔ |
|
|
|
{prefix}/recipes/{id}/isPrepared |
✔ |
false, true |
|
|
{prefix}/recipes/{id}/result |
✘ |
|
|
|
{prefix}/recipes/{id}/result/content/{idx}/value |
✘ |
5, 3.141592, "strings" |
|
|
{prefix}/recipes/{id}/result/images/{dataIndex}/data |
✘ |
"data:image/png;base64" |
Binary, base64 oder Data URI (base64) |
|
{prefix}/recipes/{id}/result/images/{dataIndex}/error |
✘ |
|
|
|
{prefix}/state |
✔ |
"SingleExecution" |
|
|
{prefix}/status/runningJobId |
✔ |
42, null |
JSON-Schemas
action.json
{
"$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"
}
]
}
}
}
}
]
}{
"$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"
]
}{
"$schema": "http://json-schema.org/schema#",
"type": "string"
}{
"$schema": "http://json-schema.org/schema#",
"type": "integer",
"minimum": 0,
"maximum": 65535
}{
"$schema": "http://json-schema.org/schema#",
"type": "string"
}{
"$schema": "http://json-schema.org/schema#",
"enum": [
null,
"Automatic",
"FrontendAccess"
]
}{
"$schema": "http://json-schema.org/schema#",
"type": "array",
"items": {
"type": "string"
}
}{
"$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"
]
}
}{
"$schema": "http://json-schema.org/schema#",
"type": "boolean"
}{
"$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
{
"$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"
}
}
]
}{
"$schema": "http://json-schema.org/schema#",
"type": ["null", "integer"]
}{
"$schema": "http://json-schema.org/schema#",
"enum": [
"Preoperational",
"Halted",
"Error",
"Initialized",
"Ready",
"SingleExecution",
"ContinuousExecution",
"FrontendAccess"
]
}
