MQTT

Die API basiert auf MQTT. Clients / Broker müssen mindestens MQTT v5.x unterstützen. Alle MQTT-Clients müssen sich mit einem aussagekräftigen, eindeutigen Client-Namen identifizieren.

Broker

WAKU Care stellt einen eigenen MQTT-Broker bereit, mit dem sich alle Clients verbinden sollen, um Gerätedaten zu senden. Er ist unter folgender URL erreichbar:

mqtt.waku-robotics.com

Sicherheit

Der MQTT-Broker ist über TLS sowie Benutzername / Passwort abgesichert. Bitte kontaktieren Sie WAKU Robotics, um Zugangsdaten zu erhalten.

Last Will Testament

Alle Clients müssen ein Last Will Testament (LWT) mit QoS Level 1 (at least once) und aktiviertem Retained-Flag registrieren.

Ein Anbieter mit einem einzelnen Client für alle seine Geräte muss das LWT an das Topic v2/providerId senden. Anbieter mit einem Client pro Gerät müssen das LWT an das Connection-Topic des Geräts senden (Format: v2/providerId/deviceId/connection).

Das Payload muss connection.schema.json mit status: offline sein.

Beachten Sie, dass das Last Will Testament im Broker verbleibt, sofern es nicht zurückgesetzt wird (da es retained ist). Es ist daher empfehlenswert, beim Verbindungsaufbau Ihres Clients ein Payload vom Typ connection.schema.json mit status: online an das LWT-Topic zu senden. Dadurch überschreiben Sie ein eventuell retained LWT aus vorherigen Durchläufen und teilen WAKU Care zugleich mit, dass Ihr Connector läuft.

Grundlegende Topic-Struktur

Die Topics müssen folgende Form haben: <majorApiVersion>/<provideId>/<WAKU-deviceId>/<topic>.

Das Zeichen / ist als Topic-Trennzeichen reserviert. Die Teile zwischen den Trennzeichen dürfen nur die folgenden Zeichen enthalten: A-Z, a-z, 0-9, -, .

MQTT Topic-Ebene	Beschreibung	Beispiel
majorApiVersion	Die Hauptversion der API, mit vorangestelltem “v” (aktuell v2)	v2
providerId	WAKU Robotics stellt jedem Datenanbieter eine eindeutige Kennung bereit: die providerId. Die providerId ist direkt mit einer Reihe von Arbeitsbereichen in WAKU Care verknüpft. Sie können nur Daten für Geräte der verknüpften Arbeitsbereiche senden.	4a1286d8
deviceId	Die deviceId identifiziert das Gerät in WAKU Care.	devicexa
topic	Das Subtopic der Nachricht.	connection, order, error, oder values

Die Kombination aus providerId und deviceId legt fest, welchem Arbeitsbereich die Daten zugeordnet werden.

Beispiel

Wenn Ihre providerId provider1 ist und Ihre Geräte in WAKU Care die IDs devicexa, devicexb und devicexc haben, könnten die Basis-Topics für Ihre Geräte wie folgt aussehen:

• Gerät 1: /v2/provider1/devicexa
• Gerät 2: /v2/provider1/devicexb
• Gerät 3: /v2/provider1/devicexc

Fehlerprotokollierung

Wir stellen für alle Connectoren ein Error-Topic bereit. Sie können <majorApiVersion>/<providerId>/errorlog abonnieren. Falls eine Ihrer gesendeten Nachrichten zu einem Fehler führt, werden Sie über dieses Topic benachrichtigt. Beispiele hierfür sind die Verwendung falscher Timestamp-Formate in Ihren Nachrichten. Wir senden jedoch keine Fehlerinformationen, wenn die Validierung Ihrer Nachrichten fehlschlägt, da wir davon ausgehen, dass Sie entweder einen Schema-Validator oder einen Code-Generator verwenden.

Die Nachrichten, die Sie erhalten, sind von folgendem Typ:

Datei: errorlog.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
timestamp	string	Ja	Zeitstempel im ISO8601-Format, zu dem der Fehler gesendet wurde
sourceMsgId	uint16	Ja	MQTT-Nachrichten-ID der Nachricht, die den Fehler ausgelöst hat
sourceMsgTopic	uint16	Ja	Topic der Nachricht, die den Fehler ausgelöst hat
message	uint16	Ja	Die Fehlermeldung