Skip to content

MQTT Interface

Jump to bottom
Daniel Stolpmann edited this page Apr 19, 2024 · 1 revision

Message Queuing Telemetry Transport (MQTT) is the primary interface to control FlowEmu. It is used for the communication between the FlowEmu core and the User Interface (UI), but can also be used to connect other software or even custom hardware to FlowEmu.

MQTT is a publish/subscribe protocol that uses a central message broker where clients connect to. By using MQTT, the performance of the FlowEmu core is not influenced by the number or behavior of the clients. Any message is only sent once to the broker and is then distributed to the clients. The FlowEmu core is not aware of the number of clients connected.

Topics

In MQTT, messages are organized in topics. In FlowEmu, all communication is sorted into two main topics:

  • get for messages from the core (to the UI)
  • set for messages (from the UI) to the core

Going into details, FlowEmu uses the following topics:

  • {get,set}/paths to get the current paths as JavaScript Object Notation (JSON) or to modify the paths by sending a modified JSON.
  • {get,set}/module/+ to get information about the modules that are currently in the graph as JSON or to add/modify a module by sending a JSON. The last level of the topic is the module ID.
  • {get,set}/module/+/+ to get or set the parameters and statistic values of the modules as raw values. The second last level of the topic is the module ID and the last level is the parameter or statistic ID.
  • get/module_library to get a list of the modules in the module library as JSON.
  • get/graphs to get the name of the graphs located in the config/graphs directory as JSON.
  • set/load to load the graph with the specified name.
  • set/save to save the current graph under the specified name.

Like in the MQTT specification, + stands for a wildcard at one level of the topic hierarchy.

Example

To demonstrate how FlowEmu can be controlled via MQTT using an external program, this section shows how a module parameter can be changed using the mosquitto_pub command-line tool. The tool needs to be available on your system. If it is not installed, please check how you can install it on your system.

For this example, we assume a simple graph as shown in the figure below.

Screenshot of an example graph

To obtain the module ID and parameter ID of a specific parameter, you can hover over the label on the left-hand side of the parameter. As shown in the figure below, a tooltip will appear after a short time that shows the module ID followed by the parameter ID separated by a full stop. We therefore know that the module ID in this example is fifo_queue and the parameter ID is buffer_size.

Screenshot of an example parameter

To change this parameter, we have to send the raw value to the set/module/+/+ topic. Assuming that FlowEmu is running on the local machine, we can do this using:

mosquitto_pub -h localhost -t "set/module/fifo_queue/buffer_size" -m "10"

The buffer size of the FIFO queue should now be set to 10 packets.

Recommended Tools

When working with the MQTT interface of FlowEmu, the following tools are recommended:

  • MQTT Explorer allows you to browse the MQTT topic hierarchy, to receive and send messages, and to visualize values in graphs.
Clone this wiki locally