Waylay MQTT Broker Manager

What is the Waylay MQTT Broker

Waylay can host an auto-scaling high available MQTT broker for the sole purpose of terminating MQTTS connections with IoT gateways and to transport data to/from the Waylay Automation Engine.

This means that the Waylay MQTT broker is a broker that has been optimized for communication to and from the Waylay rules engine and cannot be used for any other purposes.



  • Mqtts mandatory (minimum SSL version 1.2)
  • username/password authentication only, no client certificates
  • Single MQTT connection per device
  • Maximum MQTT payload size is 128KB
  • By default we support QoS1
  • The payload should be JSON and should contain “resource” : “id” in the top level JSON payload. In most cases, the ‘{$id}’ will be the gateway id.



There will be 1 MQTT broker per tenant, meaning that a customer does not share the MQTT infrastructure with any other Waylay customer and therefore also isolated from any other tenants.

The Waylay MQTT broker requires unique keys per device, auto-generated by Waylay - see next paragraph. We maintain the following MQTT topic convention:

  • ‘waylay/{$id}/data’ , for letting the device to push data
  • ‘waylay/{$id}/commands’, for sending actuations

Where ‘{$id}’ is the unique Client ID that is generated by Waylay.

The payload should be JSON and should contain “resource” : “id” in the top level JSON payload. In most cases, the ‘{$id}’ will be the gateway id.

Managing IoT device connections

If you log in as administrator to your Waylay environment, you will find a purple tile like the one above. When you click it, it will open a new tab with an overview of all MQTT devices that have been provisioned and their current status (connected or not).


On this page, you can also manually provision new devices via the “ADD DEVICE” button.


As described before, the client ID, username, password are all auto-generated by Waylay when clicking this button. This information is also used in the data and command topics for that new device.

It is important to download and save the credentials offline. Once you click the ‘save’ button, there is no way to retrieve the password again via this interface. If you lost the password, the device will have to be re-provisioned.

Optionally, you can also define a subtopic per MQTT device. We only support 1 level subtopics: /waylay/subtopic/clientid/data or /waylay/clientid/data


Client id (__clientid), and the topic (__topic), are then passed as transient paramaters by the Waylay Broker to the Waylay Engine (i.e. they are not stored in the time series database nor message cache). You can then use a discovery template to make use of these values to for instance associate different device types to MQTT clients which are grouped by topic.

Bridging the MQTT broker with the Waylay Engine

The connection between the Waylay MQTT broker and the Waylay Engine can be established via the “Channels” tile.


This means that all data that is received on the Waylay MQTT broker will be forwarded to the Waylay Engine because this channel has been configured in such a way that it listens to the MQTT wildcard topic.

If you want, you can change the settings and update them. Please contact Waylay Support for the right configuration settings.


A really good tool to test the Waylay MQTT broker is using mqtt.fx