Topics

Hier finden Sie eine Liste aller Subtopics, ihrer Nachrichtenformate und der erwarteten Parameterkonfiguration.

Subtopic-Name	Zweck	Implementierung	Schema	QoS-Level	Retained-Flag
connection		obligatorisch	connection.schema.json	1	true
errors		empfohlen	error.schema.json	0	false
order		empfohlen	order.schema.json	0	false
values		empfohlen	values.schema.json	0	false

Topic: Connection

Datei: connection.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
timestamp	string	Ja	Zeitstempel im ISO8601-Format (YYYY-MM-DDTHH:mm:ss.ssZ).
status	string	Ja	Gerätestatus. Mögliche Werte sind: online, offline.

Das Connection-Topic für Gerät 1 wäre (unter der Annahme, dass seine WAKU-Geräte-ID devicexa lautet):

/v2/provider1/devicexa/connection

Das JSON-Schema enthält ein timestamp-Feld, das, wenn möglich, die aktuelle Zeit des Roboters abbilden sollte. Das Feld status setzt den Status des Geräts auf online oder offline. Die Nachricht sollte mit QoS Level 1 (at least once) und aktiviertem Retained-Flag gesendet werden.

Beispiel Connection

Um Gerät 1 als online zu markieren, sollte folgende Nachricht an /v2/provider1/devicexa/connection gesendet werden:

{ "status": "online", "timestamp": "2024-04-19T13:00:00.000Z" }

Topic: Errors

Datei: error.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
timestamp	string	Ja	Zeitstempel im ISO8601-Format (YYYY-MM-DDTHH:mm:ss.ssZ).
activeErrors	error[]	Nein

Das Errors-Topic für Gerät 1 wäre

/v2/provider1/devicexa/errors

Das JSON-Schema enthält einen timestamp und eine Liste aktuell aktiver Fehler (activeErrors). Fehler müssen nicht explizit geöffnet oder geschlossen werden. Ist ein Fehler nicht mehr aktiv, genügt es, ihn aus der Liste zu entfernen und die aktualisierte Nachricht zu senden.

Error

Eigenschaft	Typ	Erforderlich	Beschreibung
code	string	Ja	Fehlercode
title	string	Ja	Kurzer Titel für den Fehler
component	string	Nein	Auslösende Komponente des Fehlers
description	string	Nein	Ausführliche Beschreibung des Fehlers
severity	integer	Nein	Schweregrad
parameters	JSON	Nein	Parameter zum aktuellen Fehler als Schlüssel-Wert-Paare beliebigen Typs
position	position	Nein	Position, an der der Fehler aufgetreten ist

Der Fehler selbst muss mindestens einen code und einen title enthalten. Der code ist üblicherweise eine hersteller- und/oder modellspezifische Kennung für den jeweiligen Fehler. Fehler werden durch die Verknüpfung von code und title identifiziert. Das bedeutet, ein Fehler mit gleichem Code und Titel in der activeErrors-Liste wird nicht als eigenständiger Fehler nachverfolgt. Sobald ein Fehler mit einem bestimmten Code und Titel aus der activeErrors-Liste entfernt und an WAKU Care gesendet wurde, wird ein weiterer Fehler mit demselben Code und Titel als neuer Fehler gezählt. Der Schweregrad ist eine Zahl zwischen 0 und 4, wobei 4 der schwerwiegendste Fehler ist.

Position

Datei: position.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
x	number	Ja	x-Position
y	number	Ja	y-Position
z	number	Ja	z-Position

Fehler können eine position enthalten. Die Position sollte einen Punkt im Koordinatensystem des Roboters angeben, an dem der Fehler aufgetreten ist.

Beispiel Errors

Hätte Gerät 1 zu einem bestimmten Zeitpunkt zwei aktive Fehler, würden Sie folgende Nachricht an /v2/provider1/devicexa/errors senden:

{
  "activeErrors": [
    {
      "code": "Right motor stalled",
      "severity": 0,
      "title": "Right motor stalled"
    },
    {
      "code": "Left motor stalled",
      "severity": 0,
      "title": "Left motor stalled"
    }
  ],
  "timestamp": "2024-04-19T13:10:00.000Z"
}

