Topics

Here is a list of all subtopics, their message formats and their expected parameter configuration.

Subtopic name	Purpose	Implementation	Schema	QoS level	Retained Flag
connection		mandatory	connection.schema.json	1	true
errors		preferable	error.schema.json	0	false
order		preferable	order.schema.json	0	false
values		preferable	values.schema.json	0	false

Topic: Connection

File: connection.schema.json

Property	Type	Required	Description
timestamp	string	Yes	Timestamp in ISO8601 format (YYYY-MM-DDTHH:mm:ss.ssZ).
status	string	Yes	device status Possible values are: online, offline.

The connection topic for Device 1 would be (assuming its WAKU device-id is devicexa):

/v2/provider1/devicexa/connection

The JSON Schema contains a timestamp field which should represent the current time of the robot, if possible. The status field sets the status of the device to either online or offline. The message should use QoS level 1 (at least once) and be sent with the retained flag enabled.

Example Connection

To mark Device 1 as being online, the following message should be sent on /v2/provider1/devicexa/connection:

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

Topic: Errors

File: error.schema.json

Property	Type	Required	Description
timestamp	string	Yes	Timestamp in ISO8601 format (YYYY-MM-DDTHH:mm:ss.ssZ).
activeErrors	error[]	No

The errors topic for Device 1 would be

/v2/provider1/devicexa/errors

The JSON Schema contains a timestamp and a list of currently active errors (activeErrors). Errors do not have to be opened or closed explicitly. If an error is not active anymore, it is sufficient to remove it from the list and send the updated message.

Error

Property	Type	Required	Description
code	string	Yes	error code
title	string	Yes	short title for the error
component	string	No	source component of error
description	string	No	long description of the error
severity	integer	No	severity
parameters	JSON	No	parameters to the current error as key value pairs of any type
position	position	No	position at which the error occurred

The error itself must at least contain a code and a title. The code is usually a manufacturer and/or model specific identifier for the given error. Errors are identified by concatenating their code and title. This means, an error with the same code and title in the activeErrors list will not be tracked as an individual error. Once, an error with a given code and title is removed from the activeErrors list and sent to WAKU Care, another error with the same code and title will be counted as a new error. The severity is a number between 0 and 4 where 4 is the most severe error.

Position

File: position.schema.json

Property	Type	Required	Description
x	number	Yes	x position
y	number	Yes	y position
z	number	Yes	z position

Errors may contain a position. The position should determine a point in the robot’s coordinate system where the error occurred.

Example Errors

If Device 1 would have two active errors at a given time, you would send the following message to /v2/provider1/devicexa/errors:

{
  "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"
}

This means, that WAKU Care would register both errors as having started at 1:10 PM. Now suppose that the left motor stops having an error at 1:15 PM. In this case, you would send the following message to /v2/provider1/devicexa/errors:

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

This effectively removes the “Left motor stalled” error from the list of active errors for Device 1. Once all errors are resolved, send the following message to /v2/provider1/devicexa/errors:

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

Topic: Order

File: order.schema.json

Property	Type	Required	Description
id	string	Yes	unique order identification
status	string	Yes	order status Possible values are: pending, started, finished, cancelled, aborted.
timestamp	string	Yes	Timestamp in ISO8601 format (YYYY-MM-DDTHH:mm:ss.ssZ).
device_order_id	string	No	device-internal order identification
name	string	No	order name
parameters	JSON	No	parameters to the current mission as key value pairs of any type

The order topic for Device 1 would be

/v2/provider1/devicexa/order

Orders are identified using their id.

Orders can be started by sending a message with status = started. Once, the order is completed, the client can send a message with status = finished. The status cancelled means that an order was cancelled by a robot operator, while the status aborted means that the order had to be aborted due to technical reasons. For exmaple, an order may be aborted because the goal position could not be reached.

The name property serves as a means to group orders which correspond to the same mission. For example, a mission could be called “Transport pallet to Station D4”. Then, any order which is executing that mission should mention this name. This allows to perform analytics on orders later.

The timestamp should correspond to the actual robot time.

The parameters property offers the possibility to define an arbitrary set of parameters for a given order as a JSON object. This will be stored together with the remaining order metadata. For example, the mission “Transport pallet to Station D4” could be reprogrammed to take a parameter which determines where the pallet should be transported to, e.g., “Transport pallet”. Then, an order executing “Transport pallet” with parameter “destination: Station A2” could have the following content:

Example Order

If Device 1 would start an order “Transport pallet” you would send the following message to /v2/provider1/devicexa/order:

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

Once the order is finished, send the following message to /v2/provider1/devicexa/order:

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

Topic: Values

The values topic provides a way to send any kind of scalar data regarding a device. One example would be temperature measurements of an environmental sensor. Another example could be counting wheel rotations or measuring the rotations per minute of a turbine.

These values can be realtime values or aggregated.

File: values.schema.json

Property	Type	Required	Description
timestamp	string	Yes	Timestamp in ISO8601 format (YYYY-MM-DDTHH:mm:ss.ssZ).
values	value[]	Yes	The values to be set.
interval	string	No	If set, treat values as aggregated within the given interval.

The values topic for Device 1 would be

/v2/provider1/devicexa/values

The JSON Schema contains a timestamp and a list of values (values). If interval is not specified, WAKU Care treats the values as realtime data and appends each value in values to the device’s data. This is the fastest option and should be chosen for values that need to be sent frequently (e.g., every second).

If interval is set, WAKU Care will round the given timestamp to this interval. For example, if interval=600, the timestamp will be rounded into 10 minute buckets. Therefore, sending a timestamp, like 2024-02-27T13:23:41+0000 will be rounded to 2024-02-27T13:20:00+0000. If a value for the given device and the rounded timestamp exists already, it will be updated with the current one. This allows to send incomplete aggregates, which are computed on the device.

Value

File: value.schema.json

Property	Type	Required	Description
name	string	Yes	name of the metric
value	number	Yes	actual value
unit	string	Yes	unit of the value

The name can be chosen arbitrarily but should be kept constant for a given metric. The value can be any numerical value. The unit must be any of the following:

• Speed

  • mps: Meters per second
  • kmph: Kilometers per hour
  • mph: Miles per hour

• Angles

  • rad: Radians
  • deg: Degrees
  • 16segment: Unit circle divided into 16 segments

• Rotation

  • rpm: Rotations per minute

• Distance

  • m: Meters
  • cm: Centimeters
  • mm: Millimeters
  • in: Inches
  • ft: Feet
  • mi: Miles

• Pressure

  • pa: Pascal
  • hpa: Hectopascal
  • psi: Pounds per square inch
  • bar: Bar

• Temperature

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

• Power

  • w: Watt
  • kw: Kilowatt

• Energy

  • j: Joule
  • wh: Watthours
  • kw: Kilowatthours

• Ratio

  • percent: Percentage

• none: no unit

WAKU Care automatically handles the conversion between units of the same group. For example, if you send temperatures in Fahrenheit you can still read them later as Celsius or Kelvin without providing these converted values yourself.

This is an example message, setting 15-minute aggregated environmental data for Device 1 on topic /v2/provider1/devicexa/values

{
  "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 }
  ]
}