Konnektor erstellen

Konnektoren konfigurieren - Integration mit externen Diensten¶

Jedes in die Evrlast-Plattform integrierte Gerät kann sogenannte Konnektoren bedienen.

In der Geräte-Ansicht im Reiter Konfiguration können im Abschnitt Konnektoren mehrere sog. Konnektoren über den Button „Hinzufügen“ angelegt werden und später auch aktiviert werden.

Die Konnektoren ermöglichen es, die empfangenen Messwerte an beliebige Dienste weiterzuleiten.

Externer MQTT-Konnektor¶

Ein MQTT-Konnektor kann die empfangenen Sensordaten an aus dem Internet erreichbare MQTT-Broker weiterreichen. Hierzu werden die Verbindungsdaten und das gewünschte Topic, unter dem die Nachrichten publiziert werden sollen, festgelegt.

Eine Beispiel-Konfiguration zum Publizieren auf einem der Test-Broker (unverschlüsselt, mit Authentifizierung) von mosquitto.org kann wie folgt aussehen:

Konnektoren_erstellen

Unterstützt werden MQTT (unverschlüsselte Übertragung) und MQTTS (verschlüsselte Übertragung) MQTT-Broker, mit und ohne Authentifizierung am Broker über Benutzernamen und Passwort.

Verbindung im Konnektor direkt testen¶

Neben dem Button „Speichern" steht der Button „Verbindung testen" zur Verfügung. Damit lässt sich prüfen, ob die eingetragene Konfiguration funktioniert. MQTT Verbindung testen

So testen Sie die Verbindung:

Klicken Sie auf „Verbindung testen". Es öffnet sich das Fenster „MQTT Verbindung testen".
Das Fenster enthält eine vorausgefüllte Testnachricht im JSON-Format: in der gleichen Struktur wie reguläre Messwerte. Sie können die Nachricht bei Bedarf direkt im Fenster bearbeiten.
Über „Senden" wird die Testnachricht mit den aktuell im Formular eingetragenen Verbindungseinstellungen (Broker-Adresse, Port, Topic, Authentifizierung) auf dem angegebenen Topic veröffentlicht.
Eine Snackbar meldet anschließend zurück, ob die Veröffentlichung erfolgreich war oder fehlgeschlagen ist.

Kein vorheriges Speichern nötig

Der Test verwendet immer die aktuell im Formular eingetragenen Parameter. Geänderte Werte müssen dafür nicht zuerst gespeichert werden. So können Sie verschiedene Einstellungen schnell ausprobieren, bevor Sie den Konnektor endgültig speichern.

Evrlast MQTT Broker¶

Der Evrlast MQTT Broker ist ein von uns betriebener MQTT-Broker, über den Sie die Messdaten Ihrer Geräte direkt aus der Evrlast Cloud per MQTT abonnieren können. Anders als beim externen MQTT-Konnektor müssen Sie keinen eigenen Broker bereitstellen - die Verbindungsdaten werden automatisch erzeugt, sobald Sie den internen Konnektor an einem Gerät aktivieren.

Pro aktiviertem Gerät stellt der Evrlast MQTT Broker ein eindeutiges Topic bereit, auf dem alle neuen Messwerte des Geräts in Echtzeit publiziert werden. Sie verbinden sich mit Ihrem API Key (Erstellen eines API-Keys) als Zugangsdaten und können die Nachrichten in beliebigen MQTT-Clients (z. B. MQTT Explorer, MQTTX, mosquitto_sub, Node-RED, Home Assistant) weiterverarbeiten.

Evrlast MQTT Broker an einem Gerät aktivieren¶

Öffnen Sie in der Evrlast Plattform die Geräte-Ansicht und wechseln Sie in den Reiter Konfiguration.
Scrollen Sie zum Abschnitt Konnektoren und legen Sie über den Button „Hinzufügen" einen neuen Konnektor vom Typ Evrlast MQTT Broker an.
Aktivieren Sie den Konnektor über den Schalter Aktiv. Direkt nach dem Speichern erzeugt das System die Verbindungsdaten und zeigt sie unterhalb des Schalters an:
- Broker Adresse - die vollständige URL des Evrlast Brokers
- Protokoll - immer SSL (verschlüsselte Verbindung über Port 8883)
- URL - der Host des Brokers
- Port - 8883
- Topic - das gerätespezifische Topic, auf dem die Messwerte publiziert werden
Über die Kopieren-Buttons rechts neben jedem Feld übernehmen Sie die Werte direkt in Ihren MQTT-Client.

Zugangsdaten