Das bedeutet, dass WAKU Care beide Fehler als um 13:10 Uhr begonnen registrieren würde. Angenommen, der Fehler am linken Motor endet um 13:15 Uhr. In diesem Fall würden Sie folgende Nachricht an /v2/provider1/devicexa/errors senden:

{
  "activeErrors": [
    {
      "code": "Right motor stalled",
      "severity": 0,
      "title": "Right motor stalled"
    }
  ],
  "timestamp": "2024-04-19T13:15:00.000Z"
}

Dadurch wird der Fehler “Left motor stalled” effektiv aus der Liste der aktiven Fehler von Gerät 1 entfernt. Sobald alle Fehler behoben sind, senden Sie folgende Nachricht an /v2/provider1/devicexa/errors:

{
  "activeErrors": [],
  "timestamp": "2024-04-19T13:20:00.000Z"
}

Topic: Order

Datei: order.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
id	string	Ja	eindeutige Auftragskennung
status	string	Ja	Auftragsstatus. Mögliche Werte sind: pending, started, finished, cancelled, aborted.
timestamp	string	Ja	Zeitstempel im ISO8601-Format (YYYY-MM-DDTHH:mm:ss.ssZ).
device_order_id	string	Nein	gerätinterne Auftragskennung
name	string	Nein	Auftragsname
parameters	JSON	Nein	Parameter zum aktuellen Auftrag als Schlüssel-Wert-Paare beliebigen Typs

Das Order-Topic für Gerät 1 wäre

/v2/provider1/devicexa/order

Aufträge werden über ihre id identifiziert.

Aufträge können durch Senden einer Nachricht mit status = started gestartet werden. Sobald der Auftrag abgeschlossen ist, kann der Client eine Nachricht mit status = finished senden. Der Status cancelled bedeutet, dass ein Auftrag von einem Roboter-Operator abgebrochen wurde, während der Status aborted bedeutet, dass der Auftrag aus technischen Gründen abgebrochen werden musste. Zum Beispiel kann ein Auftrag abgebrochen werden, weil die Zielposition nicht erreicht werden konnte.

Die Eigenschaft name dient dazu, Aufträge zu gruppieren, die zur gleichen Mission gehören. Zum Beispiel könnte eine Mission “Transport pallet to Station D4” heißen. Jeder Auftrag, der diese Mission ausführt, sollte dann diesen Namen verwenden. Dies ermöglicht spätere Auswertungen über Aufträge.

Der timestamp sollte der tatsächlichen Roboterzeit entsprechen.

Die Eigenschaft parameters bietet die Möglichkeit, einen beliebigen Satz von Parametern für einen bestimmten Auftrag als JSON-Objekt zu definieren. Dieser wird zusammen mit den übrigen Auftragsmetadaten gespeichert. Zum Beispiel könnte die Mission “Transport pallet to Station D4” so umprogrammiert werden, dass sie einen Parameter akzeptiert, der bestimmt, wohin die Palette transportiert werden soll, z. B. “Transport pallet”. Ein Auftrag, der “Transport pallet” mit dem Parameter “destination: Station A2” ausführt, könnte dann folgenden Inhalt haben:

Beispiel Order

Würde Gerät 1 einen Auftrag “Transport pallet” starten, würden Sie folgende Nachricht an /v2/provider1/devicexa/order senden:

{
  "id": "a11",
  "status": "started",
  "timestamp": "2024-02-27T13:17:34+0000",
  "name": "Transport pallet",
  "parameters": {
    "destination": "Station A2"
  }
}

Sobald der Auftrag abgeschlossen ist, senden Sie folgende Nachricht an /v2/provider1/devicexa/order:

{
  "id": "a11",
  "status": "finished",
  "timestamp": "2024-02-27T13:20:41+0000",
  "name": "Transport pallet",
  "parameters": {
    "destination": "Station A2"
  }
}

Topic: Values

