Zum Hauptinhalt springen

Generic MQTT Connector

Connector-Details Generic​

Der Generic MQTT Connector ermöglicht es der Plattform, Daten zu veröffentlichen, entweder auf ihrem eigenen MQTT-Broker oder auf einem externen MQTT-Broker. Der Hauptunterschied im Vergleich zu einem MQTT Channel besteht darin, dass die Veröffentlichung entweder über die API oder die Rule Engine erfolgt und die Daten vor der Veröffentlichung umformatiert werden können. Das bietet den Vorteil, dass sowohl das Topic als auch das Datenformat an die Anforderungen eines externen Systems angepasst werden können.

⚠️ Es ist derzeit nicht möglich, den Generic MQTT Connector zum Abonnieren eines MQTT-Brokers zu verwenden.

Veröffentlichen von Daten auf dem plattforminternen MQTT-Broker​

Um Daten auf dem plattforminternen MQTT-Broker zu veröffentlichen, muss zunächst eine basicCredentialSetId erstellt werden. Dies muss derzeit über die API / Swagger am folgenden Endpunkt erfolgen: https://staging.yggio.net/swagger/#/BasicCredentialsSets/createBasicCredentialsSet

Schritte​

  1. Melden Sie sich mit Ihren Zugangsdaten bei Swagger an: https://staging.yggio.net/swagger/#/Authorization/login
  2. Kopieren Sie das Token.
  3. Gehen Sie oben rechts in Swagger und fügen Sie das Token im Feld "Authorize" ein.
  4. Navigieren Sie zum Endpunkt Basic Credential Set und erstellen Sie Ihren Benutzernamen und Ihr Passwort.
  5. Notieren Sie die zurückgegebene ID.

Diese Zugangsdaten (Benutzername, Passwort und ID) werden zusammen mit dem Topic von Ihrem externen System verwendet, um die veröffentlichten Daten zu abonnieren.

connector-details-1

Erforderliche Informationen​

Um einen Generic MQTT Connector einzurichten, geben Sie Folgendes an:

  • a. Basic Credential Set ID: Die ID des Basic Credential Set, das den MQTT-Benutzernamen und das Passwort definiert.

Externes System konfigurieren​

Um den plattforminternen MQTT-Broker zu abonnieren, konfigurieren Sie das externe System wie folgt:

  • a. MQTT broker URL: mqtt.staging.yggio.net
  • b. Port:
    • 8883 für sicheres TLS (dringend empfohlen)
    • 1883 für unverschlüsselte Daten
  • c. Topic: Das Basis-Topic für den plattforminternen MQTT-Broker kann nicht konfiguriert werden. Es lautet immer yggio/push/v1/<BasicCredentialsSetId>/#. Das Symbol # im Topic wird durch den Publish-Befehl durch eine geräte­spezifische eindeutige Kennung ersetzt.
  • d. MQTT username: Wie im Basic Credential Set festgelegt.
  • e. MQTT password: Wie im Basic Credential Set festgelegt.
  • f. MQTT version: Sie können entweder mit MQTT v3.1.1 oder MQTT v5 abonnieren.

Veröffentlichen von Daten auf einem externen MQTT-Broker​

Um Daten auf einem externen MQTT-Broker zu veröffentlichen, muss dieser zunächst so konfiguriert werden, dass er die von der Plattform veröffentlichten Daten annimmt, d. h. Topic, Benutzername und Passwort müssen konfiguriert und die Host-URL bekannt sein.

connector-details-2

Externes System konfigurieren​

Konfigurieren Sie das externe System wie folgt:

  • a. Port:
    • 8883 für sicheres TLS (dringend empfohlen)
    • 1883 für unverschlüsselte Daten
  • b. Topic: Das Basis-Topic, auf dem die Plattform Daten veröffentlichen soll. Der eigentliche Publish-Befehl hängt dann die geräteeigene eindeutige Kennung als Subtopic an das Topic an.
  • c. MQTT username: Der Benutzername.
  • d. MQTT password: Das Passwort.

Erforderliche Informationen​

Um einen Generic MQTT Connector zur Veröffentlichung auf einem externen MQTT-Broker einzurichten, geben Sie Folgendes an, wie im externen System konfiguriert:

  • a. MQTT broker URL: Die URL des MQTT-Brokers
  • b. Port: Die Portnummer
  • c. Topic: Das Basis-Topic, auf dem die Plattform Daten veröffentlichen soll.
  • c. MQTT username: Der Benutzername.
  • d. MQTT password: Das Passwort.

Verwendung des plattforminternen MQTT-Brokers als externer Broker​

Es ist möglich, den plattforminternen MQTT-Broker als externen Broker in der Generic-MQTT-Integration zu verwenden. Dies eröffnet einige interessante Anwendungsfälle:

  • Daten von einer Plattforminstanz an eine andere weitergeben.
  • Sensible Daten entfernen, bevor sie mit einem anderen Benutzer geteilt werden.
  • Command Buttons verwenden, um Ereignisse in der Plattform auszulösen.