Als Benutzername und Passwort für den Broker verwenden Sie Ihren persönlichen API Key sowie das zugehörige API Key Secret aus Ihrem Benutzerprofil. Sie sehen Ihre vorhandenen Keys oder erstellen einen neuen Key über die Anleitung Erstellen eines API-Keys.

Nachrichtenformat¶

Pro Messwert publiziert der Evrlast Broker eine JSON-Nachricht auf dem gerätespezifischen Topic. Das Format entspricht dem des externen MQTT-Konnektors:

{
    "date": "2024-09-01T15:11:44.000+00:00",
    "deviceId": "6543892042e2b408a20d76ab",
    "deviceName": "MeineStation",
    "sensorId": "66471f347e91111285eef3fc",
    "sensorName": "MeinSensor",
    "value": 9385.0,
    "unit": "mm"
}

Verbindung testen¶

Am einfachsten testen Sie die Verbindung mit einem grafischen MQTT-Client. Bewährt haben sich:

MQTT Explorer - https://mqtt-explorer.com
MQTTX - https://mqttx.app

Beide sind kostenlos, für Windows verfügbar und benötigen keine zusätzliche Konfiguration. Tragen Sie in der Verbindungsmaske die Werte aus dem Konnektor-Panel ein:

Feld im MQTT-Client	Wert
Protocol / Scheme	`mqtts` (TLS)
Host / URL	URL aus dem Konnektor
Port	`8883`
Username	Ihr API Key
Password	Ihr API Key Secret

Nach erfolgreichem Verbindungsaufbau abonnieren Sie das Topic aus dem Konnektor-Panel und erhalten ab dem nächsten Messwert die Nachrichten in Echtzeit.

Hinweis MQTT Explorer / GUI-Clients

In der Topic-Übersicht der meisten GUI-Clients wird nur der zuletzt empfangene Wert angezeigt. Die vollständige Nachrichten-Historie der aktuellen Sitzung finden Sie üblicherweise in einem separaten History- oder Messages-Panel des jeweiligen Clients.

HTTP-Webhook-Konnektor¶

Mit dem HTTP-Webhook-Konnektor sendet die Evrlast Cloud die empfangenen Messwerte per HTTPS POST an eine von Ihnen festgelegte Ziel-URL - zum Beispiel an eine eigene REST-API, eine Cloud-Funktion (Azure Functions, AWS Lambda), einen Automatisierungsdienst (Power Automate, Make, Zapier, n8n) oder einen Webhook-Endpunkt in Node-RED. Sie benötigen dafür keinen MQTT-Broker, sondern lediglich einen aus dem Internet erreichbaren HTTPS-Endpunkt.

HTTP-Webhook an einem Gerät einrichten¶

Öffnen Sie in der Evrlast Plattform die Geräte-Ansicht und wechseln Sie in den Reiter Konfiguration.
Scrollen Sie zum Abschnitt Konnektoren und legen Sie über den Button „Hinzufügen" einen neuen Konnektor vom Typ HTTP Webhook an.

Füllen Sie die Felder aus:

Feld	Beschreibung
Ziel-URL	Vollständige Adresse des Endpunkts, an den die Messwerte gesendet werden. Pflichtfeld. Die URL muss mit `https://` beginnen und einen gültigen Host (z. B. `example.com`, `localhost` oder eine IP-Adresse) enthalten. Port und Pfad sind optional, z. B. `https://api.example.com:8443/evrlast/messwerte`.
Benutzername	Optional. Ist ein Benutzername eingetragen, authentifiziert sich die Evrlast Cloud per HTTP Basic Auth am Endpunkt.
Passwort	Optional. Passwort für die Basic-Auth-Anmeldung.

Aktivieren Sie den Konnektor über den Schalter Aktiv und klicken Sie auf „Speichern".

Nur verschlüsselte Übertragung

Aus Sicherheitsgründen werden ausschließlich HTTPS-Ziele unterstützt. Unverschlüsselte http://-Adressen werden bereits bei der Eingabe abgelehnt. Der Endpunkt muss ein gültiges, vertrauenswürdiges TLS-Zertifikat besitzen.

Passwort ändern oder beibehalten

Das Passwort wird verschlüsselt gespeichert und nach dem Speichern nicht wieder angezeigt. Lassen Sie das Feld Passwort bei späteren Änderungen am Konnektor (z. B. einer neuen Ziel-URL) einfach leer - das bisher gespeicherte Passwort bleibt dann erhalten. Tragen Sie nur dann ein Passwort ein, wenn Sie es neu setzen möchten.

Abonnement

Ob sich ein Konnektor aktivieren lässt, hängt von Ihrem Abonnement ab. Ist der Schalter Aktiv ausgegraut, ist die maximale Anzahl aktiver Konnektoren in Ihrem Abo erreicht oder Ihr Abo enthält keine Konnektoren.