Das Values-Topic bietet eine Möglichkeit, beliebige skalare Daten zu einem Gerät zu senden. Ein Beispiel wären Temperaturmessungen eines Umweltsensors. Ein weiteres Beispiel wäre das Zählen von Radumdrehungen oder das Messen der Drehzahl einer Turbine.

Diese Werte können Echtzeitwerte oder aggregierte Werte sein.

Datei: values.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
timestamp	string	Ja	Zeitstempel im ISO8601-Format (YYYY-MM-DDTHH:mm:ss.ssZ).
values	value[]	Ja	Die zu setzenden Werte.
interval	string	Nein	Falls gesetzt, werden die Werte als innerhalb des angegebenen Intervalls aggregiert behandelt.

Das Values-Topic für Gerät 1 wäre

/v2/provider1/devicexa/values

Das JSON-Schema enthält einen timestamp und eine Liste von Werten (values). Ist interval nicht angegeben, behandelt WAKU Care die Werte als Echtzeitdaten und fügt jeden value aus values den Daten des Geräts hinzu. Dies ist die schnellste Option und sollte für Werte gewählt werden, die häufig gesendet werden müssen (z. B. jede Sekunde).

Ist interval gesetzt, rundet WAKU Care den angegebenen Zeitstempel auf dieses Intervall. Bei interval=600 wird der timestamp beispielsweise auf 10-Minuten-Intervalle gerundet. Ein gesendeter Zeitstempel wie 2024-02-27T13:23:41+0000 wird also auf 2024-02-27T13:20:00+0000 gerundet. Existiert für das angegebene Gerät und den gerundeten Zeitstempel bereits ein Wert, wird dieser mit dem aktuellen aktualisiert. Dies ermöglicht das Senden unvollständiger Aggregate, die auf dem Gerät berechnet werden.

Value

Datei: value.schema.json

Eigenschaft	Typ	Erforderlich	Beschreibung
name	string	Ja	Name der Metrik
value	number	Ja	tatsächlicher Wert
unit	string	Ja	Einheit des Werts

Der name kann frei gewählt werden, sollte aber für eine gegebene Metrik konstant bleiben. value kann ein beliebiger numerischer Wert sein. unit muss eine der folgenden sein:

• Geschwindigkeit

  • mps: Meter pro Sekunde
  • kmph: Kilometer pro Stunde
  • mph: Meilen pro Stunde

• Winkel

  • rad: Radiant
  • deg: Grad
  • 16segment: Einheitskreis, unterteilt in 16 Segmente

• Drehzahl

  • rpm: Umdrehungen pro Minute

• Distanz

  • m: Meter
  • cm: Zentimeter
  • mm: Millimeter
  • in: Zoll
  • ft: Fuß
  • mi: Meilen

• Druck

  • pa: Pascal
  • hpa: Hektopascal
  • psi: Pound-force per square inch
  • bar: Bar

• Temperatur

  • k: Kelvin
  • c: Celsius
  • f: Fahrenheit

• Leistung

  • w: Watt
  • kw: Kilowatt

• Energie

  • j: Joule
  • wh: Wattstunden
  • kw: Kilowattstunden

• Verhältnis

  • percent: Prozent

• none: keine Einheit

WAKU Care übernimmt automatisch die Umrechnung zwischen Einheiten derselben Gruppe. Senden Sie Temperaturen beispielsweise in Fahrenheit, können Sie diese später dennoch in Celsius oder Kelvin auslesen, ohne die umgerechneten Werte selbst bereitstellen zu müssen.

Dies ist ein Beispiel für eine Nachricht, die 15-minütig aggregierte Umweltdaten für Gerät 1 auf dem Topic /v2/provider1/devicexa/values setzt:

{
  "timestamp": "2025-04-01T11:07:38Z",
  "interval": 900,
  "values": [
    { "name": "temperature", "unit": "c", "value": 8.1 },
    { "name": "windspeed", "unit": "kmph", "value": 6.4 },
    { "name": "winddirection", "unit": "deg", "value": 63.0 },
    { "name": "pressure", "unit": "hpa", "value": 1014.4 }
  ]
}