Einrichtungsanleitung​

  1. Bei Swagger anmelden in der Plattforminstanz, an die Sie Daten veröffentlichen möchten, indem Sie die obigen Anweisungen befolgen. (Es kann dieselbe Instanz sein, in der Sie den Generic MQTT Connector konfigurieren.)

  2. Ein Basic Credential Set erstellen: https://staging.yggio.net/swagger/#/BasicCredentialsSets/createBasicCredentialsSet

  3. MQTT-Sub-Topics reservieren für alle IoT-Nodes, für die Sie Daten veröffentlichen möchten: https://staging.yggio.net/swagger/#/ReservedMqttTopics/createReservedMqttTopic

    • Das Topic muss der Struktur folgen: yggio/generic/v2/<unique identifier>

  4. Den Generic MQTT Connector erstellen mit folgender Konfiguration:

    • MQTT broker URL: mqtt.staging.yggio.net (oder eine andere Plattforminstanz)
    • Port: 8883 (Sicheres TLS)
    • Topic: yggio/generic/v2
    • MQTT username: Wie im Basic Credential Set festgelegt.
    • MQTT password: Wie im Basic Credential Set festgelegt.

Ergebnis​

Wenn Sie Daten veröffentlichen, wird ein neuer IoT-Node in der Plattform erstellt. Sie können dann:

  • Ihn mit bestimmten Benutzern teilen, oder
  • Einen benutzerdefinierten Übersetzer mit spezifischer Logik hinzufügen, um die eingehenden Daten zu verarbeiten.

Veröffentlichen von Daten mit dem Generic MQTT Connector​

In den obigen Abschnitten haben wir verschiedene Arten von Generic MQTT Connectors erstellt, aber noch keine Daten veröffentlicht. Um Daten zu veröffentlichen, müssen Sie entweder:

  1. Eine Send-MQTT-Action zu einer Regel in der Rule Engine hinzufügen, oder
  2. Einen Command direkt an den Connector über die API senden.

Eine Rule erstellen​

Die Verwendung der Rule Engine zur Veröffentlichung von Daten ist der häufigste Anwendungsfall für den Generic MQTT Connector.

Das Prinzip ist einfach:

  • Verwenden Sie einen beliebigen Trigger-Typ für die Regel.
  • Fügen Sie eine Send-MQTT-Action hinzu, die auf diesen Connector zeigt.
  • Bauen Sie in der Action das Topic und den Payload, den Sie veröffentlichen wollen, mit Platzhaltern für die Werte, die vom auslösenden Gerät kommen.

Einrichtungsanleitung​

  1. Gehen Sie zur Rule Engine und erstellen Sie eine Regel.
  2. Fügen Sie einen Trigger hinzu: Device updated, Missing expected report, oder Button, wenn Sie auf Anforderung aus einem Command Button-Widget veröffentlichen wollen.
  3. Fügen Sie optional eine Value-threshold-Bedingung hinzu, damit die Regel nur veröffentlicht, wenn der Wert relevant ist.
  4. Fügen Sie eine Send MQTT-Action hinzu und verbinden Sie sie mit dem Trigger oder mit dem Zweig der Bedingung, auf dem sie laufen soll.
  5. Wählen Sie in der Action den Generic MQTT Connector und füllen Sie aus:

  • Topic Das Sub-Topic, das an das Basis-Topic des Connectors angehängt wird. Da das Sub-Topic in der Regel pro Gerät eindeutig sein muss, sind gängige Optionen:

    • {{iotnode._id}}
    • {{iotnode.devEui}}
    • {{iotnode.secret}}

  • Payload Die zu veröffentlichende Nachricht. Platzhalter wie {{iotnode.temperature}} und {{diff.temperature}} werden vor dem Veröffentlichen ersetzt, sodass der Payload so geformt werden kann, wie das empfangende System es erwartet.

  1. Setzen Sie bei einer Action, die mit einer Bedingung verbunden ist, die Ausführungsrichtlinie: On enter, On exit oder Every event.

Sowohl das Topic als auch der Payload unterstützen die {{path}}-Platzhaltersyntax. Die vollständige Liste der Platzhalter und wofür sie stehen finden Sie unter Rule Engine.

Beispiel-Topics und -Payloads

Command Button als Trigger, um den Power Level auf 50 % zu setzen

Topic{{iotnode._id}}
Payload{"powerLevel":50}

Command Button als Trigger, um Power auf Aus zu setzen

Topic{{iotnode._id}}
Payload{"command":"off"}

Temperatur ins NGSI-LD-Format umformatieren

Topic{{iotnode.devEui}}
Payload{"temperature":{"value":{{iotnode.temperature}},"unit":"°C","type":"property"}}

LoRaWAN-Signalqualitätsparameter ins NGSI-LD-Format umformatieren

Topic{{iotnode.devEui}}
Payload{"rssi":{"value":{{iotnode.rssi}},"unit":"dB","type":"property"},"snr":{"value":{{iotnode.snr}},"unit":"dB","type":"property"},"frameCount":{"value":{{iotnode.frameCount}},"type":"property"},"spreadingFactor":{"value":{{iotnode.spreadingFactor}},"type":"property"}}

Der Payload ist die Nachricht selbst, das JSON muss also weder stringifiziert noch seine Anführungszeichen maskiert werden, wie es in der alten Rule Engine nötig war.

Command API​

Der Generic MQTT Connector veröffentlicht Daten, wenn er über die API einen sendDownlink-Befehl erhält. Hier ein Beispiel

curl --location --request PUT "https://staging.yggio.net/api/connectors/command" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{
        "command": "sendDownlink",
        "integrationName": "Generic",
        "connectorId": "<connector _id>",
        "data": {
            "mqttTopic": "subTopic",
            "message": "myMessage as stringified JSON"
        }
    }'