MQTT
The API is relying on MQTT.
Clients / Brokers must support at least MQTT v5.x.
All MQTT clients must identify with a descriptive, unique client name.
Broker
Section titled “Broker”WAKU Care provides an own MQTT broker to which all clients should connect in order to send device data. It is reachable under the following URL:
mqtt.waku-robotics.com
Security
Section titled “Security”The MQTT broker is secured with TLS and username / password. Please contact WAKU Robotics in order to obtain login credentials.
Last Will Testament
Section titled “Last Will Testament”All clients must register a last will testament (LWT) with QoS level 1 (at least once) and the retained flag enabled.
A provider with a single client for all of their devices must send the LWT to the topic v2/providerId.
Providers with one client per device must send the LWT to the connection-topic of the device (format: v2/providerId/deviceId/connection).
The payload must be connection.schema.json with status: offline.
Note, that the last will testament will remain in the broker unless reset (since it is retained).
It is therefore good practice to send a payload of type connection.schema.json with status: online to the LWT topic when your client connects.
This way, you will ovewrite any retained LWT from previous runs and also let WAKU Care know that your connector is running.
Basic Topic structure
Section titled “Basic Topic structure”The topics must be of the following form: <majorApiVersion>/<provideId>/<WAKU-deviceId>/<topic>.
The character / is reserved as the topic separator.
The parts between the separator must contain only the following characters: A-Z, a-z, 0-9, -, .
| MQTT Topic Level | Description | Example |
|---|---|---|
| majorApiVersion | The major version of the API, preceded by “v” (currently v2) |
v2 |
| providerId | WAKU Robotics provides every data provider with a unique identifier: The providerId. The providerId is directly linked to a set of workspaces in WAKU Care. You can only send data for devices of the linked workspaces. |
4a1286d8 |
| deviceId | The deviceId identifies the device in WAKU Care. |
devicexa |
| topic | The message’s subtopic. | connection, order, error, or values |
The combination of providerId and deviceId defines to which workspace the data will be associated to.
Example
Section titled “Example”If your providerId is provider1, and your devices have IDs devicexa, devicexb, and devicexc in WAKU Care, then the base topics for your devices might look like this:
- Device 1:
/v2/provider1/devicexa - Device 2:
/v2/provider1/devicexb - Device 3:
/v2/provider1/devicexc
Error Logging
Section titled “Error Logging”We provide an error topic for all connectors.
You can subscribe at <majorApiVersion>/<providerId>/errorlog.
If one of the messages you sent leads to an error, you will be notified on this topic.
Examples include, using the wrong timestamp format in your messages.
However, we do not send error information when the validation of your messages fails since we assume you are either using a schema validator or a code generator.
The messages you will receive are of this type:
File: errorlog.schema.json
| Property | Type | Required | Description |
|---|---|---|---|
timestamp |
string | Yes | Timestamp in ISO8601 format when the error was sent |
sourceMsgId |
uint16 | Yes | MQTT Message ID of the message that caused the error |
sourceMsgTopic |
uint16 | Yes | Topic the message that caused the error was sent on |
message |
uint16 | Yes | The error message |