Wie die Messwerte gesendet werden¶

Die Evrlast Cloud sendet Messwerte nicht einzeln, sondern fasst sie pro Konnektor zu Paketen zusammen. Das verringert die Anzahl der Anfragen an Ihren Endpunkt deutlich, wenn ein Gerät viele Sensoren auf einmal überträgt.

Ein Paket wird gesendet, sobald 50 Messwerte gesammelt wurden, oder
sobald seit dem letzten eingegangenen Messwert ca. 30 Sekunden lang keine neuen Werte hinzugekommen sind (die Übertragung des Geräts gilt dann als abgeschlossen).

Rechnen Sie daher mit einer Verzögerung von etwa 30 bis 40 Sekunden zwischen dem Eintreffen der Messwerte in der Evrlast Cloud und dem Aufruf Ihres Endpunkts.

Jede Anfrage hat folgende Eigenschaften:

Eigenschaft	Wert
Methode	`POST`
Header `Content-Type`	`application/json`
Header `Authorization`	`Basic …` - nur wenn ein Benutzername hinterlegt ist
Verbindungsaufbau	max. 5 Sekunden
Antwortzeit	max. 10 Sekunden

Nachrichtenformat¶

Der Inhalt (Body) der Anfrage ist immer ein JSON-Array - auch dann, wenn nur ein einzelner Messwert enthalten ist. Jedes Element hat dieselbe Struktur wie die Nachrichten der MQTT-Konnektoren:

[
    {
        "date": "2024-09-01T15:11:44.000+00:00",
        "deviceId": "6543892042e2b408a20d76ab",
        "deviceName": "MeineStation",
        "sensorId": "66471f347e91111285eef3fc",
        "sensorName": "Pegel",
        "value": 9385.0,
        "unit": "mm"
    },
    {
        "date": "2024-09-01T15:11:44.000+00:00",
        "deviceId": "6543892042e2b408a20d76ab",
        "deviceName": "MeineStation",
        "sensorId": "66471f347e91111285eef3fd",
        "sensorName": "Batteriespannung",
        "value": 3.61,
        "unit": "V"
    }
]

Feld	Bedeutung
`date`	Zeitpunkt der Messung (ISO 8601, UTC)
`deviceId` / `deviceName`	ID und Name des Geräts in der Evrlast Cloud
`sensorId` / `sensorName`	ID und Name des Sensors
`value`	Messwert als Zahl
`unit`	Einheit des Messwerts

Antwort Ihres Endpunkts¶

Ihr Endpunkt sollte jedes erfolgreich angenommene Paket mit einem HTTP-Statuscode aus dem Bereich 2xx (z. B. 200 OK oder 204 No Content) beantworten. Der Inhalt der Antwort wird nicht ausgewertet. Andere Statuscodes behandelt die Evrlast Cloud wie folgt:

Antwort	Verhalten der Evrlast Cloud
2xx	Paket gilt als zugestellt.
401 / 403 (Anmeldung fehlgeschlagen / kein Zugriff)	Paket wird verworfen, Fehler wird im Konnektor-Log vermerkt. Prüfen Sie Benutzername und Passwort.
429 (zu viele Anfragen)	Paket wird verworfen, Fehler wird im Konnektor-Log vermerkt.
Andere 4xx (z. B. 400, 404, 422)	Paket wird verworfen, da eine Wiederholung am Ergebnis nichts ändern würde. Fehler wird im Konnektor-Log vermerkt.
5xx, Zeitüberschreitung oder Verbindungsfehler	Paket wird später erneut gesendet (bis zu 5 Zustellversuche). Danach wird es verworfen.

Nach 10 aufeinanderfolgenden Fehlern legt der Konnektor eine kurze Sendepause ein, bevor er neue Messwerte wieder an Ihren Endpunkt weiterleitet.

Verworfene Pakete werden nicht nachgeliefert

Messwerte aus verworfenen Paketen werden nicht automatisch erneut gesendet. Sie bleiben aber selbstverständlich in der Evrlast Cloud gespeichert und können dort jederzeit eingesehen werden. Antworten Sie mit einem 5xx-Statuscode, wenn Ihr Endpunkt vorübergehend nicht verarbeiten kann und die Daten später erneut erhalten möchte.

Doppelte Messwerte erkennen

Bei Wiederholungen nach einem 5xx-Fehler oder einer Zeitüberschreitung kann es vorkommen, dass ein Paket Ihren Endpunkt mehrfach erreicht - etwa wenn Ihr Endpunkt die Daten bereits verarbeitet hat, die Antwort aber zu spät kam. Die Kombination aus sensorId und date identifiziert einen Messwert eindeutig und eignet sich zum Erkennen von Duplikaten.

Verbindung testen¶

Wie beim externen MQTT-Konnektor steht neben „Speichern" der Button „Verbindung testen" zur Verfügung:

Klicken Sie auf „Verbindung testen". Es öffnet sich das Fenster „HTTP Verbindung testen" mit einer vorausgefüllten Testnachricht im JSON-Format, die Sie bei Bedarf bearbeiten können.
Über „Senden" wird die Testnachricht mit den aktuell im Formular eingetragenen Einstellungen (Ziel-URL, Benutzername, Passwort) per POST an Ihren Endpunkt gesendet. Ein vorheriges Speichern ist nicht nötig.
Eine Snackbar meldet das Ergebnis. Der Test gilt nur dann als erfolgreich, wenn Ihr Endpunkt mit einem Statuscode 2xx antwortet - also nach denselben Regeln wie im regulären Betrieb. Bei einem Fehler nennt die Meldung die Ursache, z. B. falsche Zugangsdaten (401), fehlende Berechtigung (403), nicht gefundener Endpunkt (404) oder den zurückgegebenen HTTP-Statuscode. Bei bereits gespeicherten Konnektoren öffnet sich nach erfolgreichem Test zusätzlich das Konnektor-Log.

Unterschied zum regulären Versand

Die Testnachricht wird als einzelnes JSON-Objekt gesendet, nicht als Array wie im regulären Betrieb. Berücksichtigen Sie das, falls Ihr Endpunkt den Inhalt streng prüft.

Endpunkt ohne eigenen Server ausprobieren

Wenn Sie zunächst nur sehen möchten, welche Daten die Evrlast Cloud sendet, können Sie einen kostenlosen Test-Endpunkt wie https://webhook.site verwenden. Dort erhalten Sie eine persönliche HTTPS-Adresse, die Sie als Ziel-URL eintragen, und sehen alle eingehenden Anfragen direkt im Browser. Verwenden Sie solche öffentlichen Dienste nur für Tests und nicht für produktive Daten.

Konnektor-Log¶

Über das Symbol rechts neben den Buttons eines gespeicherten Konnektors öffnen Sie das Konnektor-Log. Dort sehen Sie fehlgeschlagene Zustellungen mit Zeitpunkt und Fehlerursache (z. B. falsche Zugangsdaten, nicht erreichbarer Endpunkt oder abgelehnte Anfrage mit HTTP-Statuscode).

Welcher Konnektor passt zu mir?¶

Alle Konnektor-Arten lassen sich pro Gerät parallel aktivieren. Welche Variante für Sie passt, hängt davon ab, wo die Daten weiterverarbeitet werden:

Anwendungsfall	Empfehlung
Sie möchten Messwerte mit eigenen Tools, Skripten oder Drittsystemen weiterverarbeiten und betreiben keinen eigenen MQTT-Broker.	Evrlast MQTT Broker
Sie betreiben bereits einen MQTT-Broker (z. B. im Firmennetz, in einer Smart-Home-Zentrale, in einem Industriegateway) und möchten die Evrlast-Messwerte dort einspeisen.	Externer MQTT-Konnektor
Sie möchten Messwerte an einen Dienst weiterleiten, der bereits eine MQTT-Anbindung hat (Node-RED, Home Assistant, Grafana via MQTT-Datasource etc.).	Evrlast MQTT Broker
Sie integrieren mehrere Datenquellen aus unterschiedlichen Systemen und wollen alle Nachrichten in einem zentralen, von Ihnen verwalteten Broker bündeln.	Externer MQTT-Konnektor
Sie betreiben eine eigene Web-Anwendung oder REST-API und möchten die Messwerte dort direkt entgegennehmen.	HTTP-Webhook
Sie möchten Messwerte an einen Automatisierungs- oder Cloud-Dienst übergeben, der Webhooks empfangen kann (Power Automate, Make, Zapier, n8n, Azure Functions, AWS Lambda etc.).	HTTP-Webhook
Sie sind sich unsicher und möchten möglichst schnell auf die Daten zugreifen.	Evrlast MQTT Broker

Kurz zusammengefasst:

Evrlast MQTT Broker = nichts selbst betreiben, sofort verbinden, Authentifizierung per API Key.
Externer MQTT-Konnektor = volle Kontrolle über den Broker, eigene ACLs/Topics, Integration in eine bestehende MQTT-Landschaft.
HTTP-Webhook = kein Broker nötig, Messwerte kommen gebündelt per HTTPS POST bei Ihrem Endpunkt an, Authentifizierung per Basic Auth.